afs: Shutdown signals on exit.
[paraslash.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 092bf87..4a86e96 100644 (file)
--- a/INSTALL
+++ b/INSTALL
-INSTALL
-=======
-
-----
 Any knowledge of how to work with mouse and icons is not required.
 
----------------------------
-Install all needed packages
----------------------------
-See
-<<
-<a href="REQUIREMENTS.html"> REQUIREMENTS </a>
->>
-for a list of required software. You don't need everything listed
-there. In particular, mp3, ogg vorbis and aac support are all
-optional. The configure script will detect what is installed on your
-system and will only try to build those executables that can be built
-with your setup.
-
-Note that no mp3 library (not even the mp3 decoding library libmad)
-is needed for para_server if you only want to stream mp3 files. Also,
-it's fine to use para_server on a box without sound card as para_server
-only sends the audio stream to connected clients.
-
--------------------------
-Install server and client
--------------------------
-
-Install the paraslash package on all machines, you'd like this software
-to run on:
-
-       (./configure && make) > /dev/null
-
-There should be no errors but probably some warnings about missing
-software packages which usually implies that not all audio formats will
-be supported. If headers or libs are installed at unusual locations
-you might need to tell the configure script where to find them. Try
-
-       ./configure --help
-
-to see a list of options. If the paraslash package was compiled
-successfully, execute as root,
-
-       make install
-
------------------------------------
-Setup user list and create RSA keys
------------------------------------
-
-Note that the RSA keys for paraslash 0.3.x will not work for version
-0.4.x as the new version requires stronger (2048 bit) keys. If you
-already have your 2048 bit keys, skip this step. If you are new to
-paraslash, you have to generate a key pair for each user you want to
-allow to connect. You need at least one user.
-
-Let's assume that you'd like to run the server on host server_host
-as user foo, and that you want to connect from client_host as user bar.
-
-As foo@server_host, create ~/.paraslash/server.users by typing the
-following commands:
-
-       user=bar
-       target=~/.paraslash/server.users
-       key=~/.paraslash/key.pub.$user
-       perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
-       mkdir -p ~/.paraslash
-       echo "user $user $key $perms" >> $target
-
-This gives "bar" the full privileges.
-
-Change to the "bar" account on client_host and generate the key-pair
-with the commands
-
-       key=~/.paraslash/key.$LOGNAME
-       mkdir -p ~/.paraslash
-       (umask 077 && openssl genrsa -out $key 2048)
-
-Next, extract its public part:
-
-       pubkey=~/.paraslash/key.pub.$LOGNAME
-       openssl rsa -in $key -pubout -out $pubkey
-
-and copy the public key just created to server_host (you may
-skip this step for a single-user setup, i.e. if foo=bar and
-server_host=client_host):
-
-       scp $pubkey foo@server_host:.paraslash/
-
-Finally, tell para_client to connect to server_host:
-
-       conf=~/.paraslash/client.conf
-       echo 'hostname server_host' > $conf
-
------------------
-Start para_server
------------------
-
-Before starting the server make sure you have write permissions to
-the directory /var/paraslash.
-
-       sudo chown $LOGNAME /var/paraslash
-
-Alternatively, use the --afs_socket Option to specify a different
-location for the afs command socket.
-
-For this first try, we'll use the info loglevel to make the output
-of para_server more verbose.
-
-       para_server -l info
-
-Now you can use para_client to connect to the server and issue
-commands. Open a new shell (as "bar" on "client_host" in the above
-example) and try
-
-       para_client help
-       para_client si
-
-to retrieve the list of available commands and some server info.
-Don't proceed if this doesn't work.
-
--------------------
-Create the database
--------------------
-
-       para_client init
-
-This creates some empty tables under ~/.paraslash/afs_database-0.4.
-You normally don't need to look at these tables, but it's good to
-know that you can start from scratch with
-
-       rm -rf ~/.paraslash/afs_database-0.4
-
-in case something went wrong.
-
-Next, you need to fill the audio file table of that database with
-contents so that para_server knows about your audio files.  Choose an
-absolute path to a directory containing some audio files and add them
-to the audio file table:
-
-       para_client add /my/mp3/dir
-
-This might take a while, so it is a good idea to start with a directory
-containing not too many audio files. Note that the table only contains
-data about the audio files found, not the files themselves.
-
-Print a list of all audio files found with
-
-       para_client ls
-
-------------------------
-Start streaming manually
-------------------------
-
-       para_client play
-       para_client -- stat -n=2
-
-This starts streaming and dumps some information about the current
-audio file to stdout.
-
-You should now be able to receive the stream and listen to it. If
-you have mpg123 or xmms handy, execute on client_host
-
-       mpg123 http://server_host:8000/
-or
-       xmms http://server_host:8000/
-
-Paraslash comes with its own receiving and playing software, which
-will be described next. Try the following on client_host (assuming
-Linux/ALSA and an mp3 stream):
-
-       para_recv -r 'http -i server_host' > file.mp3
-       # (interrupt with CTRL+C after a few seconds)
-       ls -l file.mp3 # should not be empty
-       para_filter -f mp3dec -f wav < file.mp3 > file.wav
-       ls -l file.wav # should be much bigger than file.mp3
-       para_write -w alsa < file.wav
-
-If this works, proceed. Otherwise double check what is logged by
-para_server and use the --loglevel option of para_recv, para_filter
-and para_write to increase verbosity.
-
-Next, put the pieces together:
-
-       para_recv -r 'http -i server_host' \
-               | para_filter -f mp3dec -f wav \
-               | para_write -w alsa
-
----------------------
-Configure para_audiod
----------------------
-
-In order to automatically start the right decoder at the right time
-and to offer to the clients some information on the current audio
-stream and on paraslash's internal state, you should run the local
-audio daemon, para_audiod, on every machine in your network which is
-supposed to play the audio stream. Try
-
-       para_audiod -h
-
-for help. Usually you have to specify only server_host as the receiver
-specifier for each supported audio format, like this:
-
-       para_audiod -l info -r 'mp3:http -i server_host'
-
-The preferred way to use para_audiod is to run it once at system start
-as an unprivileged user. para_audiod needs to create a "well-known"
-socket for the clients to connect to. The default path for this
-socket is
-
-       /var/paraslash/audiod_socket.$HOSTNAME
-
-so the /var/paraslash directory should be writable for the user who
-runs para_audiod.
-
-If you want to change the location of the socket, use the --socket
-option for para_audiod or the config file ~/.paraslash/audiod.conf
-to change the default. Note that in this case you'll also have to
-specify the same value for para_audioc's --socket option.
-
-If para_server is playing, you should be able to listen to the audio
-stream as soon as para_audiod is started.  Once it is running, try
-
-       para_audioc stat
-
-That should dump some information to stdout. Other commands include
-
-       para_audioc off
-       para_audioc on
-       para_audioc sb
-       para_audioc term
-       para_audioc cycle
-
---------------
-Start para_gui
---------------
-
-para_gui reads the output of "para_audioc stat" and displays that
-information in a curses window. It also allows you to bind keys to
-arbitrary commands. There are several flavours of key-bindings:
-
-       - internal: These are the built-in commands that can not be
-         changed (help, quit, loglevel, version...).
-       - external: Shutdown curses before launching the given command.
-         Useful for starting other ncurses programs from within
-         para_gui, e.g.  aumix or dialog scripts. Or, use the mbox
-         output format to write a mailbox containing one mail for each
-         (admissible) file the audio file selector knows about. Then
-         start mutt from within para_gui to browse your collection!
-       - display: Launch the command and display its stdout in
-         para_gui's bottom window.
-       - para: Like display, but start "para_client <specified
-         command>" instead of "<specified command>".
-
-This concludes the installation notes. Next thing you might to have a look
-at is how to use paraslash's audio file selector. See
-<<
-<a href="README.afs.html"> README.afs</a>
->>
+Installing lopsub
+~~~~~~~~~~~~~~~~~
+       git clone git://git.tuebingen.mpg.de/lopsub
+       cd lopsub && make && sudo make install
+       (see http://people.tuebingen.mpg.de/maan/lopsub/)
+
+Installing osl
+~~~~~~~~~~~~~~
+       git clone git://git.tuebingen.mpg.de/osl
+       cd osl && make && sudo make install
+       (see http://people.tuebingen.mpg.de/maan/osl/)
+
+Installing paraslash from tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+       ./configure && make && sudo make install
+
+Installing paraslash from git
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+       autoconf && autoheader && make && sudo make install
+
+Example for cross-compiling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+       export CC='armv6j-hardfloat-linux-gnueabi-gcc'
+       export PATH="/usr/cross/arm/bin:$PATH"
+       export LDFLAGS='
+               -L/usr/sysroot/arm/lib
+               -L/usr/sysroot/arm/usr/lib
+               -L/usr/sysroot/arm/usr/lib/glibc/lib
+               -L/usr/sysroot/arm/usr/local/ssl/lib
+       '
+       autoconf
+       autoheader
+       ./configure --host=arm-linux-gnueabi --prefix /usr/sysroot/arm/usr/local
+       make
+
+For details see the user manual:
+
+       http://people.tuebingen.mpg.de/maan/paraslash/manual.html