Home
  About | Download | Features | Shots | Docs | Geeks | SF  
 
 
Obsequieum Documentation



Introduction


This document will walk you through the process of installing Obsequieum on your system. Please make sure to at least review the Requirements section, since Obsequieum depends on a number of other packages before it can be functional.

You can reach me at: rob@eorbit.net I'd love to hear about suggestions and what I could do to improve these install instructions.


System Requirements


System requirements:

  • Pentium 100, 32Mb RAM
  • Linux 2.x.x
  • glibc 2.x installed
  • POSIX pthread support (LinuxThreads)
  • zlib compression library installed (http://www.zlib.org)

Please do not attempt to run Obseqieum (or MySQL) on a non-glibc 2.x system. Obs makes heavy use threads, and libc5 is not thread safe. If you try to do so anyway, and you run into problems, I cannot help you. Please don't send me mail about getting this to work on libc5.


Software Package Requirements


In order to run Obsequieum you will need:

  • MySQL with mysqlclient
  • Perl 5.003 or later.
  • Some perl modules. See below for details.
  • Apache web server (http://www.apache.org) or with mod_perl/Registry plug-in. (recommended!)
  • Zinf 2.2.0 or later to listen to the streams.
  • The rio program from the SnowBlind Alliance if you want to download from Obs into the Rio.
  • A ripper and an MP3 encoder if you want to use the one-step-CD-ripping script.
  • Multicast support compiled into the kernel
Please be sure to satisfy these requirements before you proceed with the installation.


Installing MySQL


To install MySQL, download the latest source distribution or rpms from mysql.com. If you download prebuilt binaries like rpms, make sure you download and install the client and devel packages as well. For more details on installing MySQL, please see the MySQL documentation in the Docs directory.

If you downloaded the source distribution, the basic process for installing the source is like all the other programs you've ever built from source: 


   tar -xzf [mysql tar gz distribution]
   ./configure
   make
At this point you should su to root, if you haven't done so already. The following steps will install MySQL onto your machine: 

   make install           # install MySQL
   cd /usr/local/bin                   
   ./mysql_install_db     # create the default MySQL tables
   ./safe_mysqld &        # start the MySQL server
You may want to enter the safe_mysqld command into your startup scripts so that the SQL server starts at boot time.

The MySQL client and the expat library need the zlib compresion library installed. Most recent Linux distros will have these installed already. But if you do not, grab one from: http://www.zlib.org

Note: If your MySQL installation placed the libmysqlclient.so library into any place other than /usr/lib/mysql, then make sure that your dynamic link path includes that directory. For instance, if the MySQL installation placed the libmysqlclient.so library into /usr/local/lib/mysql, follow these steps:

  • As root, edit /etc/ld.so.conf and add a new line with the path to your library (e.g. /usr/local/lib/mysql)
  • Run the program 'ldconfig' to update the dynamic link paths


Installing needed Perl modules


The following perl modules are required, but before you start downloading read about the available shortcuts below:

Installing perl modules can be a real drag, so there are two shortcuts available for you. If you know what CPAN is and how to use it, go ahead and use it. If not and you don't have the above packages installed, you can download the perl_modules-0.4.0.tar.gz shortcut package. After you download the package, follow these steps to magically install the needed perl modules: 

   tar -xzf perl_modules-0.4.0.tar.gz
   cd perl_modules-0.4.0
   ./install.pl
The MySQL module package will ask you a few questions -- simply choose to install the module for MySQL only and accept the default choices for the rest of the options and you should be fine.


Installing Apache


A lot of distributions now come with Apache. Check your distribution to see if you can install from a .rpm or a .deb. If not, go download a copy from the Apache web site. Please follow the instructions that come with Apache to build/install it.

Using Apache's mod_perl module is highly recommended since it greatly speeds up the access of the Obseqiuem server pages. However, if this is your first time installing Obs, I would suggest you go with a standard installation of Apache and play around with Obs before you go through the process of installing mod_perl.


Building and Installing Obseqeieum


To build Obseqieum, execute these commands from the command line in the root of the obs source distribution: 


   ./configure
   make 
   su
   make install
   ./install-db.pl
   ./install-www.pl
This will build and install Obs into /usr/local/obs. If you prefer to install it someplace else, invoke configure like this: 

./configure --prefix=[path]
configure will set up the code base to compile on your machine. If configure complains about something, fix what it complains about and try again.

make will build the obsd binary. After the make you should su to root, if you haven't done so already. The rest of the installation requires you to be root. Once you're root, do make install to install the obs daemon and the non-cgi scripts.

Then, install-db.pl will let you configure which mysql user to use for Obs and it will create and install the necessary perl modules. After the perl modules it will make sure that MySQL is running and the it will create the proper MySQL user and create the tables that Obs needs. If your tables already exist they will not be overwritten by this script. The script will examine the existing tables and if necessary, add new tables or columns to existing tables without affecting your data.

The install-db.pl script will ask you for the following information:

Obseqieum database to use [obs]: Unless you already have a database named 'obs', choose the default.
Obseqieum user [obs]: Unless you already have a database user named 'obs', choose the default.
Password for user: The password to use for this user.
MySQL root password: The MySQL root user password.

After getting that information, the script will write these settings into the Obs::Defs perl module. This module is used by all Obs scripts and programs to get the database information. Then it will create new database tables for use with Obs, or if the tables already exist it will make sure that the table have all the right fields.

If the install-db.pl script dies while trying to update an existing table, your existing obs user may not have 'alter table' privledges in MySQL. You can either remove the old obs user and re-run install-db.pl to create the obs user with the proper priviledges, or you can add 'alter table' privs to the existing user and then re-run the install-db.pl script.

The install-www.pl script guides the user through the CGI script/html file install process. Before running this script you need to decide which URL relative to the root of your webserver you would like to use to bring up the Obs interface.

It is probably best to bring up the Obs interface as http://my.server.org/obs. In your httpd.conf file, check to see where DocumentRoot and ScriptAlias (for cgi-bin) point. If your DocumentRoot points to /home/httpd, then you should enter /home/httpd/obs for the HTML document directory. If your ScriptAlias for /cgi-bin points to /home/httpd/cgi-bin then enter /home/httpd/cgi-bin/obs for the cgi-bin server directory. Accept the defaults for the Obs root URL location and cgi-bin URL location:

HTML document directory [/usr/local/obs/www/obs]: This directory will contain the static html files needed for the Obseqeiuem web pages. If you would like to access Obsequieuem like this: http://www.mymachine.org/obs, then you should enter the value of DocumentRoot for the your webserver with a trailing '/obs'.
Obs root URL location [/obs]: Where, relative to the root of your webserver obs can be found. Again, if you would like to access Obsequieuem like this: http://www.mymachine.org/obs, then you should enter accept the default '/obs'.
cgi-bin server directory [/usr/local/obs/cgi-bin/obs]: This directory will contain the CGI script files needed for the Obseqeiuem web pages. Enter the value of ScriptAlias from your web server followed by '/obs'.
cgi-bin URL location [/cgi-bin/obs]: Where, relative to the root of your webserver the obs CGI scripts can be found. If you appended '/obs' to your ScriptAlias value for the question above, accept the default '/obs'.

If you decide to accept the default path locations (rather than installing into your existing DocumentRoot and ScriptAlias directories), the script will install the html and cgi scripts into /usr/local/obs/www and /usr/local/obs/cgi-bin. In this case, you will need to create an Alias for /obs and a ScriptAlias for /cgi-bin/obs in your httpd.conf.

After entering the desired values, this script will then copy the scripts/html files into their proper locations. During the copy all the html files and cgi scripts will have their relative path locations fixed up so that all the links will properly resolve. If you try to bring up the web pages and the pages (or portions thereof) do not show up, then some of the values given to this script were incorrect. Check your paths and re-run the script to try and fix this problem.

NOTE: Please make sure that Directory directive for your cgi-bin directory has the Option FollowSymLinks. If it does not have this option set the /obs/admin pages will not be found.


Configuring Obseqeieum


Now edit the obs.conf and devices.conf files in the /usr/local/obs/etc dir. Below are detailed instructions on how to edit these files.

Editing obs.conf:

Follow the instructions in the obs.conf file. Most of the values in obs.conf are good for a normal installation. If you would like to use SHOUTcast style streams instead of RTP/Multicast, then check out the SHOUTcast notes.

Please note that if an obs.conf file existed in the target install directory during the 

make install
process, the existing obs.conf file will not be touched -- the new obs.conf file will be saved to obs.conf.new. If you are installing a new version of obs, you migrate your obs.conf file to the new obs.conf file.

Editing devices.conf:

The default devices.conf file looks like this: 


   #Device:             Type:         Cache: WriteAllowed:
   /mnt/mp3             HARD_DRIVE    no     yes

The fist column defines a directory where Obs can store MP3 files. To start with, point this to an empty directory with lots of space. Start with type HARD_DRIVE (a permanently mounted path), set cache to 'no'. Cache is used for non-permament devices such as CD changers. Obs can mount a disk out of a CD changer, copy the MP3 into the cache and then stream the MP3 out of the cache. WriteAllowed should be 'yes' so that you can check files into Obs.

Setting up Volume files:

For each HARD_DRIVE path you list, you'll need to create a file called 'Volume' in that path. The file should contain a single line with the name of the volume. All MP3 files that are placed in each HARD_DRIVE path make up one volume. The Obs server can handle multiple devices and it needs a volume name to keep track of the MP3 files on the hard drive. To start with, call it something like 'hdvol01'.

Note: Its best not to touch the files in the HARD_DRIVE path -- if you move or rename the files the server will no longer be able to access them. You can use the CleanUp.pl script to manage the layout and cleanilness of your Obs mp3 collection.

Setting up DeadAirMP3:

The DeadAirMP3 file specified in the obs.conf file will be played when no tracks are available in the database. This usually only happens when something has gone wrong, like when the SQL server crashes. The install process will install a default file for this purpose. Change the path in obs.conf or replace the /usr/local/obs/etc/deadair.mp3 to something that suits you better than the default.


Starting & Installing Obseqeieum


Finally, you are ready to bring up Obs for the first time. Point your browser to the Obs URL you specified in the install-www.pl script. You should see the Obsequieum pages with the 4 panes and the title bar. If it doesn't come up, check the troubleshooting section for possible problems.

Go to /usr/local/obs/bin and start the server in debug mode by hand: 


   ./obsd -d -n
The -d option tells the server to not become a deamon, and print all messages to stdout, rather than the log file. The -n option prevents Obs from sending out a stream, since the server initially has no files to stream. Follow the messages to see if any errors occur. If they do, please re-read the relevant instructions and see if you can fix the problem.

If the output from the server looks similar to this, 


   ----- Obsequieum started Sun Mar 19 03:19:00 2000
   AddDevices: Added device: /mnt/mp3 (HARD_DRIVE)
   Hard Drive /mnt/mp3:
     vol00000
   Main: Volumes have been loaded.
   Main: Not sending a stream. Sleeping...
then everything is happy! Leave the server running like this for now so that you can check files into the server in the next step.

Later when the server works as desired, start the server with the obsctl script: 


   obsctl start
or 

   obsctl stop
When started in normal (non debug) mode the server does some sanity checks before becoming a daemon. If no messages are printed to the console the messages now go to /usr/local/obs/logs/obs.log. To watch the contents of the log file while the server is running, do a tail -f /usr/local/obs/logs/obs.log.

If the server encounters an error, always check the log file for information on what might have gone wrong.


Ripping/Music submission


At this point, you no longer need to be root. When you submit tracks to obs using either of first two the methods below, the obs server must be running.

Ripping from CD directly into Obsequeium:

The script RipCd.pl and the support program cdinfo (installed into /usr/local/bin) allow you to rip a CD (or certain tracks of it) into an Obsqeuieum server. The track listings for the CD will be automatically downloaded from the CDDB server. In order to make use of this script you will need to have the following tools installed:

Use the script like this: 

   # Get a listing of all the options
   RipCd.pl --help                        

   # Rip, encode and submit entire CD.
   RipCd.pl                               

   # Rip, encode and submit tracks 1, 3, and 5
   RipCd.pl -t 1 3 5                      

   # Rip, encode and submit entire CD to obs 
   # server obs.yourobs.net
   RipCd.pl -s obs.yourobs.net
Check the usage (--help) for more information.

Importing existing MP3s:

The script SubmitTrack.pl (installed into /usr/local/bin) allows you to submit MP3 files. This script can read the ID3 tags and use that information to import the track into Obsequieum. If no ID3 tags exist, the user can specify the track information via command line options. Example usages: 


# Submit *.mp3 into Obseqieum (ID3 tags needed)
SubmitTrack.pl -t *.mp3                

# Submit a sample mp3 without ID3 tag.
SubmitTrack.pl -n "Eclipse" -a "Pink Floyd" 
   -l "Dark Side of the Moon" -r 9 eclipse.mp3

# Automatically submit all your ID3 tagged MP3s
# out of 
find  -name \*.mp3 -exec SubmitTrack.pl -t {} \;

Searching for and Importing existing MP3s:

The AddFiles.pl script (installed into /usr/local/obs/tools) can be used to search for existing mp3 files and import then into Obs. This script does not require the obs server to be running, but it requires MySQL to be running.

The AddFiles script will recursively search the paths given on the command line and add any mp3 files it finds to the local Obs server. The script will read ID3v1, ID3v2 tags from the files, and even based on the name of the file it will attempt to extract information about the Artist, Title and Album.

For instance, if you have your mp3 collection stashed in /mnt/mp3, make sure to create a Volume file in /mnt/mp3 -- AddFiles.pl requires a Volume file to be present in the specified path. If it cannot find the Volume file in the specified path it will scan upwards in the path to find a Volume files. So, if you want to cheat and have all your mp3s in your file system use one Volume file, simply create the file Volume file in /. :-)

AddFiles.pl can be run in test mode (-t) and it will search for mp3s, but it will not actually add them to the server. It can also be run in update mode where it will add new files and update the metadata on existing files -- without the -u file existing files are skipped.

If you have all of your mp3 files oranigzed in a particular file naming scheme, you can import the meta data (artist, album, track, and title) straight from the file name. You will need to define the filename pattern that AddFiles.pl should use in /usr/local/obs/etc/obs.conf.

For instance, if your files are laid out like: 


   (Portishead)-Dummy-[03]-Strangers.mp3
Then set the ImportFileMask in obs.conf to: 

   ImportFileMask    (%artist)-%album-[%track]-%title.mp3
AddFiles.pl will first parse the filenames of found mp3s to see if they match the ImportFileMask string. If so it will parse the meta data out of the file name. Then it will try to find data in an ID3v1 tag and then it will try to find data in an ID3v2 tag. Note that data found in an ID3v2 tag overrides the data in an ID3v1 tag, which in turn overrides the data found in the filename.


Playing the Obseqeueium stream


Once you've checked some files into the server, stop the server, and restart it without the -n option. This time you should see some messages about the server adding files to the mixer.

Once the server is up and running, start Zinf (download, and install if you need to) like this: 


   zinf rtp://225.2.1.5:4420
assuming you didn't make any changes to the broadcast addr/port. Zinf should buffer up and start playing the MP3 stream.

If that worked, congratuations! You've got a running Obs server. Stop your server again and then start it without any options and it will immediately become a deamon and start the mp3 stream.


Troubleshooting an Obsequium install


Here are a few common problems you might run into:

  • The pages cannot be found in the installed directory: Double check the paths where the obs pages have been installed. Do these paths jive with the paths that Apache is using?
  • The cgi-bin scripts cannot be found in the installed directory: Double check the ScriptAlias path in the Apache configuration and make sure the scripts got copied to the right place.
  • The 4 panes display this error: 'Error: Access denied for user: 'obs@localhost'. If this error occurs, re-run in the install-db.pl and install-www.pl scripts and make sure all the values are ok. If that fails, check the Defs.pm (installed into /usr/lib/perl5/site_perl/Obs -- or whereever Perl installs modules on your system) and make sure the database, user and password values defined there jive with what you gave install-db.pl.
  • If you go to the admin pages to edit the data in the MySQL server, and the browser says that the admin pages cannot be found, make sure your Directory directive for /cgi-bin/obs in httpd.conf specifies the FollowSymLinks Option.
  • If the server crashes or misbehaves, go the the logs directory (/usr/local/obs/logs) and check what obs.log says.
If the tips up there don't help, you can subscribe to the obs-dev mailing list. This list discusses Obsequeium related issues such as install problems and future development.