Ignore:
Timestamp:
Jun 24, 2010, 1:28:00 AM (14 years ago)
Author:
Jessica B. Hamrick <jhamrick@…>
Branches:
master, debian, mac, no-cups, nodebathena, web
Children:
d2fa590
Parents:
5239eb5
git-author:
Jessica B. Hamrick <jhamrick@…> (12/15/09 00:36:23)
git-committer:
Jessica B. Hamrick <jhamrick@…> (06/24/10 01:28:00)
Message:

Modified the README to help new gutenbach
developers to get started if they don't know
where the source is.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • gutenbach/debian/lib/README

    r2e8b589 redce45f  
    1 gutenbach
    2     The SIPB MP3 Music Spooler
     1If you want to help make changes to gutenbach, do NOT make changes
     2locally!  They will most likely get overwritten by the next package
     3install.  Instead, you should check out the source and edit the
     4package itself:
    35
    4 We would love you forever if you took this README/INSTALL document and made
    5 a Debian package out of it.  That would be uber-awesome.  But otherwise, we're
    6 assuming that you just want to get gutenbach up and running on your own
    7 system.  Well, maybe we shouldn't assume that.
     6/afs/sipb/project/sipbmp3/gutenbach.git
    87
     8It may be useful to just edit things locally to make sure they work,
     9and then add the change into the package.
    910
    10 What does gutenbach do?
    11 ---------------------
     11zsr (in SIPB) is set up to build packages, and already has a git clone
     12in /root/gutenbach.  You can edit the source there, build the package,
     13and then reinstall the package.
    1214
    13 gutenbach is a music spooler.  As it turns out, streaming music is a hard
    14 problem, with lots of proprietary protocols, client and server software.
    15 All of these jiggety bits are kind of a pain to get working correctly,
    16 so, we built gutenbach on top of... a printer system.  It's very simple:
    17 you print an mp3 file to a special "printer", and it gets played on
    18 whatever speakers you're hooked up to.
     15A good guide to get started with debian packaging is here:
     16http://debathena.mit.edu/packaging/
    1917
    20 
    21 Prerequisites
    22 -------------
    23 
    24 You'll need a server hooked up to an audio system that you want to use, with
    25 Debathena installed on top of it.  Ubuntu Server Edition tends to work
    26 well.
    27 
    28 
    29 Installing gutenbach
    30 ------------------
    31 
    32 
    33 1. Configuring your sound
    34 
    35 If you're installing gutenbach on a server environment, it's highly likely
    36 that you have a bare bones audio setup and everything is muted.  Make sure
    37 your sound works!  One common problem is that the daemon user (the user which
    38 will be actually playing the songs, or the user that your lpd, the print server,
    39 will be running under), isn't in the group audio, and thus can't play
    40 anything. If you're on Ubuntu Desktop, you'll probably have pulse-audio
    41 installed, in which case you should add lpd to the pulse-audio group
    42 as well, and make pulse-audio a single, system-wide instance. See
    43 this URL for detailed instructions:
    44 
    45     http://www.pulseaudio.org/wiki/SystemWideInstance
    46 
    47 
    48 2. Install some prerequisite software
    49 
    50 On a vanilla Ubuntu server install, gutenbach will also need the following
    51 packages to work properly:
    52 
    53     * mplayer
    54     * libimage-exiftool-perl
    55 
    56 mpg123 can also be useful for testing, but is not strictly necessary.
    57 
    58 
    59 3. Setup gutenbach
    60 
    61 The Git repository for gutenbach is located in:
    62 
    63     /afs/sipb/project/sipbmp3/gutenbach.git
    64 
    65 Place this in /root/gutenbach; the remctl scripts will assume that the
    66 scripts can be found in this location.
    67 
    68 
    69 4. Configure gutenbach
    70 
    71 gutenbach will send zephyrs during playback start and end.  Since you don't
    72 want to be spamming sipb-auto (which is the default zephyr class these
    73 are sent to), you should create a configuration file:
    74 
    75     /etc/gutenbach-filter-config.pl
    76 
    77 That looks like:
    78 
    79     $zephyr_class = "my-auto-class"
    80     $host = "hostname"
    81     $queue = "printername"
    82 
    83 XXX: Auto-detect hostname and invent a sane default zephyr class off of it.
    84 
    85 
    86 5. Configure gutenbach init scripts
    87 
    88 gutenbach will attempt to drop some information into /var/run/gutenbach, which
    89 needs to exist and you can't simply mkdir since /var/run on Ubuntu is
    90 a tempfs. Thus, add the following lines to a new file, /etc/init.d/gutenbach:
    91 
    92 #!/bin/sh
    93 mkdir /var/run/gutenbach
    94 touch /var/run/gutenbach/status
    95 chmod 0777 /var/run/gutenbach/status
    96 
    97 You should also run these commands yourself. :-)
    98 
    99 XXX: 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 
    109 XXX: We need better permissions for status. Also, quentin wants to put this
    110 file in AFS.
    111 
    112 
    113 6. Configure lpd
    114 
    115 You'll need to setup a printcap file so that your machine will be actually
    116 running a printer! The magic lines are:
    117 
    118     :if=|/path/to/gutenbach-filter
    119     :lp=/dev/null
    120 
    121 Which mean that we pipe the mp3 files through gutenbach-filter (which does
    122 the actual playing), and then dump the rest of the output into /dev/null,
    123 since we don't actually care about it.
    124 
    125 A standard printcap entry looks like this:
    126 
    127 printername
    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 
    136 printcap is located in /etc/printcap, but you can also edit the symlink
    137 in /etc/lprng/printcap.
    138 
    139 In /etc/lprng/lpd.conf:
    140 
    141     printcap_path=...
    142 
    143 add /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
    148 in the future.
    149 
    150 WARNING: On a cluster machine, get_hesiod_pcap will clobber gutenbach
    151 because it sets all:all=someotherprinter, making lpr not see gutenbach.
    152 There are two ways of fixing this:
    153 
    154 1. Patch /usr/lib/get_hesiod_pcap to return a full pcap line instead
    155 of all when it gets "all" from stdin.
    156 
    157 2. Remove get_hesiod_pcap from the list.
    158 
    159 To check your modifications, and create the necessary files and folders,
    160 you 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 
    167 With recent versions of lprng, you will also need to make lpd less paranoid
    168 about accepting connections.  This usually means the following two changes:
    169 
    170 In /etc/lprng/lpd.perms:
    171 
    172     REJECT NOT SERVER
    173 
    174 should be commented out, as:
    175 
    176     #REJECT NOT SERVER
    177 
    178 You will also need to add this line in lpd.conf:
    179 
    180     lpd_listen_port=515
    181 
    182 By default, printers don't allow other users to remove other people's print
    183 jobs.  For an MP3 spooler, however, this may be a desirable trait, especially
    184 if someone trys to rickroll you.  You can let everyone lprm jobs by
    185 commenting out the line:
    186 
    187     REJECT SERVICE=M
    188 
    189 XXX: On scourge, ACCEPT SERVICE=M SAMEHOST SAMEUSER doesn't seem to work
    190 properly, so removing the REJECT line is a must!
    191 
    192 XXXXXX: gutenbach accepts no responsibility for social faux pas that may
    193 be committed with this system.  It is consider good etiquette, however,
    194 to clear the status file if you're on zsr.
    195 
    196 XXXXXXXX: 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 
    206 7. Test, round one
    207 
    208 The first test you should do to make sure gutenbach is configured properly is
    209 to attempt to play an mp3 file locally, via lpr.  The command you should use
    210 is:
    211 
    212     mit-lpr -Pprintername@localhost filename.mp3
    213 
    214 Note the "mit-" prefix; Debathena defaults to CUPS, which we have not set
    215 up yet.
    216 
    217 See below for troubleshooting tips.
    218 
    219 
    220 8. Test, round two
    221 
    222 The second test you should do is try playing an MP3 remotely. The appropriate
    223 command is:
    224 
    225     mit-lpr -Pprintername@hostname filename.mp3
    226 
    227 (Once again, with "mit-").  See below for troubleshooting tips.
    228 
    229 
    230 9. Troubleshooting
    231 
    232 So, it didn't work.  How did it fail?
    233 
    234 ----
    235 sending 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 
    240 This means that lpd is not accepting connections properly.  Check to see
    241 if you configured lpd.perms and lpd.conf correctly.  Try rebooting lpd
    242 by pkill lpd && lpd.  Use nmap to check of port 515 is open, both on the
    243 local machine and on a remote machine.  Check if networking is working
    244 on the server.  Use netstat to see what programs are listening to port
    245 515, and from which hosts.  Check iptables.
    246 
    247 ----
    248 lpr: The printer or class was not found.
    249 ----
    250 
    251 You're using lpr, not mit-lpr.
    252 
    253 ----
    254 (no output, but no sound)
    255 ----
    256 
    257 It looks like you managed to send the file over.  To diagnose the problems
    258 further:
    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 
    288 10. Deploying CUPS
    289 ------------------
    290 
    291 The final step is to give your newfangled printer a cups.mit.edu record.
    292 In order to do this, you will need to ask IS&T for a Moira pcap entry
    293 request.  Send mail to hesreq@mit.edu, specifying that you are setting
    294 up a gutenbach clone, that you want a Moira pcap entry, the printer name
    295 and server name of your queue, and that you want hwtype=LOCAL,ka=1. It wouldn't
    296 hurt to also tell them where your print queue is, and a contact list.
    297 
    298 Once you get the pcap entry, ping sipb-cups@mit.edu to add your machine
    299 to the public list.
    300 
    301 Troubleshooting:
    302 
    303 ----
    304 Send_auth_transfer: on client client_krb5_auth failed - krb5_sendauth failed -
    305 Bad application version was sent (via sendauth)
    306 ----
    307 
    308 This means that the ka field in your Hesiod pcap entry is incorrectly set to
    309 0.  Send mail to hesreq@mit.edu requesting ka be set to 1.
    310 
    311 
    312 11. Setting up keytabs on the machine
    313 -------------------------------------
    314 
    315 Email accounts@mit.edu and ask them for two keytabs: one for your machine,
    316 and one for "daemon" at your machine.  When you get the keytab, reset their
    317 passwords by running:
    318 
    319     k5srvutil change -f your.keytab
    320     k5srvutil delold -f your.keytab
    321 
    322 Now, install the machine-wide keytab in /etc/krb5.keytab, and install the
    323 daemon keytab as /etc/daemon.keytab.  (The first filename is required; the
    324 second can be changed.)  Make sure you chown and chgrp it to daemon.
    325 
    326 Finally, edit /etc/printcap and give it information about the Kerberos:
    327 
    328 gutenbach: 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 
    336 Troubleshooting
    337 
    338 -----
    339 Printer 'pikamp3@LESBIAN-BABY-SEAGULL-GODDESS.MIT.EDU' -
    340 on client client_krb5_auth failed - krb5_sendauth failed - Bad response (during sendauth exchange)
    341 -----
    342 
    343 Your daemon.keytab is not readable by daemon.
    344 
    345 12. Setting up remctl commands
    346 -----------------------------
    347 
    348 It's useful to be able to control the volume. Remctl is the way to do
    349 this without asking people to ssh in, and then alsamix(er).
    350 
    351 You will probably need to apt-get install remctl-server. Then, replace
    352 the /etc/remctl/conf.d directory with a Git checkout of
    353 /afs/sipb/project/sipbmp3/gutenbach-remctl.git.
    354 
    355 Please note that remctl will NOT work without a keytab setup.
    356 
    357 
    358 X. Deploying gutenbachweb
    359 ------------------------
    360 
    361 gutenbach web provides a nice and user-friendly interface for some common
    362 tasks. XXX: It is currently not portable beyond zsr. Stay tuned!
    363 
    364 X. Troubleshooting
    365 ------------------
    366 
    367 If things are broken on a reboot, make sure you're running:
    368 
    369     /etc/init.d/{gutenbach,zhm,debatehna-lprng}
     18jhamrick (Jessica Hamrick) is currently the active maintainer for
     19gutenbach, so if you're interested in contributing but don't know
     20quite where to start, you should talk to her.
Note: See TracChangeset for help on using the changeset viewer.