From: Andre Noll <maan@systemlinux.org> Date: Sun, 16 Mar 2008 13:12:11 +0000 (+0100) Subject: More detailed and much nicer para_server man page. X-Git-Tag: v0.3.2~61^2~4 X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=56ee850b0f0c8bd7a7cc16ad9dec148e6c955faa;p=paraslash.git More detailed and much nicer para_server man page. --- diff --git a/Makefile.in b/Makefile.in index 3d3e5f71..3e5239cf 100644 --- a/Makefile.in +++ b/Makefile.in @@ -137,7 +137,7 @@ grab_client.cmdline.h grab_client.cmdline.c: grab_client.ggo server_command_lists = server_command_list.man afs_command_list.man man/man1/para_server.1: para_server $(server_command_lists) mkdir -p man/man1 - opts="-N `for i in $(server_command_lists); do echo "-i $$i"; done`"; \ + opts="-h --detailed-help -N `for i in $(server_command_lists); do echo "-i $$i"; done`"; \ help2man $$opts ./para_server > $@ man/man1/para_audiod.1: para_audiod audiod_command_list.man diff --git a/server.ggo b/server.ggo index e7149145..bbcb09b8 100644 --- a/server.ggo +++ b/server.ggo @@ -1,128 +1,144 @@ +######################### section "General options" -#~~~~~~~~~~~~~~~~~~~~~~~~ +######################### option "loglevel" l #~~~~~~~~~~~~~~~~~~ - "set loglevel (0-6)" - - int typestr="level" - default="4" - optional +int typestr="level" +default="4" +optional option "port" p #~~~~~~~~~~~~~~ - "listening port" - - int typestr="portnumber" - default="2990" - optional +int typestr="portnumber" +default="2990" +optional +details=" + para_server listens on this tcp port for incoming connections + from clients such as para_client. If the default port is + changed, the corresponding option of para_client must be used + to connect to para_server. +" option "daemon" d #~~~~~~~~~~~~~~~~ - "run as background daemon" - - flag off +flag off +details=" + Note that para_server refuses to start in daemon mode if no + logfile was specified. +" option "user" u #~~~~~~~~~~~~~~ - -"run as user 'name'. para_server does not -need any special privileges. If started as -root (EUID == 0) this option must be given at -the command line (not in the configuration -file) so that para_server can drop the root -privileges right after parsing the command -line options, but before parsing the -configuration file. In this case, -real/effective/saved UID are all set to the -UID of 'name'. As the configuration file -is read afterwards, those options that have a -default value depending on the UID (e.g. the -directory for the configuration file) are -computed by using the uid of 'name'. -This option has no effect if para_server is -started as a non-root user (i.e. EUID != 0)" - - string typestr="name" - optional +"run as the given user" +string typestr="name" +optional +details=" + para_server does not need any special privileges. If started + as root (EUID == 0) this option must be given at the command + line (not in the configuration file) so that para_server + can drop the root privileges right after parsing the command + line options, but before parsing the configuration file. In + this case, real/effective/saved UID are all set to the UID + of 'name'. As the configuration file is read afterwards, + those options that have a default value depending on the UID + (e.g. the directory for the configuration file) are computed + by using the uid of 'name'. This option has no effect if + para_server is started as a non-root user (i.e. EUID != 0) +" option "group" g #~~~~~~~~~~~~~~~ +"set group id" +string typestr="group" +optional +details=" + This option sets the group id according to 'group'. This option + is silently ignored if EUID != 0. Otherwise, real/effective + GID and the saved set-group ID are all set to the GID given by + 'group'. Must not be given in the config file. +" -"set group id to according to 'group'. This -option is silently ignored if EUID != 0. -Otherwise, real/effective GID and the saved -set-group ID are all set to the GID given by -'group'. Must not be given in the config file." - - string typestr="group" - optional - - - +############################# section "Configuration files" -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +############################# option "logfile" L #~~~~~~~~~~~~~~~~~ - -"(default=stdout/stderr)" - - string typestr="filename" - optional +"where to write log output" +string typestr="filename" +optional +details=" + If this option is not given, para_server writes the log + messages to to stderr +" option "config_file" c #~~~~~~~~~~~~~~~~~~~~~ - "(default='~/.paraslash/server.conf'" - - string typestr="filename" - optional +string typestr="filename" +optional +details=" + para_server reads its config file right after parsing + the options that were given at the command line. If an + option is given both at the command line and in the + config file, the value that was specified at the command line + takes precedence. +" option "user_list" - #~~~~~~~~~~~~~~~~~~~ - "(default='~/.paraslash/server.users')" - string typestr="filename" - optional - +string typestr="filename" +optional +################################## section "virtual streaming system" -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +################################## option "autoplay" a #~~~~~~~~~~~~~~~~~~ - "start playing on startup" - - flag off +flag off option "autoplay_delay" - #~~~~~~~~~~~~~~~~~~~~~~~~ -"Time to wait before autoplay starts. Ignored if -autoplay is off." - int typestr="milliseconds" - default="0" - optional - - +"time to wait before streaming" +int typestr="ms" +default="0" +optional +dependon="autoplay" +details=" + If para_server is started with the autoplay option, this option + may be used to set up a delay before para_server streams its + first audio file. This is useful for example if para_server + and para_audiod are started during system startup. The delay + time should be choosen large enough so that para_audiod is + already up when para_server starts to stream. Of course, this + option depends on the autoplay option. +" option "announce_time" A #~~~~~~~~~~~~~~~~~~~~~~~ - -"Delay betweeen announcing the stream and sending data" - - int typestr="milliseconds" - default="300" - optional - +"grace time for clients" + +int typestr="ms" +default="300" +optional +details=" + Clients such as para_audiod connect to para_server and execute + the stat command to find out whether an audio stream is + currently available. This sets the delay betweeen announcing + the stream via the output of the stat command and sending + the first chunk of data. +" ############################# section "audio file selector" @@ -130,180 +146,211 @@ section "audio file selector" option "afs_database_dir" D #~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"Directory containing the osl database of the -audio file selector. -(default='~/.paraslash/afs_database'" - - string typestr="path" - optional - +"location of the database" +string typestr="path" +optional +details=" + Where para_server should look for the osl + database of the audio file selector. The default is + '~/.paraslash/afs_database'. +" option "afs_socket" s #~~~~~~~~~~~~~~~~~~~~ - -"Command socket for the audio file selector" - - string typestr="path" - default="/var/paraslash/afs_command_socket" - optional - +"Command socket for afs" +string typestr="path" +default="/var/paraslash/afs_command_socket" +optional +details=" + For each server command that is handled by the audio file + selector, the child process of para_server connects to the + audio file selector via a local socket. This option specifies + the location of that socket in the file system. +" option "afs_initial_mode" i #~~~~~~~~~~~~~~~~~~~~~~~~~~ -"Mood or playlist to load on startup. Must be -prefixed with either 'p/' or 'm/' to indicate -whether a playlist or a mood should be -loaded. Example: - --afs_initial_mode p/foo -loads the playlist named 'foo'." - - string typestr="<specifier>/<name>" - optional +"Mood or playlist to load on startup." +string typestr="<specifier>/<name>" +optional +details=" + The argument of this option must be prefixed with either 'p/' + or 'm/' to indicate whether a playlist or a mood should be + loaded. Example: + --afs_initial_mode p/foo + loads the playlist named 'foo'. +" +##################### section "http sender" -#~~~~~~~~~~~~~~~~~~~~ +##################### option "http_port" - #~~~~~~~~~~~~~~~~~~~ - "tcp port for http streaming" - - int typestr="portnumber" - default="8000" - optional +int typestr="portnumber" +default="8000" +optional +details=" + The http sender of para_server listens on this port for + incoming connections. Clients are expected to send the usual + http request message such as 'GET / HTTP/'. +" option "http_default_deny" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"deny connections from hosts which are not -explicitly allowed" - - flag off +"make the http ACL a whitelist" +flag off +details=" + The default is to use blacklists instead, i.e. connections + to the http sender are allowed unless the connecting host + matches a pattern given by a http_access option. This allows + to use access control the other way round: Connections are + denied from hosts which are not explicitly allowed by one or + more http_access options. +" option "http_access" - #~~~~~~~~~~~~~~~~~~~~~ - -"Add given host/network to access control -list (whitelist if http_default_deny was -given, blacklist otherwise) before opening -the tcp port. This option can be given -multiple times. Example: '192.168.0.0/24' -whitelists/blacklists the 256 hosts -192.168.0.x" - - string typestr="a.b.c.d/n" - optional - multiple +"add an entry to the http ACL" +string typestr="a.b.c.d/n" +optional +multiple +details=" + Add given host/network to access control list (whitelist if + http_default_deny was given, blacklist otherwise) before + opening the tcp port. This option can be given multiple + times. Example: '192.168.0.0/24' whitelists/blacklists the + 256 hosts 192.168.0.x +" option "http_no_autostart" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"do not open tcp port on server startup" - - flag off +"do not open tcp port on startup" +flag off +details=" + If this option is given, the http sender does not listen on + its tcp port. It may be instructed to open this port at a + later time by using the sender command. +" option "http_max_clients" - #~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"maximal simultaneous connections, -non-positive value means unlimited" - - int typestr="number" - default="-1" - optional - - - - +"maximal number of connections" +int typestr="number" +default="-1" +optional +details=" + The http sender will refuse connections if already that number + of clients are currently connected. A non-positive value + (the default) allows an unlimited number of simultaneous + connections. +" + +##################### section "dccp sender" -#~~~~~~~~~~~~~~~~~~~~ +##################### option "dccp_port" - #~~~~~~~~~~~~~~~~~~~ - "port for dccp streaming" - - int typestr="portnumber" - default="8000" - optional +int typestr="portnumber" +default="8000" +optional +details=" + See http_port for details. +" option "dccp_default_deny" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"See http_default_deny" - - flag off +"make the dccp ACL a whitelist" +flag off +details=" + See http_default_deny for details. +" option "dccp_access" - #~~~~~~~~~~~~~~~~~~~~~ -"See http_access" - - string typestr="a.b.c.d/n" - optional - multiple +"add an entry to the dccp ACL" +string typestr="a.b.c.d/n" +optional +multiple +details=" + See http_access for details. +" option "dccp_max_clients" - #~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"see http_max_clients" - - int typestr="number" - default="-1" - optional - - +"maximal number of connections" +int typestr="number" +default="-1" +optional +details=" + See http_max_clients for details. +" + +##################### section "ortp sender" -#~~~~~~~~~~~~~~~~~~~~ +##################### option "ortp_target" - #~~~~~~~~~~~~~~~~~~~~~ - -"Add given host/port to the list of targets. -This option can be given multiple times. -Example: '224.0.1.38:1500' instructs the ortp -sender to send to udp port 1500 on host -224.0.1.38 (unassigned ip in the Local -Network Control Block 224.0.0/24). This is -useful for LAN-streaming." - - string typestr="a.b.c.d:p" - optional - multiple +"add ortp target" +string typestr="a.b.c.d:p" +optional +multiple +details=" + Add given host/port to the list of targets. This option + can be given multiple times. Example: '224.0.1.38:1500' + instructs the ortp sender to send to udp port 1500 on host + 224.0.1.38 (unassigned ip in the Local Network Control Block + 224.0.0/24). This is useful for LAN-streaming. +" option "ortp_no_autostart" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"do not start to send automatically" - - flag off +"do not start sending" +flag off +details=" + If this option is given, ortp streaming may be activated at + a later time by using the sender command. +" option "ortp_default_port" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"default udp port if not specified" - - int typestr="portnumber" - default="1500" - optional +"udp port to send to" +int typestr="port" +default="1500" +optional option "ortp_header_interval" H #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"time between extra header sends" - - int typestr="milliseconds" - default="2000" - optional +"duration for sending header" +int typestr="ms" +default="2000" +optional +details=" + As the ortp sender has no idea about connected clients it + sends the audio file header periodically if necessary. This + option is used to specify the duration of the interval between + sending the header. Shorter values decrease the average time + clients have to wait before being able to start playback, + but this also increases the amount network traffic. Note + that this affects only ogg vorbis streams as this is the only + audio format that needs an audio file header. +" option "ortp_jitter_compensation" j #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"non-zero values enable ortp's adaptive -jitter compensation" - - int typestr="milliseconds" - default="400" - optional +"configure jitter compensation" +int typestr="ms" +default="400" +optional +details=" + ortp's adaptive jitter compensation gets activated whenever + this value is greater than zero. See the ortp documentation + about details on this feature. +"