INSTALL

   1 Paraslash install notes
   2 =======================
   3
   4 Any knowledge of how to work with mouse and icons is not required.
   5
   6 Install all needed packages
   7 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   8 See README for a list of required software. Don't be afraid of the long
   9 list of unusal libraries: Most of them are only needed for optional
  10 programs. Autoconf will detect what is installed on your system and
  11 will only build those executables that can be built with your setup.
  12
  13
  14 Install server and client
  15 ~~~~~~~~~~~~~~~~~~~~~~~~~
  16 Install the package on all machines, you'd like this software to run on:
  17
  18         (./configure && make) > /dev/null
  19
  20 There should be no errors (but probably many warnings about missing
  21 software). Then, as root,
  22
  23         make install
  24
  25
  26 Setup user list and create rsa keys
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28 If you already have your rsa keys, skip this step. If you are new
  29 to paraslash, you have to generate an rsa key pair for each user you
  30 want to allow to connect. You need at least one user.
  31
  32 Let's assume that you'd like to run the server on host server_host
  33 as user foo, and that you want to connect from client_host as user bar.
  34
  35 As foo@server_host, create ~/.paraslash/server.users by typing the
  36 following commands:
  37
  38         target=~/.paraslash/server.users
  39         key=~/.paraslash/key.pub.bar
  40         perms=DB_READ,DB_WRITE,AFS_READ,AFS_WRITE
  41         mkdir -p ~/.paraslash
  42         echo "user bar $key $perms" >> $target
  43
  44 This gives bar full privileges.
  45
  46 Change to the bar account on client_host and generate the key-pair
  47 with the commands
  48
  49         key=~/.paraslash/key.bar
  50         mkdir -p ~/.paraslash
  51         (umask 077 && openssl genrsa -out $key)
  52
  53 Next, extract its public part:
  54
  55         pubkey=~/.paraslash/key.pub.bar
  56         openssl rsa -in $key -pubout -out $pubkey
  57
  58 and copy the public key just created to server_host (you may
  59 skip this step for a single-user setup, i.e. if foo=bar and
  60 server_host=client_host):
  61
  62         scp $pubkey foo@server_host:.paraslash/
  63
  64 Finally, tell para_client to connect to server_host:
  65
  66         echo 'hostname server_host' > ~/.paraslash/client.conf
  67
  68 Start para_server
  69 ~~~~~~~~~~~~~~~~~
  70 For the first try, we'll use the default audio file selector, the
  71 "random" selector which chooses audio files from the given directory
  72 by random. You have to tell para_server via the --random_dir command
  73 line option where this selector should look for audio files.
  74
  75         para_server --random_dir=/my/mp3/directory
  76
  77 Now you can use para_client to connect to the server and issue
  78 commands. Open a new shell (as "bar" on "client_host" in the above
  79 example) and try
  80
  81         para_client help
  82         para_client si
  83
  84 to retrieve the list of available commands and some server info.
  85
  86 Start streaming manually
  87 ~~~~~~~~~~~~~~~~~~~~~~~~
  88
  89         para_client play
  90         para_client stat 2
  91
  92 This starts streaming and dumps some information on the current song
  93 to stdout.
  94
  95 You should now be able to listen to the stream with any player
  96 capable of reading from stdin. To check this, try the following
  97 on client_host:
  98
  99         mp3:
 100
 101         para_recv -r 'http -i server_host' | para_filter -f mp3dec -f wav | para_write -w alsa
 102         or
 103         mpg123 http://server_host:8000/
 104         or
 105         xmms http://server_host:8000/
 106
 107         ogg:
 108
 109         para_recv -r 'http -i server_host' | para_filter -f oggdec -f wav | para_write -w alsa
 110
 111 If this works, proceed. Otherwise doublecheck what is logged by
 112 para_server and use the --loglevel option of para_recv, para_filter
 113 to increase verbosity.
 114
 115 Choose an audio file selector
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117 paraslash has three different audio file selectors: random (default),
 118 playlist and mysql.
 119
 120         The random selector chooses files randomly from the given
 121         directory.
 122
 123         The playlist selector allows to send a playlist to para_server
 124         via the lpl (load playlist) command. para_server will choose
 125         files from the loaded playlist in sequential order.
 126
 127         The mysql selector stores information about your audio
 128         files in a mysql database. It is much more involved than
 129         the other two selectors and lets you chose files in many
 130         interesting ways. If you like to use the mysql selector,
 131         read README.mysql and follow the instructions given there.
 132         Return to this document when ready.
 133
 134 The current audio file selector can be changed at runtime via
 135
 136         para_client chs new_selector
 137
 138
 139 Configure para_audiod
 140 ~~~~~~~~~~~~~~~~~~~~~
 141 In order to automatically start the right decoder at the right time
 142 and to offer to the clients some information on the current audio
 143 stream and on paraslash's internal state, you should run the local
 144 audio daemon, para_audiod, on every machine that is supposed to play
 145 the audio stream. Try
 146
 147         para_audiod -h
 148
 149 for help. Usually you have to specify at least server_host as the
 150 receiver specifier, like this:
 151
 152         -r 'mp3:http -i server_host'
 153
 154 The prefered way to use para_audiod is to run it once at system start
 155 as an unprivileged user. para_audiod needs to create a "well-known"
 156 socket for the clients to connect to. If you want to change the
 157 default socket (e.g. because you do not have write access for the
 158 directory where the socket resides), use the -s option or the config
 159 file to change the default. Note that in this case you'll also have
 160 to specify the same value for para_audioc's -s option.
 161
 162 If para_server is playing, you should be able to listen to the audio
 163 stream as soon as para_audiod is started.  Once it is running, try
 164
 165         para_audioc stat
 166
 167 That should dump some information to stdout. Other commands include
 168
 169         para_audioc off
 170         para_audioc on
 171         para_audioc sb
 172         para_audioc term
 173         para_audioc cycle
 174
 175
 176 Start para_gui
 177 ~~~~~~~~~~~~~~
 178 para_gui reads the output of "para_audioc stat" and displays that
 179 information in a curses window. It also allows you to bind keys to
 180 arbitrary commands. There are several flavours of key-bindings:
 181
 182         o internal: These are the built-in commands that can not be
 183         changed (help, quit, loglevel, version...).
 184
 185         o external: Shutdown curses before launching the given command.
 186         Useful for starting other ncurses programs from within
 187         para_gui, e.g. aumix or para_dbadm. Or, use
 188
 189                 para_client mbox
 190
 191         to write a mailbox containing one mail for each file
 192         in the mysql database and start mutt from within para_gui
 193         to browse your collection!
 194
 195         o display: Launch the command and display its stdout in
 196         para_gui's bottom window.
 197
 198         o para: Like display, but start "para_client <specified
 199         command>" instead of "<specified command>".
 200
 201
 202 That's all, congratulations. Check out all the other optional gimmics!
 203
 204 Troubles?
 205 ~~~~~~~~~
 206 If something went wrong, look at the output. If that does not give
 207 you a clue, use loglevel one (option -l 1 for most commands) to show
 208 debugging info. Almost all paraslash executables have a brief online
 209 help which is displayed by using the -h switch.
 210
 211 Still not working? Mail the author Andre Noll <maan@systemlinux.org>
 212 (english, german, or spanish language). Please provide enough info
 213 such as the version of paraslash you are using and relevant parts of
 214 the logs.