source: gutenbach/debian/lib/README @ eadacf9

debianmacno-cupsnodebathenaweb
Last change on this file since eadacf9 was eadacf9, checked in by Jessica B. Hamrick <jhamrick@…>, 14 years ago

Update README after reinstalling zsr.
Signed-off-by: Edward Z. Yang <edwardzyang@…>

  • Property mode set to 100644
File size: 10.0 KB
Line 
1sipbmp3
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 sipbmp3 up and running on your own
7system.  Well, maybe we shouldn't assume that.
8
9
10What does sipbmp3 do?
11---------------------
12
13sipbmp3 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 sipbmp3 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 sipbmp3
30------------------
31
32
331. Configuring your sound
34
35If you're installing sipbmp3 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, sipbmp3 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 sipbmp3
60
61The Git repository for sipbmp3 is located in:
62
63    /afs/sipb/project/sipbmp3/sipbmp3.git
64
65Place this in /root/sipbmp3; the remctl scripts will assume that the
66scripts can be found in this location.
67
68
694. Configure sipbmp3
70
71sipbmp3 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/sipbmp3-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 sipbmp3 init scripts
87
88sipbmp3 will attempt to drop some information into /var/run/sipbmp3, 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/sipbmp3:
91
92#!/bin/sh
93mkdir /var/run/sipbmp3
94touch /var/run/sipbmp3/status
95chmod 0777 /var/run/sipbmp3/status
96
97You should also run these commands yourself. :-)
98
99XXX: We need better permissions for status. Also, quentin wants to put this
100file in AFS.
101
102
1036. Configure lpd
104
105You'll need to setup a printcap file so that your machine will be actually
106running a printer! The magic lines are:
107
108    :if=|/path/to/sipbmp3-filter
109    :lp=/dev/null
110
111Which mean that we pipe the mp3 files through sipbmp3-filter (which does
112the actual playing), and then dump the rest of the output into /dev/null,
113since we don't actually care about it.
114
115A standard printcap entry looks like this:
116
117printername
118  :server
119  :cm=Human Readable Printer Name
120  :lp=/dev/null
121  :if=|/path/to/sipbmp3-filter
122  :sd=/var/spool/lpd/printername
123  :ml=0:mx=0:sh:sf
124  :create_files
125
126printcap is located in /etc/printcap, but you can also edit the symlink
127in /etc/lprng/printcap.
128
129In /etc/lprng/lpd.conf:
130
131    printcap_path=...
132
133add /etc/lprng/printcap to the beginning of the pathlist, so it looks like:
134
135    printcap_path=/etc/lprng/printcap:|/usr/lib/get_hesiod_pcap
136
137/etc/printcap will also work, assuming lprng doesn't do something funky
138in the future.
139
140WARNING: On a cluster machine, get_hesiod_pcap will clobber sipbmp3
141because it sets all:all=someotherprinter, making lpr not see sipbmp3.
142There are two ways of fixing this:
143
1441. Patch /usr/lib/get_hesiod_pcap to return a full pcap line instead
145of all when it gets "all" from stdin.
146
1472. Remove get_hesiod_pcap from the list.
148
149To check your modifications, and create the necessary files and folders,
150you should run:
151
152    checkpc -V -f
153
154(As root, of course). You might get a failure on a directory
155/var/spool/lpd/%P doesn't exist; simply mkdir it and run checkpc -V -f
156
157With recent versions of lprng, you will also need to make lpd less paranoid
158about accepting connections.  This usually means the following two changes:
159
160In /etc/lprng/lpd.perms:
161
162    REJECT NOT SERVER
163
164should be commented out, as:
165
166    #REJECT NOT SERVER
167
168You will also need to add this line in lpd.conf:
169
170    lpd_listen_port=515
171
172By default, printers don't allow other users to remove other people's print
173jobs.  For an MP3 spooler, however, this may be a desirable trait, especially
174if someone trys to rickroll you.  You can let everyone lprm jobs by
175commenting out the line:
176
177    REJECT SERVICE=M
178
179XXX: On scourge, ACCEPT SERVICE=M SAMEHOST SAMEUSER doesn't seem to work
180properly, so removing the REJECT line is a must!
181
182XXXXXX: sipbmp3 accepts no responsibility for social faux pas that may
183be committed with this system.  It is consider good etiquette, however,
184to clear the status file if you're on zsr.
185
186
1877. Test, round one
188
189The first test you should do to make sure sipbmp3 is configured properly is
190to attempt to play an mp3 file locally, via lpr.  The command you should use
191is:
192
193    mit-lpr -Pprintername@localhost filename.mp3
194
195Note the "mit-" prefix; Debathena defaults to CUPS, which we have not set
196up yet.
197
198See below for troubleshooting tips.
199
200
2018. Test, round two
202
203The second test you should do is try playing an MP3 remotely. The appropriate
204command is:
205
206    mit-lpr -Pprintername@hostname filename.mp3
207
208(Once again, with "mit-").  See below for troubleshooting tips.
209
210
2119. Troubleshooting
212
213So, it didn't work.  How did it fail?
214
215----
216sending job 'ezyang@vivace+800' to asdfasdf@localhost
217 connecting to 'localhost', attempt 1
218 cannot open connection to localhost - No such file or directory
219----
220
221This means that lpd is not accepting connections properly.  Check to see
222if you configured lpd.perms and lpd.conf correctly.  Try rebooting lpd
223by pkill lpd && lpd.  Use nmap to check of port 515 is open, both on the
224local machine and on a remote machine.  Check if networking is working
225on the server.  Use netstat to see what programs are listening to port
226515, and from which hosts.  Check iptables.
227
228----
229lpr: The printer or class was not found.
230----
231
232You're using lpr, not mit-lpr.
233
234----
235(no output, but no sound)
236----
237
238It looks like you managed to send the file over.  To diagnose the problems
239further:
240
241    * Check the zephyr logs of the class sipbmp3 was configured to
242      send messages to:
243
244        - If you see a reasonably full and formatted message, that means
245          that either: 1. your volume is turned off, or 2. mplayer is
246          horribly broken (XXX: it probably isn't, but I don't know what
247          error message it gives in that case)
248
249          By the way, be sure to check both the *hardware* and the
250          *software* volume.
251
252        - If you see a blank zephyr, that means that sipbmp3-filter died
253          trying to get a handle to /var/run/sipbmp3/status and failing.
254          Check if you created the file correctly, and that daemon has
255          permissions to write to it. If you rebooted recently, check if
256          you have the appropriate init.d script setup.
257
258    * Otherwise, check /var/spool/lpd/printername/status.pr (most of all the
259      other files are useless, especially including log):
260
261        - If you see a Perl error, fix it. The most common cause is because
262          exiftools is not installed.
263
264    * Otherwise, double check the userland code in sipbmp3-filter. XXX: There
265      are some edge-cases that don't give nice error messages, for example
266      the failed write to /var/run/sipbmp3/status
267
268
26910. Deploying CUPS
270------------------
271
272The final step is to give your newfangled printer a cups.mit.edu record.
273In order to do this, you will need to ask IS&T for a Moira pcap entry
274request.  Send mail to hesreq@mit.edu, specifying that you are setting
275up a sipbmp3 clone, that you want a Moira pcap entry, the printer name
276and server name of your queue, and that you want hwtype=LOCAL. It wouldn't
277hurt to also tell them where your print queue is, and a contact list.
278
279Once you get the pcap entry, ping sipb-cups@mit.edu to add your machine
280to the public list.
281
282
28311. Setting up keytabs on the machine
284-------------------------------------
285
286Email accounts@mit.edu and ask them for two keytabs: one for your machine,
287and one for "daemon" at your machine.  When you get the keytab, reset their
288passwords by running:
289
290    k5srvutil change -f your.keytab
291    k5srvutil delold -f your.keytab
292
293Now, install the machine-wide keytab in /etc/krb5.keytab, and install the
294daemon keytab as /etc/daemon.keytab.  (The first filename is required; the
295second can be changed.)  Make sure you chown and chgrp it to daemon.
296
297Finally, edit /etc/printcap and give it information about the Kerberos:
298
299sipbmp3: server
300    :cm=SIPB MP3 Spooler
301    ...
302    :auth_forward=kerberos5
303    :use_auth=kerberos5
304    :kerberos_id=daemon/your-machine-name.mit.edu@ATHENA.MIT.EDU
305    :kerberos_keytab=/etc/daemon.keytab
306
307
30812. Setting up remctl commands
309-----------------------------
310
311It's useful to be able to control the volume. Remctl is the way to do
312this without asking people to ssh in, and then alsamix(er).
313
314You will probably need to apt-get install remctl-server. Then, replace
315the /etc/remctl/conf.d directory with a Git checkout of
316/afs/sipb/project/sipbmp3/sipbmp3-remctl.git.
317
318Please note that remctl will NOT work without a keytab setup.
319
320
321X. Deploying sipbmp3web
322------------------------
323
324sipbmp3 web provides a nice and user-friendly interface for some common
325tasks. XXX: It is currently not portable beyond zsr. Stay tuned!
326
Note: See TracBrowser for help on using the repository browser.