rplay INSTALL - Installation instructions		-*-outline-*-

* Overview

This file contains a list of installation instructions for RPlay.
Please read this file very carefully and don't skip any steps unless
you think you know what you are doing.  If you get confused at any
time during the installation please read the documents in the `doc'
directory.

* Configuration

** Execute `./configure'

RPlay is configured using GNU autoconf.  Execute `./configure' in the
RPlay source directory to create RPlay configuration files for your
system.  If you want to install RPlay in a directory tree other than
`/usr/local' use `./configure --prefix=/installation/path'.

The file `INSTALL.generic' contains generic GNU autoconf installation
instructions.  Please read this file if you're having problems
using configure.

If the configuration script cannot determine your system type it will
try to use a generic configuration.  Note that the system type is used
to enable system specific audio routines.  The generic configuration
assumes an 8000 Hz audio device that accepts ulaw encoded audio data.
System specific audio routines are located in the rplayd/audio
directory.  See the PORTING file for more information on porting RPlay
to another system.

** Edit `Makefile.config'

You may need to edit `Makefile.config' to choose the correct C
compiler, CC_OPTIONS, and LD_OPTIONS.  Note that configure will try to
use the gcc compiler with the -O flag by default.  HP users should
uncomment all the lines specified.

** Edit `include/config.h'

RPlay configuration parameters can be changed in `include/config.h'.
This is where you can change the location of rplay.conf, rplay.hosts,
rplay.servers, rplay.cache, and rplay.log, if necessary.  (These file
names are automatically modified by configure's --prefix option)
There's several other parameters that you may want to enable or
disable or change.

** Special HP modifications

HP users need to edit `librplay/Makefile' to comment/uncomment a few lines.
See the directions in `librplay/Makefile' for more information.
-- I've got to add this to the configure script.

* Build Makefile dependencies

This step is optional but recommended.  Execute `make depend' to
create dependencies in the Makefiles.  The `makedepend' program is
used to create the dependencies (see `Makefile.config').w

* Compile RPlay

Execute `make' to compile RPlay.  Compiler flags can be changed by
specifying CFLAGS on the make command line.  (i.e. `make CFLAGS="-O4
-g"') The C compiler can be changed in the same manner as CFLAGS by
using the CC make parameter.

If RPlay does not compile successfully you might need to change either
the `Makefile.config' or `include/config.h'.

* Create configuration files

Create your rplay.servers, rplay.hosts, and rplay.conf files.  Samples
of all of these files are located in the `samples' directory.  If you
want any of these files to be installed automatically, copy them to
the `site' directory.  Manual pages for each of these files are
included in the `doc' directory.

Note that the rplay.hosts file is only required if AUTH was defined in 
include/config.h.  (AUTH is defined by default)

* Install RPlay

When RPlay successfully compiles, execute `make install'.  This will
verify that RPlay has been compiled successfully and install RPlay.

* rplayd installation options

** Is rplayd secure enough to run as root?

Well, that's entirely up to you.  The BAD_DIRS option in
`include/config.h' restricts the directories that can be accessed by
rplayd.  (By default BAD_DIRS includes /etc, /dev, and /devices) I
feel rplayd is secure enough to run as root, but that is NOT for me to
decide.  Remember to read the NO WARRANTY section in the COPYING file.

** Running rplayd from inetd

rplayd can be configured to run from inetd, although it's not required
or recommended.  If you plan on using inetd to invoke rplayd, become
root and add the following to /etc/services:

    rplay 5555/udp

    *NOTE* This entry used to be `rplay 55555/udp'.

Then add this to inetd.conf (you may need to change the pathname):

    rplay dgram udp wait nobody /usr/local/bin/rplayd rplayd -t300

If you do not have a `nobody' user defined in your password file
(/etc/passwd), change `nobody' to a valid username.  Make sure that
the user specified in inetd.conf has write access to audio device.
Some systems change the owner of audio device to person who's logged
in on the console.  (See audio device permissions below)

If you are running NIS (YP) you will need to update the services map.
`cd /var/yp; make' will probably do the trick for SunOS 4.1.x users.
The NIS update must be done on the NIS server.  You can execute
`ypwhich' to locate your NIS server.

Now you need to restart inetd.
    bash$ ps aux | grep inetd
    (result will be something like this)
    root       174  0.0  0.0   48    0 ?  IW   13:25   0:04 inetd
    bash$ kill -1 174

Check /var/adm/messages or the console for any errors.

** Running rplayd as a standalone daemon

When rplayd is not started by inetd it must be started manually by
individual users or at system startup.  Users may wish to start rplayd
whenever they use the system console.  rplayd can be started using
`rplayd &' or many options can be used to configure rplayd's
behaviour.  See `rplayd --help' for more information.

** Audio device permissions

Check your systems audio device permissions.  SunOS 4.1.x can
automatically set the permissions of /dev/audio using /etc/fbtab.
(`man 5 fbtab') Solaris 2.X uses /etc/logindevperm.  When these device
permission files include the audio device, only the person logged in
on the system console will have access to the audio device.  Of
course, this does not apply if you're running rplayd as root.

* Now see if RPlay works

Start rplayd (using inetd or standalone) and execute `rplay sound',
where `sound' is the name of a sound file in rplay.conf, a sound file
in the current directory, or a complete pathname to a sound file.

If `sound' is played then obviously RPlay is working.

* It doesn't work!

** Try debug mode

If a `sound' is not played then I recommend you run rplayd in debug
mode to see exactly what is wrong.  When using rplayd in debug mode
all inetd.conf entries (if any) must be removed.  Remove the rplayd
entry from inetd.conf, restart inetd, and kill any old rplayds that
might be running.

Try running `rplayd -n -d -t0 &' and then `rplay sound'.
You should see output like:

    rplayd: 127.0.0.1 play bogus
    rplayd: bogus.au: 8 bit, 8000 Hz, 1 channel

** Other possible problems

If you still don't hear any sound, check the following things:

*** Is the volume of the audio device very low or zero?

Use xrplay or audiotool to change the volume.

*** Is another program using the audio device?

There are several programs around that hog the audio device.  These
programs include soundtool, audiotool, play, x_soundtool, any many
others.  Note that RPlay is audio device friendly and will close the
audio device when it is not being used (see --audio-close).
     
*** Are you running another audio server like Aserver?

RPlay does not work with Aserver and probably won't work with other
servers.  If you want to use RPlay make sure other audio servers are
not running.

If you see errors like `/dev/audio open: Device busy' then another
program is using the audio device.  Read the audio device permissions
section above.

** Ask for help

If you are still having problems send email to boyns@sdsu.edu and I
will do my best to help you out.  The RPlay mailing list is discussed
in the README file.

