source: server/README.old @ 9c0279e

debianmacno-cupsweb
Last change on this file since 9c0279e was 30beeab, checked in by Jessica B. Hamrick <jhamrick@…>, 14 years ago

Remove "gutenbach-" from directory names and rename "gutenbach" to "gutenbach-server"

  • Property mode set to 100644
File size: 11.8 KB
Line 
1gutenbach
2    The SIPB MP3 Music Spooler
3
4We would love you forever if you took this README/INSTALL document and made
5a Debian package out of it.  That would be uber-awesome.  But otherwise, we're
6assuming that you just want to get gutenbach up and running on your own
7system.  Well, maybe we shouldn't assume that.
8
9
10What does gutenbach do?
11---------------------
12
13gutenbach is a music spooler.  As it turns out, streaming music is a hard
14problem, with lots of proprietary protocols, client and server software.
15All of these jiggety bits are kind of a pain to get working correctly,
16so, we built gutenbach on top of... a printer system.  It's very simple:
17you print an mp3 file to a special "printer", and it gets played on
18whatever speakers you're hooked up to.
19
20
21Prerequisites
22-------------
23
24You'll need a server hooked up to an audio system that you want to use, with
25Debathena installed on top of it.  Ubuntu Server Edition tends to work
26well.
27
28
29Installing gutenbach
30------------------
31
32
331. Configuring your sound
34
35If you're installing gutenbach on a server environment, it's highly likely
36that you have a bare bones audio setup and everything is muted.  Make sure
37your sound works!  One common problem is that the daemon user (the user which
38will be actually playing the songs, or the user that your lpd, the print server,
39will be running under), isn't in the group audio, and thus can't play
40anything. If you're on Ubuntu Desktop, you'll probably have pulse-audio
41installed, in which case you should add lpd to the pulse-audio group
42as well, and make pulse-audio a single, system-wide instance. See
43this URL for detailed instructions:
44
45    http://www.pulseaudio.org/wiki/SystemWideInstance
46
47
482. Install some prerequisite software
49
50On a vanilla Ubuntu server install, gutenbach will also need the following
51packages to work properly:
52
53    * mplayer
54    * libimage-exiftool-perl
55
56mpg123 can also be useful for testing, but is not strictly necessary.
57
58
593. Setup gutenbach
60
61The Git repository for gutenbach is located in:
62
63    /afs/sipb/project/sipbmp3/gutenbach.git
64
65Place this in /root/gutenbach; the remctl scripts will assume that the
66scripts can be found in this location.
67
68
694. Configure gutenbach
70
71gutenbach will send zephyrs during playback start and end.  Since you don't
72want to be spamming sipb-auto (which is the default zephyr class these
73are sent to), you should create a configuration file:
74
75    /etc/gutenbach-filter-config.pl
76
77That looks like:
78
79    $zephyr_class = "my-auto-class"
80    $host = "hostname"
81    $queue = "printername"
82
83XXX: Auto-detect hostname and invent a sane default zephyr class off of it.
84
85
865. Configure gutenbach init scripts
87
88gutenbach will attempt to drop some information into /var/run/gutenbach, which
89needs to exist and you can't simply mkdir since /var/run on Ubuntu is
90a tempfs. Thus, add the following lines to a new file, /etc/init.d/gutenbach:
91
92#!/bin/sh
93mkdir /var/run/gutenbach
94touch /var/run/gutenbach/status
95chmod 0777 /var/run/gutenbach/status
96
97You should also run these commands yourself. :-)
98
99XXX: Note from jhamrick: I would recomment actually setting this up as a nice startup script, with a switch case for {start|stop|restart} (where with stop you just remove the directory, and with restart you remove the directory and then recreate it).  Also, gutenbach won't actually run on startup unless there are scripts in the /etc/rc*.d directory, so we need to do:
100
101> ln -s ../init.d/gutenbach /etc/rc2.d/S61gutenbach
102> ln -s ../init.d/gutenbach /etc/rc3.d/S61gutenbach
103> ln -s ../init.d/gutenbach /etc/rc4.d/S61gutenbach
104> ln -s ../init.d/gutenbach /etc/rc5.d/S61gutenbach
105> ln -s ../init.d/gutenbach /etc/rc0.d/K39gutenbach
106> ln -s ../init.d/gutenbach /etc/rc1.d/K39gutenbach
107> ln -s ../init.d/gutenbach /etc/rc6.d/K39gutenbach
108
109XXX: We need better permissions for status. Also, quentin wants to put this
110file in AFS.
111
112
1136. Configure lpd
114
115You'll need to setup a printcap file so that your machine will be actually
116running a printer! The magic lines are:
117
118    :if=|/path/to/gutenbach-filter
119    :lp=/dev/null
120
121Which mean that we pipe the mp3 files through gutenbach-filter (which does
122the actual playing), and then dump the rest of the output into /dev/null,
123since we don't actually care about it.
124
125A standard printcap entry looks like this:
126
127printername
128  :server
129  :cm=Human Readable Printer Name
130  :lp=/dev/null
131  :if=|/path/to/gutenbach-filter
132  :sd=/var/spool/lpd/printername
133  :ml=0:mx=0:sh:sf
134  :create_files
135
136printcap is located in /etc/printcap, but you can also edit the symlink
137in /etc/lprng/printcap.
138
139In /etc/lprng/lpd.conf:
140
141    printcap_path=...
142
143add /etc/lprng/printcap to the beginning of the pathlist, so it looks like:
144
145    printcap_path=/etc/lprng/printcap:|/usr/lib/get_hesiod_pcap
146
147/etc/printcap will also work, assuming lprng doesn't do something funky
148in the future.
149
150WARNING: On a cluster machine, get_hesiod_pcap will clobber gutenbach
151because it sets all:all=someotherprinter, making lpr not see gutenbach.
152There are two ways of fixing this:
153
1541. Patch /usr/lib/get_hesiod_pcap to return a full pcap line instead
155of all when it gets "all" from stdin.
156
1572. Remove get_hesiod_pcap from the list.
158
159To check your modifications, and create the necessary files and folders,
160you should run:
161
162    checkpc -V -f
163
164(As root, of course). You might get a failure on a directory
165/var/spool/lpd/%P doesn't exist; simply mkdir it and run checkpc -V -f
166
167With recent versions of lprng, you will also need to make lpd less paranoid
168about accepting connections.  This usually means the following two changes:
169
170In /etc/lprng/lpd.perms:
171
172    REJECT NOT SERVER
173
174should be commented out, as:
175
176    #REJECT NOT SERVER
177
178You will also need to add this line in lpd.conf:
179
180    lpd_listen_port=515
181
182By default, printers don't allow other users to remove other people's print
183jobs.  For an MP3 spooler, however, this may be a desirable trait, especially
184if someone trys to rickroll you.  You can let everyone lprm jobs by
185commenting out the line:
186
187    REJECT SERVICE=M
188
189XXX: On scourge, ACCEPT SERVICE=M SAMEHOST SAMEUSER doesn't seem to work
190properly, so removing the REJECT line is a must!
191
192XXXXXX: gutenbach accepts no responsibility for social faux pas that may
193be committed with this system.  It is consider good etiquette, however,
194to clear the status file if you're on zsr.
195
196XXXXXXXX: Another note from jhamrick (09/2009): debathena-lprng does not start up with the system by default.  debathena developers are currently deciding whether to change this, but in the meantine you will want to do:
197
198> ln -s ../etc/init.d/debathena-lprng /etc/rc2.d/S60debathena-lprng
199> ^rc2^rc3
200> ^rc3^rc4
201> ^rc4^rc5
202> ln -s ../etc/init.d/debathena-lprng /etc/rc0.d/K40debathena-lprng
203> ^rc0^rc1
204> ^rc1^rc6
205
2067. Test, round one
207
208The first test you should do to make sure gutenbach is configured properly is
209to attempt to play an mp3 file locally, via lpr.  The command you should use
210is:
211
212    mit-lpr -Pprintername@localhost filename.mp3
213
214Note the "mit-" prefix; Debathena defaults to CUPS, which we have not set
215up yet.
216
217See below for troubleshooting tips.
218
219
2208. Test, round two
221
222The second test you should do is try playing an MP3 remotely. The appropriate
223command is:
224
225    mit-lpr -Pprintername@hostname filename.mp3
226
227(Once again, with "mit-").  See below for troubleshooting tips.
228
229
2309. Troubleshooting
231
232So, it didn't work.  How did it fail?
233
234----
235sending job 'ezyang@vivace+800' to asdfasdf@localhost
236 connecting to 'localhost', attempt 1
237 cannot open connection to localhost - No such file or directory
238----
239
240This means that lpd is not accepting connections properly.  Check to see
241if you configured lpd.perms and lpd.conf correctly.  Try rebooting lpd
242by pkill lpd && lpd.  Use nmap to check of port 515 is open, both on the
243local machine and on a remote machine.  Check if networking is working
244on the server.  Use netstat to see what programs are listening to port
245515, and from which hosts.  Check iptables.
246
247----
248lpr: The printer or class was not found.
249----
250
251You're using lpr, not mit-lpr.
252
253----
254(no output, but no sound)
255----
256
257It looks like you managed to send the file over.  To diagnose the problems
258further:
259
260    * Check the zephyr logs of the class gutenbach was configured to
261      send messages to:
262
263        - If you see a reasonably full and formatted message, that means
264          that either: 1. your volume is turned off, or 2. mplayer is
265          horribly broken (XXX: it probably isn't, but I don't know what
266          error message it gives in that case)
267
268          By the way, be sure to check both the *hardware* and the
269          *software* volume.
270
271        - If you see a blank zephyr, that means that gutenbach-filter died
272          trying to get a handle to /var/run/gutenbach/status and failing.
273          Check if you created the file correctly, and that daemon has
274          permissions to write to it. If you rebooted recently, check if
275          you have the appropriate init.d script setup.
276
277    * Otherwise, check /var/spool/lpd/printername/status.pr (most of all the
278      other files are useless, especially including log):
279
280        - If you see a Perl error, fix it. The most common cause is because
281          exiftools is not installed.
282
283    * Otherwise, double check the userland code in gutenbach-filter. XXX: There
284      are some edge-cases that don't give nice error messages, for example
285      the failed write to /var/run/gutenbach/status
286
287
28810. Deploying CUPS
289------------------
290
291The final step is to give your newfangled printer a cups.mit.edu record.
292In order to do this, you will need to ask IS&T for a Moira pcap entry
293request.  Send mail to hesreq@mit.edu, specifying that you are setting
294up a gutenbach clone, that you want a Moira pcap entry, the printer name
295and server name of your queue, and that you want hwtype=LOCAL,ka=1. It wouldn't
296hurt to also tell them where your print queue is, and a contact list.
297
298Once you get the pcap entry, ping sipb-cups@mit.edu to add your machine
299to the public list.
300
301Troubleshooting:
302
303----
304Send_auth_transfer: on client client_krb5_auth failed - krb5_sendauth failed -
305Bad application version was sent (via sendauth)
306----
307
308This means that the ka field in your Hesiod pcap entry is incorrectly set to
3090.  Send mail to hesreq@mit.edu requesting ka be set to 1.
310
311
31211. Setting up keytabs on the machine
313-------------------------------------
314
315Email accounts@mit.edu and ask them for two keytabs: one for your machine,
316and one for "daemon" at your machine.  When you get the keytab, reset their
317passwords by running:
318
319    k5srvutil change -f your.keytab
320    k5srvutil delold -f your.keytab
321
322Now, install the machine-wide keytab in /etc/krb5.keytab, and install the
323daemon keytab as /etc/daemon.keytab.  (The first filename is required; the
324second can be changed.)  Make sure you chown and chgrp it to daemon.
325
326Finally, edit /etc/printcap and give it information about the Kerberos:
327
328gutenbach: server
329    :cm=SIPB MP3 Spooler
330    ...
331    :auth_forward=kerberos5
332    :use_auth=kerberos5
333    :kerberos_id=daemon/your-machine-name.mit.edu@ATHENA.MIT.EDU
334    :kerberos_keytab=/etc/daemon.keytab
335
336Troubleshooting
337
338-----
339Printer 'pikamp3@LESBIAN-BABY-SEAGULL-GODDESS.MIT.EDU' -
340on client client_krb5_auth failed - krb5_sendauth failed - Bad response (during sendauth exchange)
341-----
342
343Your daemon.keytab is not readable by daemon.
344
34512. Setting up remctl commands
346-----------------------------
347
348It's useful to be able to control the volume. Remctl is the way to do
349this without asking people to ssh in, and then alsamix(er).
350
351You will probably need to apt-get install remctl-server. Then, replace
352the /etc/remctl/conf.d directory with a Git checkout of
353/afs/sipb/project/sipbmp3/gutenbach-remctl.git.
354
355Please note that remctl will NOT work without a keytab setup.
356
357
358X. Deploying gutenbachweb
359------------------------
360
361gutenbach web provides a nice and user-friendly interface for some common
362tasks. XXX: It is currently not portable beyond zsr. Stay tuned!
363
364X. Troubleshooting
365------------------
366
367If things are broken on a reboot, make sure you're running:
368
369    /etc/init.d/{gutenbach,zhm,debatehna-lprng}
Note: See TracBrowser for help on using the repository browser.