INSTALL

   1 INSTALL
   2 =======
   3
   4 ----
   5 Any knowledge of how to work with mouse and icons is not required.
   6
   7 ---------------------------
   8 Install all needed packages
   9 ---------------------------
  10 See
  11 <<
  12 <a href="REQUIREMENTS.html"> REQUIREMENTS </a>
  13 >>
  14 for a list of required software. You don't need everything listed
  15 there. In particular, mp3, ogg vorbis and aac, ortp support is
  16 optional. Autoconf will detect what is installed on your system
  17 and will only try to build those executables that can be built with
  18 your setup.
  19
  20 Note that no special library (not even the mp3 decoding library libmad)
  21 is needed for para_server if you only want to stream mp3 files.
  22 Also, it's fine to use para_server on a box without sound card as
  23 para_server only sends the audio stream to connected clients.
  24
  25 -------------------------
  26 Install server and client
  27 -------------------------
  28
  29 Install the package on all machines, you'd like this software to run on:
  30
  31         (./configure && make) > /dev/null
  32
  33 There should be no errors but probably some warnings about missing
  34 software packages which usually implies that not all audio formats will
  35 be supported. If headers or libs are installed at unusual locations
  36 you might need to tell the configure script to find them.  Try
  37
  38         ./configure --help
  39
  40 to see a list of options. If the paraslash package was compiled
  41 successfully, execute as root,
  42
  43         make install
  44
  45 -----------------------------------
  46 Setup user list and create rsa keys
  47 -----------------------------------
  48
  49 If you already have your rsa keys, skip this step. If you are new
  50 to paraslash, you have to generate an rsa key pair for each user you
  51 want to allow to connect. You need at least one user.
  52
  53 Let's assume that you'd like to run the server on host server_host
  54 as user foo, and that you want to connect from client_host as user bar.
  55
  56 As foo@server_host, create ~/.paraslash/server.users by typing the
  57 following commands:
  58
  59         user=bar
  60         target=~/.paraslash/server.users
  61         key=~/.paraslash/key.pub.$user
  62         perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
  63         mkdir -p ~/.paraslash
  64         echo "user $user $key $perms" >> $target
  65
  66 This gives "bar" the full privileges.
  67
  68 Change to the bar account on client_host and generate the key-pair
  69 with the commands
  70
  71         key=~/.paraslash/key.$LOGNAME
  72         mkdir -p ~/.paraslash
  73         (umask 077 && openssl genrsa -out $key)
  74
  75 Next, extract its public part:
  76
  77         pubkey=~/.paraslash/key.pub.$LOGNAME
  78         openssl rsa -in $key -pubout -out $pubkey
  79
  80 and copy the public key just created to server_host (you may
  81 skip this step for a single-user setup, i.e. if foo=bar and
  82 server_host=client_host):
  83
  84         scp $pubkey foo@server_host:.paraslash/
  85
  86 Finally, tell para_client to connect to server_host:
  87
  88         conf=~/.paraslash/client.conf
  89         echo 'hostname server_host' > $conf
  90
  91 -----------------
  92 Start para_server
  93 -----------------
  94
  95 Before starting the server make sure you have write permissions to
  96 the directory /var/paraslash.
  97
  98        sudo chown $user /var/paraslash
  99
 100 Alternatively, use the --afs_socket Option to specify a different
 101 location for the afs command socket.
 102
 103 For this first try, we'll use a debug level of two to make the
 104 output of para_server more verbose.
 105
 106         para_server -l 2
 107
 108 Now you can use para_client to connect to the server and issue
 109 commands. Open a new shell (as "bar" on "client_host" in the above
 110 example) and try
 111
 112         para_client help
 113         para_client si
 114
 115 to retrieve the list of available commands and some server info.
 116 Don't proceed if this doesn't work.
 117
 118 -------------------
 119 Create the database
 120 -------------------
 121
 122         para_client init
 123
 124 This creates some empty tables under ~/.paraslash/afs_database.
 125 You normally don't need to look at these tables, but it's good
 126 to know that you can start from scratch with
 127
 128         rm -rf ~/.paraslash/afs_database
 129
 130 in case something went wrong.
 131
 132 Next, you need to fill the audio file table of that database with
 133 contents so that para_server knows about your audio files.  Choose an
 134 absolute path to a directory containing some audio files and add them
 135 to the audio file table:
 136
 137         para_client add /my/mp3/dir
 138
 139 This might take a while, so it is a good idea to start with a directory
 140 containing not too many audio files. Note that the table only contains
 141 data about the audio files found, not the files themselves.
 142
 143 Print a list of all audio files found with
 144
 145         para_client ls
 146
 147 ------------------------
 148 Start streaming manually
 149 ------------------------
 150
 151         para_client play
 152         para_client stat 2
 153
 154 This starts streaming and dumps some information about the current
 155 audio file to stdout.
 156
 157 You should now be able to receive the stream and listen to it. If
 158 you have mpg123 or xmms handy, execute on client_host
 159
 160         mpg123 http://server_host:8000/
 161 or
 162         xmms http://server_host:8000/
 163
 164 Paraslash comes with its own receiving and playing software, which
 165 will be described next. Try the following on client_host (assuming
 166 Linux/ALSA and an mp3 stream):
 167
 168         para_recv -l 2 -r 'http -i server_host' > file.mp3
 169         # (interrupt with CTRL+C after a few seconds)
 170         ls -l file.mp3 # should not be empty
 171         para_filter -f mp3dec -f wav < file.mp3 > file.wav
 172         ls -l file.wav # should be much bigger than file.mp3
 173         para_write -w alsa < file.wav
 174
 175 If this works, proceed. Otherwise double check what is logged by
 176 para_server and use the --loglevel option of para_recv, para_filter
 177 and para_write to increase verbosity.
 178
 179 Next, put the pieces together:
 180
 181         para_recv -r 'http -i server_host' \
 182                 | para_filter -f mp3dec -f wav \
 183                 | para_write -w alsa
 184
 185 ---------------------
 186 Configure para_audiod
 187 ---------------------
 188
 189 In order to automatically start the right decoder at the right time
 190 and to offer to the clients some information on the current audio
 191 stream and on paraslash's internal state, you should run the local
 192 audio daemon, para_audiod, on every machine in your network which is
 193 supposed to play the audio stream. Try
 194
 195         para_audiod -h
 196
 197 for help. Usually you have to specify only server_host as the receiver
 198 specifier for each supported audio format, like this:
 199
 200         para_audiod -l 2 -r 'mp3:http -i server_host'
 201
 202 The preferred way to use para_audiod is to run it once at system start
 203 as an unprivileged user. para_audiod needs to create a "well-known"
 204 socket for the clients to connect to. The default path for this
 205 socket is
 206
 207         /var/paraslash/audiod_socket.$HOSTNAME
 208
 209 so the /var/paraslash directory should be writable for the user who
 210 runs para_audiod.
 211
 212 If you want to change the location of the socket, use the -s option
 213 for para_audiod or the config file ~/.paraslash/audiod.conf to change
 214 the default. Note that in this case you'll also have to specify the
 215 same value for para_audioc's -s option.
 216
 217 If para_server is playing, you should be able to listen to the audio
 218 stream as soon as para_audiod is started.  Once it is running, try
 219
 220         para_audioc stat
 221
 222 That should dump some information to stdout. Other commands include
 223
 224         para_audioc off
 225         para_audioc on
 226         para_audioc sb
 227         para_audioc term
 228         para_audioc cycle
 229
 230 --------------
 231 Start para_gui
 232 --------------
 233
 234 para_gui reads the output of "para_audioc stat" and displays that
 235 information in a curses window. It also allows you to bind keys to
 236 arbitrary commands. There are several flavours of key-bindings:
 237
 238         - internal: These are the built-in commands that can not be
 239           changed (help, quit, loglevel, version...).
 240         - external: Shutdown curses before launching the given command.
 241           Useful for starting other ncurses programs from within
 242           para_gui, e.g.  aumix or dialog scripts. Or, use the mbox
 243           output format to write a mailbox containing one mail for each
 244           (admissible) file the audio file selector knows about. Then
 245           start mutt from within para_gui to browse your collection!
 246         - display: Launch the command and display its stdout in
 247           para_gui's bottom window.
 248         - para: Like display, but start "para_client <specified
 249           command>" instead of "<specified command>".
 250
 251 This concludes the installation notes. Next thing you might to have a look
 252 at is how to use paraslash's audio file selector. See
 253 <<
 254 <a href="README.afs.html"> README.afs</a>
 255 >>