X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=web%2Fmanual.m4;h=20cae69ab7e00d6d50b8f5026ab5c42d8e39c33b;hb=62a2e10a42e4f9b6556ba7e58f70f52ffa3dfa99;hp=56ee3469fbe666dda6ef470644ec18c3b86715e2;hpb=107d4619b3a6a8bdc1a85c8021cb1951244e7626;p=paraslash.git diff --git a/web/manual.m4 b/web/manual.m4 index 56ee3469..20cae69a 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -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,7 +112,7 @@ 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 @@ -145,6 +145,12 @@ interactive sessions on systems with libreadline. 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* @@ -159,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* @@ -172,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* @@ -197,8 +202,16 @@ 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 -In any case you'll need +Detailed description: In any case you'll need - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl). The _object storage layer_ library is used by para_server. To @@ -219,14 +232,6 @@ 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) 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. @@ -236,6 +241,14 @@ In any case you'll need 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 @@ -262,6 +275,10 @@ Optional: 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. @@ -270,9 +287,13 @@ Optional: libao). Needed to build the ao writer (ESD, PulseAudio,...). Debian package: libao-dev. + - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed + for para_gui. Debian package: libncurses-dev. + - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html, GNU Readline). If this library (libreadline-dev) is installed, - para_client and para_audioc support interactive sessions. + para_client, para_audioc and para_play support interactive + sessions. Installation ~~~~~~~~~~~~ @@ -385,7 +406,7 @@ 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 +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 @@ -484,9 +505,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). @@ -496,8 +517,8 @@ 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, @@ -516,6 +537,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -536,7 +566,7 @@ as follows: 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 @@ -553,12 +583,12 @@ 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 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 @@ -571,7 +601,7 @@ The user_list file 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. +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 @@ -618,7 +648,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. ----------------------- @@ -1749,7 +1779,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