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
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
+ libasound2-dev libao-dev libreadline-dev libncurses-dev \
+ libopus-dev
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
scripts which run during compilation require the EMPH(Bourne
again shell). It is most likely already installed.
- - 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(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt)
is needed to generate the C code for the command line parsers
of all paraslash executables.
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
- XREFERENCE(http://www.underbit.com/products/mad/,
libid3tag). For version-2 ID3 tag support, you'll need
the libid3tag development package libid3tag0-dev. Without
- libid3tag, only version one tags are recognized.
+ libid3tag, only version-1 tags are recognized. The mp3 tagger
+ also needs this library for modifying (id3v1 and id3v2) tags.
- XREFERENCE(http://www.xiph.org/downloads/, ogg vorbis).
For ogg vorbis streams you'll need libogg, libvorbis,
Installation
~~~~~~~~~~~~
+To build the sources from a tarball, execute
-First make sure all non-optional packages listed in the section on
-REFERENCE(Requirements, required software) are installed on your
-system.
-
-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.
-
-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.
-
-Next, install the paraslash package on all machines, you'd like this
-software to run on. If you compile from a released tarball, execute
+ ./configure && make
- (./configure && make) > /dev/null
-
-When compiling from git or from snapshots downloaded via gitweb,
-the above command will not work because the configure script is not
-included in the git repository. In this case the following command
-should be used instead:
+To build from git or a gitweb snapshot, run this command instead:
./autogen.sh
-This runs autoconf to generate the configure script, then runs it as
-above. Therefore you'll need autoconf for this to work.
-
There should be no errors but probably some warnings about missing
packages which usually implies that not all audio formats will be
supported. If headers or libs are installed at unusual locations you
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:
*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.
*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'
*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.
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).
-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,
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
- 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 the pseudo-random bytes provided
by the crypto library (openssl or libgcrypt), on the security of
-the implementation of the RSA and RC4 crypto routines and on the
+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
maintains tables containing images (e.g. album cover art) and lyrics
that can be associated with one or more audio files.
-AFS uses XREFERENCE(http://systemlinux.org/~maan/osl/, libosl), the
+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
The command
- para_client -- ls -lv
+ para_client -- ls -l=v
gives you a verbose listing of your audio files also showing which
attributes are set.
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.
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
---------------------------------------
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*
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 consits of frames of varying size, up
+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.
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
from the client to the server.
There is no knowledge about the server commands built into para_client,
-so it does not know about addblob commands. Instead, it inspects the
-first data package sent by the server for a magic string. If this
-string was found, it sends STDIN to the server, otherwise it dumps
-data from the server to STDOUT.
+so it does not know about addblob commands. Instead, the server sends
+a special "awaiting data" packet for these commands. If the client
+receives this packet, it sends STDIN to the server, otherwise it
+dumps data from the server to STDOUT.
Streaming protocols
~~~~~~~~~~~~~~~~~~~
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
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.
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
operates on undecoded PCM data (visualizers, equalizers etc.). Such
filters are called _decoders_ in general, and xxxdec is the name of
the paraslash decoder for the audio format xxx. For example, the mp3
-decoder filter is called mp3dec.
+decoder is called mp3dec.
Note that the output of the decoder is about 10 times larger than
its input. This means that filters that operate on the decoded audio
Paraslash relies on external libraries for most decoders, so these
libraries must be installed for the decoder to be included in the
-para_filter and para_audiod executables. The oggdec filter depends
-on the libogg and libvorbis libraries for example.
+executables. For example, the mp3dec filter depends on the mad library.
Forward error correction
~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~
Doxygen is a documentation system for various programming
-languages. The paraslash project uses Doxygen for generating the API
-reference on the web pages, but good source code documentation is
-also beneficial to people trying to understand the code structure
-and the interactions between the various source files.
+languages. The API reference on the paraslash web page is generated
+by doxygen.
It is more illustrative to look at the source code for examples than
-to describe the conventions for documenting the source in this manual,
-so we only describe which parts of the code need doxygen comments,
-but leave out details on documentation conventions.
+to describe the conventions in this manual, so we only describe which
+parts of the code need doxygen comments, but leave out details on
+documentation conventions.
As a rule, only the public part of the C source is documented with
Doxygen. This includes structures, defines and enumerations in header
files as well as public (non-static) C functions. These should be
-documented completely. For example each parameter and the return
-value of a public function should get a descriptive comment.
+documented completely. For example, each parameter and the return
+value of a public function should get a descriptive doxygen comment.
No doxygen comments are necessary for static functions and for
structures and enumerations in C files (which are used only within
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
~~~~~~~
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)
projects / paraslash.git / blobdiff