manual: Move /var/paraslash instructions to Troubleshooting.
[paraslash.git] / web / manual.m4
index 2af59f5376b4ecfadc6ce12a38b5781698b276ce..b7e059785b193ccb67a1c47d34a6d60143b23229 100644 (file)
@@ -77,11 +77,11 @@ The paraslash executables
 
 *para_server*
 
-para_server streams binary audio data (MP3, OGG/Vorbis, OGG/Speex,
-M4A, WMA files) over local and/or remote networks. It listens on a
-TCP port and accepts commands such as play, stop, pause, next from
-authenticated clients. There are many more commands though, see the
-man page of para_server for a description of all commands.
+para_server streams binary audio data (MP3, ...) over local and/or
+remote networks. It listens on a TCP port and accepts commands such
+as play, stop, pause, next from authenticated clients. There are
+many more commands though, see the man page of para_server for a
+description of all commands.
 
 It supports three built-in network streaming protocols
 (senders/receivers): HTTP, DCCP, or UDP. This is explained in more
@@ -112,9 +112,12 @@ can be used by any scripting language to produce user interfaces with
 little programming effort.
 
 All connections between para_server and para_client are encrypted
-with a symmetric RC4 session key. For each user of paraslash you must
+with a symmetric session key. For each user of paraslash you must
 create a public/secret RSA key pair for authentication.
 
+If para_client is started without non-option arguments, an interactive
+session (shell) is started. Command history and command completion are
+supported through libreadline.
 
 *para_audiod*
 
@@ -135,12 +138,19 @@ socket credentials, if available.
 
 The client program which talks to para_audiod. Used to control
 para_audiod, to receive status info, or to grab the stream at any
-point of the decoding process.
+point of the decoding process. Like para_client, para_audioc supports
+interactive sessions on systems with libreadline.
 
 *para_recv*
 
 A command line HTTP/DCCP/UDP stream grabber. The http mode is
 compatible with arbitrary HTTP streaming sources (e.g. icecast).
+In addition to the three network streaming modes, para_recv can also
+operate in local (afh) mode. In this mode it writes the content of
+an audio file on the local file system in complete chunks to stdout,
+optionally 'just in time'. This allows to cut an audio file without
+first decoding it, and it enables third-party software which is unaware
+of the particular audio format to send complete frames in real time.
 
 *para_filter*
 
@@ -155,11 +165,7 @@ for audio volume.
 
 A small stand-alone program that prints tech info about the given
 audio file to STDOUT. It can be instructed to print a "chunk table",
-an array of offsets within the audio file or to write the content of
-the audio file in complete chunks 'just in time'.
-
-This allows third-party streaming software that is unaware of the
-particular audio format to send complete frames in real time.
+an array of offsets within the audio file.
 
 *para_write*
 
@@ -168,6 +174,9 @@ output plug-in and optional WAV/raw players for ALSA (Linux) and for
 coreaudio (Mac OS). para_write can also be used as a stand-alone WAV
 or raw audio player.
 
+*para_play*
+
+A command line audio player.
 
 *para_gui*
 
@@ -179,7 +188,7 @@ can be added easily.
 
 *para_fade*
 
-An (OSS-only) alarm clock and volume-fader.
+An alarm clock and volume-fader for OSS and ALSA.
 
 -----------
 Quick start
@@ -193,18 +202,28 @@ REFERENCE(Quick start, set up) a typical server and client.
 
 Requirements
 ~~~~~~~~~~~~
+For the impatient:
+
+       git clone git://git.tuebingen.mpg.de/osl
+       cd osl && make && sudo make install && sudo ldconfig
+       sudo apt-get install autoconf libssl-dev help2man gengetopt \
+              libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
+              libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+              libasound2-dev libao-dev libreadline-dev libncurses-dev \
+              libopus-dev
 
-In any case you'll need
+Detailed description: In any case you'll need
 
-       - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl).
+       - XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl).
        The _object storage layer_ library is used by para_server. To
        clone the source code repository, execute
 
        git clone git://git.tuebingen.mpg.de/osl
 
-       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc). The
-       EMPH(gnu compiler collection) is usually shipped with the
-       distro. gcc-3.3 or newer is required.
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc) or
+       XREFERENCE(http://clang.llvm.org, clang). All gcc versions
+       >= 3.3 are currently supported. Clang version 1.1 or newer
+       should work as well.
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/make, gnu make) is
        also shipped with the disto. On BSD systems the gnu make
@@ -214,17 +233,23 @@ In any case you'll need
        scripts which run during compilation require the EMPH(Bourne
        again shell).  It is most likely already installed.
 
-       - XREFERENCE(http://www.openssl.org/, openssl). The EMPH(Secure
-       Sockets Layer) library is needed for cryptographic routines
-       on both the server and the client side. It is usually shipped
-       with the distro, but you might have to install the "development
-       package" (called libssl-dev on debian systems) as well.
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt)
+       is needed to generate the C code for the command line parsers
+       of all paraslash executables.
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man)
        is used to create the man pages.
 
 Optional:
 
+       - XREFERENCE(http://www.openssl.org/, openssl) or
+       XREFERENCE(ftp://ftp.gnupg.org/gcrypt/libgcrypt/, libgcrypt).
+       At least one of these two libraries is needed as the backend
+       for cryptographic routines on both the server and the client
+       side. Both openssl and libgcrypt are usually shipped with the
+       distro, but you might have to install the development package
+       (libssl-dev or libgcrypt-dev on debian systems) as well.
+
        - XREFERENCE(http://www.underbit.com/products/mad/, libmad).
        To compile in MP3 support for paraslash, the development
        package must be installed. It is called libmad0-dev on
@@ -247,6 +272,14 @@ Optional:
        - XREFERENCE(http://www.speex.org/, speex). In order to stream
        or decode speex files, libspeex (libspeex-dev) is required.
 
+       - XREFERENCE(http://flac.sourceforge.net/, flac). To stream
+       or decode files encoded with the _Free Lossless Audio Codec_,
+       libFLAC (libFLAC-dev) must be installed.
+
+       - XREFERENCE(http://www.mega-nerd.com/SRC/index.html,
+       libsamplerate). The resample filter will only be compiled if
+       this library is installed. Debian package: libsamplerate-dev.
+
        - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On
        Linux, you'll need to have ALSA's development package
        libasound2-dev installed.
@@ -255,26 +288,23 @@ Optional:
        libao). Needed to build the ao writer (ESD, PulseAudio,...).
        Debian package: libao-dev.
 
-Installation
-~~~~~~~~~~~~
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed
+       for para_gui. Debian package: libncurses-dev.
 
-First make sure all non-optional packages listed in the section on
-REFERENCE(Requirements, required software) are installed on your
-system.
+       - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
+       GNU Readline). If this library (libreadline-dev) is installed,
+       para_client, para_audioc and para_play support interactive
+       sessions.
 
-You don't need everything listed there. In particular, MP3, OGG/Vorbis,
-OGG/Speex 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.
+Installation
+~~~~~~~~~~~~
+To build the sources from a tarball, execute
 
-Note that no special decoder library (not even the MP3 decoding library
-libmad) is needed for para_server if you only want to stream MP3 or WMA
-files. Also, it's fine to use para_server on a box without sound card.
+       ./configure && make
 
-Next, install the paraslash package on all machines, you'd like this
-software to run on:
+To build from git or a gitweb snapshot, run this command instead:
 
-       (./configure && make) > /dev/null
+       ./autogen.sh
 
 There should be no errors but probably some warnings about missing
 packages which usually implies that not all audio formats will be
@@ -323,18 +353,11 @@ following commands:
 Next, change to the "bar" account on client_host and generate the
 key pair with the commands
 
-       ssh-keygen -t rsa -b 2048
-       # hit enter twice to create a key with no passphrase
+       ssh-keygen -q -t rsa -b 2048 -N '' -f $key
 
-This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note
-that paraslash can also read keys generated by the "openssl genrsa"
-command. However, since keys created with ssh-keygen can also be used
-for ssh, this method is recommended.
-
-Note that para_server refuses to use a key if it is shorter than 2048
-bits. In particular, the RSA keys of paraslash 0.3.x will not work
-with version 0.4.x. Moreover, para_client refuses to use a (private)
-key which is world-readable.
+This generates the two files id_rsa and id_rsa.pub in ~/.ssh.  Note
+that para_server won't accept keys shorter than 2048 bits. Moreover,
+para_client rejects private keys which are world-readable.
 
 para_server only needs to know the public key of the key pair just
 created. Copy this public key to server_host:
@@ -351,14 +374,6 @@ Finally, tell para_client to connect to server_host:
 
 *Step 2*: Start para_server
 
-Before starting the server make sure you have write permissions to
-the directory /var/paraslash that has been created during installation:
-
-       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.
 
@@ -403,19 +418,8 @@ You may print the list of all known audio files with
 
 *Step 4*: Configure para_audiod
 
-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
-
-In order to make this directory writable for para_audiod, execute
-as bar@client_host
-
-       sudo chown $LOGNAME /var/paraslash
-
-
-We will also have to tell para_audiod that it should receive the
-audio stream from server_host via http:
+We will have to tell para_audiod that it should receive the audio
+stream from server_host via http:
 
        para_audiod -l info -r '.:http -i server_host'
 
@@ -432,9 +436,16 @@ streamed in which order.
 
 *Troubleshooting*
 
-It did not work? To find out why, try to receive, decode and play the
-stream manually using para_recv, para_filter and para_write as follows.
+If you receive a socket related error on server or audiod startup,
+make sure you have write permissions to the /var/paraslash directory:
+
+       sudo chown $LOGNAME /var/paraslash
+
+Alternatively, use the --afs-socket (para_server) or --socket
+(para_audiod) option to specify a different socket pathname.
 
+To identify streaming problems try to receive, decode and play the
+stream manually using para_recv, para_filter and para_write as follows.
 For simplicity we assume that you're running Linux/ALSA and that only
 MP3 files have been added to the database.
 
@@ -455,9 +466,9 @@ User management
 para_server uses a challenge-response mechanism to authenticate
 requests from incoming connections, similar to ssh's public key
 authentication method. Authenticated connections are encrypted using
-the RC4 stream cipher.
+a stream cipher, either RC4 or AES in integer counter mode.
 
-In this chapter we briefly describe RSA and RC4 and sketch the
+In this chapter we briefly describe RSA, RC4 and AES, and sketch the
 REFERENCE(Client-server authentication, authentication handshake)
 between para_client and para_server. User management is discussed
 in the section on REFERENCE(The user_list file, the user_list file).
@@ -467,15 +478,15 @@ in a REFERENCE(Connecting para_audiod, separate section).
 
 
 
-RSA and RC4
-~~~~~~~~~~~
+RSA, RC4, AES
+~~~~~~~~~~~~~
 
 RSA is an asymmetric block cipher which is used in many applications,
 including ssh and gpg. An RSA key consists in fact of two keys,
 called the public key and the private key. A message can be encrypted
 with either key and only the counterpart of that key can decrypt
 the message. While RSA can be used for both signing and encrypting
-a message, paraslash only uses RSA only for the latter purpose. The
+a message, paraslash uses RSA only for the latter purpose. The
 RSA public key encryption and signatures algorithms are defined in
 detail in RFC 2437.
 
@@ -487,6 +498,15 @@ strong encryption by today's standards. Since the same key must never
 be used twice, a different, randomly-generated key is used for every
 new connection.
 
+AES, the advanced encryption standard, is a well-known symmetric block
+cipher, i.e. a transformation operating on fixed-length blocks which
+is determined by a single key for both encryption and decryption. Any
+block cipher can be turned into a stream cipher by generating
+a pseudo-random key stream by encrypting successive values of a
+counter. The AES_CTR128 stream cipher used in paraslash is obtained
+in this way from the AES block cipher with a 128 bit block size.
+
+
 Client-server authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -495,22 +515,23 @@ as follows:
 
        - para_client connects to para_server and sends an
        authentication request for a user. It does so by connecting
-       to para_server, TCP 2990, the control port of para_server.
+       to TCP port 2990 of the server host. This port is called the
+       para_server _control port_.
 
        - para_server accepts the connection and forks a child process
-       which is supposed to handle the connection. The parent process
-       keeps listening on the control port while the child process
-       (also called para_server below) continues as follows.
+       which handles the incoming request. The parent process keeps
+       listening on the control port while the child process (also
+       called para_server below) continues as follows.
 
        - para_server loads the RSA public key of that user, fills a
        fixed-length buffer with random bytes, encrypts that buffer
        using the public key and sends the encrypted buffer to the
        client. The first part of the buffer is the challenge which
-       is used for authentication while the second part is the RC4
+       is used for authentication while the second part is the
        session key.
 
        - para_client receives the encrypted buffer and decrypts it
-       using the user's private key, thereby obtaining the challenge
+       with the user's private key, thereby obtaining the challenge
        buffer and the session key. It sends the SHA1 hash value of
        the challenge back to para_server and stores the session key
        for further use.
@@ -523,13 +544,13 @@ as follows:
 
        - Otherwise the user is considered authenticated and the client
        is allowed to proceed by sending a command to be executed. From
-       this point on the communication is encrypted using the RC4
-       stream cipher with the session key known to both peers.
+       this point on the communication is encrypted using the stream
+       cipher with the session key known to both peers.
 
-paraslash relies on the quality of openssl's cryptographically strong
-pseudo-random bytes, on the security of the implementation of the
-openssl RSA and RC4 crypto routines and on the infeasibility to invert
-the SHA1 function.
+paraslash relies on the quality of the pseudo-random bytes provided
+by the crypto library (openssl or libgcrypt), on the security of
+the implementation of the RSA, RC4 and AES crypto routines and on the
+infeasibility to invert the SHA1 function.
 
 Neither para_server or para_client create RSA keys on their own. This
 has to be done once for each user as sketched in REFERENCE(Quick start,
@@ -539,9 +560,9 @@ file, below).
 The user_list file
 ~~~~~~~~~~~~~~~~~~
 
-At startup para_server reads the user list file which must contain
-one line per user. The default location of the user list file may be
-changed with the --user_list option.
+At startup para_server reads the user list file which contains one
+line per user. The default location of the user list file may be
+changed with the --user-list option.
 
 There should be at least one user in this file. Each user must have
 an RSA key pair. The public part of the key is needed by para_server
@@ -588,7 +609,7 @@ restricted on platforms that support UNIX socket credentials which
 allow para_audiod to obtain the Unix credentials of the connecting
 process.
 
-Use para_audiod's --user_allow option to allow connections only for
+Use para_audiod's --user-allow option to allow connections only for
 a limited set of users.
 
 -----------------------
@@ -607,10 +628,11 @@ known audio files to those which satisfy certain criteria.  It also
 maintains tables containing images (e.g. album cover art) and lyrics
 that can be associated with one or more audio files.
 
-AFS uses libosl, the object storage layer, as the backend library
-for storing information on audio files, playlists, etc. This library
-offers functionality similar to a relational database, but is much
-more lightweight than a full database backend.
+AFS uses XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl), the
+object storage layer library, as the backend library for storing
+information on audio files, playlists, etc. This library offers
+functionality similar to a relational database, but is much more
+lightweight than a full database backend.
 
 In this chapter we sketch the setup of the REFERENCE(The AFS process,
 AFS process) during server startup and proceed with the description
@@ -620,7 +642,7 @@ and moods) explains these two audio file selection mechanisms
 in detail and contains pratical examples. The way REFERENCE(File
 renames and content changes, file renames and content changes) are
 detected is discussed briefly before the REFERENCE(Troubleshooting,
-Troubleshooting) section which concludes the chapter.
+Troubleshooting) section concludes the chapter.
 
 The AFS process
 ~~~~~~~~~~~~~~~
@@ -723,7 +745,7 @@ Similarly, the "test" bit can be removed from an audio file with
        para_client setatt test- /path/to/the/audio/file
 
 Instead of a path you may use a shell wildcard pattern. The attribute
-is applied to all audio files matching that pattern:
+is applied to all audio files matching this pattern:
 
        para_client setatt test+ '/test/directory/*'
 
@@ -779,7 +801,7 @@ can be used.
 
 Note that the images and lyrics are not interpreted at all, and also
 the playlist and the mood blobs are only investigated when the mood
-or playlist is activated by using the select command.
+or playlist is activated with the select command.
 
 *The score table*
 
@@ -795,7 +817,9 @@ next. While doing so, it computes the new score and updates the
 last_played and the num_played fields in the audio file table.
 
 The score table is recomputed by the select command which loads a
-new mood or playlist.
+mood or playlist. Audio files are chosen for streaming from the rows
+of the score table on a highest-score-first basis.
+
 
 Playlists and moods
 ~~~~~~~~~~~~~~~~~~~
@@ -807,17 +831,12 @@ terms of attributes and other type of information available in the
 audio file table. As an example, a mood can define a filename pattern,
 which is then matched against the names of audio files in the table.
 
-Selecting a mood or playlist means the generation of a ranking
-(a score table) for the set of admissible files. Audio files are
-then selected on a highest-score-first basis. The score table is
-recomputed at the moment the mood or playlist is selected.
-
 *Playlists*
 
 Playlists are accommodated in the playlist table of the afs database,
-using the aforementioned blob format for tables. A new filelist is
-created using the addpl command, by specifying the full (absolute)
-paths of all desired audio files, separated by newlines. For example
+using the aforementioned blob format for tables. A new playlist is
+created with the addpl command by specifying the full (absolute)
+paths of all desired audio files, separated by newlines. Example:
 
        find /my/mp3/dir -name "*.mp3" | para addpl my_playlist
 
@@ -837,7 +856,7 @@ A mood consists of a unique name and its *mood definition*, which is
 a set of *mood lines* containing expressions in terms of attributes
 and other data contained in the database.
 
-At any time, at most one mood can be *active* which means that
+At any time at most one mood can be *active* which means that
 para_server is going to select only files from that subset of
 admissible files.
 
@@ -947,7 +966,7 @@ The year tag is special as its value is undefined if the audio file
 has no year tag or the content of the year tag is not a number. Such
 audio files never match. Another difference is the special treatment
 if the year tag is a two-digit number. In this case either 1900 or
-2000 are added to the tag value depending on whether the number is
+2000 is added to the tag value, depending on whether the number is
 greater than 2000 plus the current year.
 
 
@@ -1022,17 +1041,18 @@ It is possible to change the behaviour of the add command by using the
 Troubleshooting
 ~~~~~~~~~~~~~~~
 
-Use the debug loglevel (option -l debug for most commands) to show
-debugging info. Almost all paraslash executables have a brief online
-help which is displayed by using the -h switch. The --detailed-help
-option prints the full help text.
+Use the debug loglevel (-l debug) to show debugging info. All paraslash
+executables have a brief online help which is displayed when -h is
+given. The --detailed-help option prints the full help text.
 
 If para_server crashed or was killed by SIGKILL (signal 9), it
 may refuse to start again because of "dirty osl tables". In this
 case you'll have to run the oslfsck program of libosl to fix your
-database. It might be necessary to use --force (even if your name
-isn't Luke). However, make sure para_server isn't running before
-executing oslfsck --force.
+database:
+
+       oslfsck -fd ~/.paraslash/afs_database-0.4
+
+However, make sure para_server isn't running before executing oslfsck.
 
 If you don't mind to recreate your database you can start
 from scratch by removing the entire database directory, i.e.
@@ -1050,6 +1070,14 @@ care about the table contents. To check for invalid table contents, use
 This prints out references to missing audio files as well as invalid
 playlists and mood definitions.
 
+Similarly, para_audiod refuses to start if its socket file exists, since
+this indicates that another instance of para_audiod is running. After
+a crash a stale socket file might remain and you must run
+
+       para_audiod --force
+
+once to fix it up.
+
 ---------------------------------------
 Audio formats and audio format handlers
 ---------------------------------------
@@ -1086,7 +1114,17 @@ Excited Linear Prediction) coding. It is designed for voice
 over IP applications, has modest complexity and a small memory
 footprint. Wideband and narrowband (telephone quality) speech are
 supported. As for Vorbis audio, Speex bit-streams are often stored
-in OGG files.
+in OGG files. As of 2012 this codec is considered obsolete since the
+Oppus codec, described below, surpasses its performance in all areas.
+
+*OGG/Opus*
+
+Opus is a lossy audio compression format standardized through RFC
+6716 in 2012. It combines the speech-oriented SILK codec and the
+low-latency CELT (Constrained Energy Lapped Transform) codec. Like
+OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG
+containers. All known software patents which cover Opus are licensed
+under royalty-free terms.
 
 *AAC*
 
@@ -1105,6 +1143,15 @@ how meta data about the file is to be encoded. The bit stream of WMA
 is composed of superframes, each containing one or more frames of
 2048 samples. For 16 bit stereo a WMA superframe is about 8K large.
 
+*FLAC*
+
+The Free Lossless Audio Codec (FLAC) compresses audio without quality
+loss. It gives better compression ratios than a general purpose
+compressor like zip or bzip2 because FLAC is designed specifically
+for audio. A FLAC-encoded file consists of frames of varying size, up
+to 16K. Each frame starts with a header that contains all information
+necessary to decode the frame.
+
 Meta data
 ~~~~~~~~~
 
@@ -1117,10 +1164,10 @@ title, album, year and comment tags. Each of these can only be at most
 32 characters long. ID3, version 2 is much more flexible but requires
 a separate library being installed for paraslash to support it.
 
-Ogg vorbis files contain meta data as Vorbis comments, which are
-typically implemented as strings of the form "[TAG]=[VALUE]". Unlike
-ID3 version 1 tags, one may use whichever tags are appropriate for
-the content.
+Ogg vorbis, ogg speex and flac files contain meta data as Vorbis
+comments, which are typically implemented as strings of the form
+"[TAG]=[VALUE]". Unlike ID3 version 1 tags, one may use whichever
+tags are appropriate for the content.
 
 AAC files usually use the MPEG-4 container format for storing meta
 data while WMA files wrap meta data as special objects within the
@@ -1138,7 +1185,7 @@ paraslash uses the word "chunk" as common term for the building blocks
 of an audio file. For MP3 files, a chunk is the same as an MP3 frame,
 while for OGG files a chunk is an OGG page, etc.  Therefore the chunk
 size varies considerably between audio formats, from a few hundred
-bytes (MP3) up to 8K (WMA).
+bytes (MP3) up to 16K (FLAC).
 
 The chunk table contains the offsets within the audio file that
 correspond to the chunk boundaries of the file. Like the meta data,
@@ -1159,10 +1206,9 @@ chunk table and reads the meta data.
 
 The audio format handler code is linked into para_server and executed
 via the _add_ command. The same code is also available as a stand-alone
-tool, para_afh, which can be used to print the technical data, the
-chunk table and the meta data of a file. Furthermore, one can use
-para_afh to cut an audio file, i.e. to select some of its chunks to
-produce a new file containing only these chunks.
+tool, para_afh, which prints the technical data, the chunk table
+and the meta data of a file. Moreover, all audio format handlers are
+combined in the afh receiver which is part of para_recv and para_play.
 
 ----------
 Networking
@@ -1366,15 +1412,21 @@ the stream.
 Examples
 ~~~~~~~~
 
-The sender command of para_server allows to (de-)activate senders
-and to change the access permissions senders at runtime. The "si"
-(server info) command is used to list the streaming options of the
-currently running server as well as the various sender access lists.
+The "si" (server info) command lists some information about the
+currently running server process.
 
--> Show client/target/access lists:
+-> Show PIDs, number of connected clients, uptime, and more:
 
        para_client si
 
+The sender command of para_server prints information about senders,
+like the various access control lists, and it allows to (de-)activate
+senders and to change the access permissions at runtime.
+
+-> List all senders
+
+       para_client sender
+
 -> Obtain general help for the sender command:
 
        para_client help sender
@@ -1384,6 +1436,10 @@ currently running server as well as the various sender access lists.
        s=http # or dccp or udp
        para_client sender $s help
 
+-> Show status of the http sender
+
+       para_client sender http status
+
 By default para_server activates both the HTTP and th DCCP sender on
 startup. This can be changed via command line options or para_server's
 config file.
@@ -1448,10 +1504,10 @@ the output to STDOUT, the filter modules of para_audiod are always
 connected to a receiver which produces the input stream and a writer
 which absorbs the output stream.
 
-Some filters depend on a specific library being installed and are
-not compiled in if this library was not found at compile time. To
-see the list of supported filters, run para_filter and para_audiod
-with the --help option. The output looks similar to the following:
+Some filters depend on a specific library and are not compiled in
+if this library was not found at compile time. To see the list of
+supported filters, run para_filter and para_audiod with the --help
+option. The output looks similar to the following:
 
        Available filters:
                compress wav amp fecdec wmadec prebuffer oggdec aacdec mp3dec
@@ -1712,7 +1768,7 @@ a curses window. By default the command
 
        para_audioc -- stat -p
 
-is executed, but this can be customized via the --stat_cmd option. In
+is executed, but this can be customized via the --stat-cmd option. In
 particular it possible to use
 
        para_client -- stat -p
@@ -1802,11 +1858,6 @@ branches, below), the git source code management tool is used for
 paraslash development. It is necessary for cloning the git repository
 and for getting updates.
 
-ftp://ftp.gnu.org/pub/gnu/gengetopt/ (gengetopt). The C code for
-the command line parsers of all paraslash executables is generated
-by gengetopt. The generated C files are shipped in the tarballs but
-are not contained in the git repository.
-
 ftp://ftp.gnu.org/pub/gnu/m4/ (m4). Some input files for gengetopt
 are generated from templates by the m4 macro processor.
 
@@ -1883,7 +1934,7 @@ the tip of topic branches you are interested in from the output of
 "git log next"). You should be able to safely build on top of them.
 
 However, at times "next" will be rebuilt from the tip of "master" to
-get rid of merge commits that will never be in "master. The commit
+get rid of merge commits that will never be in "master". The commit
 that replaces "next" will usually have the identical tree, but it
 will have different ancestry from the tip of "master".
 
@@ -2082,6 +2133,35 @@ maintain state for each listening receiver, multicast often implies
 connectionless transport, which is the reason that it is currently
 only available via UDP.
 
+Abstract socket namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~
+UNIX domain sockets are a traditional way to communicate between
+processes on the same machine. They are always reliable (see above)
+and don't reorder datagrams. Unlike TCP and UDP, UNIX domain sockets
+support passing open file descriptors or process credentials to
+other processes.
+
+The usual way to set up a UNIX domain socket (as obtained from
+socket(2)) for listening is to first bind the socket to a file system
+pathname and then call listen(2), then accept(2). Such sockets are
+called _pathname sockets_ because bind(2) creates a special socket
+file at the specified path. Pathname sockets allow unrelated processes
+to communicate with the listening process by binding to the same path
+and calling connect(2).
+
+There are two problems with pathname sockets:
+
+       * The listing process must be able to (safely) create the
+       socket special in a directory which is also accessible to
+       the connecting process.
+
+       * After an unclean shutdown of the listening process, a stale
+       socket special may reside on the file system.
+
+The abstract socket namespace is a non-portable Linux feature which
+avoids these problems. Abstract sockets are still bound to a name,
+but the name has no connection with file system pathnames.
+
 License
 ~~~~~~~
 
@@ -2128,11 +2208,14 @@ RFCs
        Congestion Control ID 2: TCP-like Congestion Control
        - XREFERENCE(http://www.ietf.org/rfc/rfc4342.txt, RFC 4342) (2006):
        Congestion Control ID 3: TCP-Friendly Rate Control (TFRC)
+       - XREFERENCE(http://www.ietf.org/rfc/rfc6716.txt, RFC 6716) (2012):
+       Definition of the Opus Audio Codec
 
 Application web pages
 ~~~~~~~~~~~~~~~~~~~~~
 
-       - XREFERENCE(http://paraslash.systemlinux.org/, paraslash)
+       - XREFERENCE(http://people.tuebingen.mpg.de/maan/paraslash/, paraslash)
+       - XREFERENCE(http://paraslash.systemlinux.org/, paraslash (alternative page))
        - XREFERENCE(http://xmms2.org/wiki/Main_Page, xmms)
        - XREFERENCE(http://www.mpg123.de/, mpg123)
        - XREFERENCE(http://gstreamer.freedesktop.org/, gstreamer)