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 For this first try, we'll use a debug level of two to make the
  96 output of para_server more verbose.
  97
  98         para_server -l 2
  99
 100 Now you can use para_client to connect to the server and issue
 101 commands. Open a new shell (as "bar" on "client_host" in the above
 102 example) and try
 103
 104         para_client help
 105         para_client si
 106
 107 to retrieve the list of available commands and some server info.
 108 Don't proceed if this doesn't work.
 109
 110 -------------------
 111 Create the database
 112 -------------------
 113
 114         para_client init
 115
 116 This creates some empty tables under ~/.paraslash/afs_database.
 117 You normally don't need to look at these tables, but it's good
 118 to know that you can start from scratch with
 119
 120         rm -rf ~/.paraslash/afs_database
 121
 122 in case something went wrong.
 123
 124 Next, you need to fill the audio file table of that database with
 125 contents so that para_server knows about your audio files.  Choose an
 126 absolute path to a directory containing some audio files and add them
 127 to the audio file table:
 128
 129         para_client add /my/mp3/dir
 130
 131 This might take a while, so it is a good idea to start with a directory
 132 containing not too many audio files. Note that the table only contains
 133 data about the audio files found, not the files themselves.
 134
 135 Print a list of all audio files found with
 136
 137         para_client ls
 138
 139 ------------------------
 140 Start streaming manually
 141 ------------------------
 142
 143         para_client play
 144         para_client stat 2
 145
 146 This starts streaming and dumps some information about the current
 147 audio file to stdout.
 148
 149 You should now be able to receive the stream and listen to it. If
 150 you have mpg123 or xmms handy, execute on client_host
 151
 152         mpg123 http://server_host:8000/
 153 or
 154         xmms http://server_host:8000/
 155
 156 Paraslash comes with its own receiving and playing software, which
 157 will be described next. Try the following on client_host (assuming
 158 Linux/ALSA and an mp3 stream):
 159
 160         para_recv -l 2 -r 'http -i server_host' > file.mp3
 161         # (interrupt with CTRL+C after a few seconds)
 162         ls -l file.mp3 # should not be empty
 163         para_filter -f mp3dec -f wav < file.mp3 > file.wav
 164         ls -l file.wav # should be much bigger than file.mp3
 165         para_write -w alsa < file.wav
 166
 167 If this works, proceed. Otherwise double check what is logged by
 168 para_server and use the --loglevel option of para_recv, para_filter
 169 and para_write to increase verbosity.
 170
 171 Next, put the pieces together:
 172
 173         para_recv -r 'http -i server_host' \
 174                 | para_filter -f mp3dec -f wav \
 175                 | para_write -w alsa
 176
 177 ---------------------
 178 Configure para_audiod
 179 ---------------------
 180
 181 In order to automatically start the right decoder at the right time
 182 and to offer to the clients some information on the current audio
 183 stream and on paraslash's internal state, you should run the local
 184 audio daemon, para_audiod, on every machine in your network which is
 185 supposed to play the audio stream. Try
 186
 187         para_audiod -h
 188
 189 for help. Usually you have to specify only server_host as the receiver
 190 specifier for each supported audio format, like this:
 191
 192         para_audiod -l 2 -r 'mp3:http -i server_host'
 193
 194 The preferred way to use para_audiod is to run it once at system start
 195 as an unprivileged user. para_audiod needs to create a "well-known"
 196 socket for the clients to connect to. The default path for this
 197 socket is
 198
 199         /var/paraslash/audiod_socket.$HOSTNAME
 200
 201 so the /var/paraslash directory should be writable for the user who
 202 runs para_audiod.
 203
 204 If you want to change the location of the socket, use the -s option
 205 for para_audiod or the config file ~/.paraslash/audiod.conf to change
 206 the default. Note that in this case you'll also have to specify the
 207 same value for para_audioc's -s option.
 208
 209 If para_server is playing, you should be able to listen to the audio
 210 stream as soon as para_audiod is started.  Once it is running, try
 211
 212         para_audioc stat
 213
 214 That should dump some information to stdout. Other commands include
 215
 216         para_audioc off
 217         para_audioc on
 218         para_audioc sb
 219         para_audioc term
 220         para_audioc cycle
 221
 222 --------------
 223 Start para_gui
 224 --------------
 225
 226 para_gui reads the output of "para_audioc stat" and displays that
 227 information in a curses window. It also allows you to bind keys to
 228 arbitrary commands. There are several flavours of key-bindings:
 229
 230         - internal: These are the built-in commands that can not be
 231           changed (help, quit, loglevel, version...).
 232         - external: Shutdown curses before launching the given command.
 233           Useful for starting other ncurses programs from within
 234           para_gui, e.g.  aumix or dialog scripts. Or, use the mbox
 235           output format to write a mailbox containing one mail for each
 236           (admissible) file the audio file selector knows about. Then
 237           start mutt from within para_gui to browse your collection!
 238         - display: Launch the command and display its stdout in
 239           para_gui's bottom window.
 240         - para: Like display, but start "para_client <specified
 241           command>" instead of "<specified command>".
 242
 243 This concludes the installation notes. Next thing you might to have a look
 244 at is how to use paraslash's audio file selector. See
 245 <<
 246 <a href="README.afs.html"> README.afs</a>
 247 >>