+#########################
section "General options"
-option "loglevel" l "set loglevel (0-6)" int typestr="level" default="4" no
-option "port" p "port to listen on" int typestr="portnumber" default="2990" no
-option "daemon" d "run as background daemon" flag off
-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 'username'. As the configuration file is read afterwards, those options that have a default value depending on the UID (e.g. the home directory for the configuration file) are computed by using the uid of 'username'. This option has no effect if para_server ist started as a non-root user (i.e. EUID != 0)" string typestr="name" no
+#########################
+option "loglevel" l
+#~~~~~~~~~~~~~~~~~~
+"set loglevel (1-6)"
+int typestr="level"
+default="4"
+optional
+details="
+ Larger values mean less verbose output. Loglevel 1 (debug) gets
+ really noisy; a value of 2 (info) produces still noisy output,
+ but this won't fill up the disk quicky. Messaged logged with
+ loglevel 3 (notice) indicate normal but significant events
+ while level 4 (warning) logs unexpected events that can be
+ handled. Unhandled error conditions are logged with loglevel
+ 5 (error) and crititcal errors are logged using loglevel 6
+ (crit). Finally, loglevel 7 (emerg) is reserved for messages
+ that cause para_server to terminate immediately.
+"
+
+option "port" p
+#~~~~~~~~~~~~~~
+"listening port"
+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
+dependon="logfile"
+details="
+ Note that para_server refuses to start in daemon mode if no
+ logfile was specified.
+"
+
+option "user" u
+#~~~~~~~~~~~~~~
+"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.
+"
+
+#############################
section "Configuration files"
-option "logfile" L "(default=stdout/stderr)" string typestr="filename" no
-option "config_file" c "(default='~/.paraslash/server.conf'" string typestr="filename" no
-option "user_list" - "(default='~/.paraslash/server.users')" string typestr="filename" no
-
-section "audio file sender"
-option "autoplay" a "start playing on startup" flag off
-option "announce_time" A "Delay betweeen announcing the stream and sending data" int typestr="milliseconds" default="300" no
-option "selector" S "(default=random)" string typestr="name" no
-
-section "mysql selector:"
-option "mysql_host" - "mysql server" string default="localhost" no
-option "mysql_port" - "where mysql is listening" int default="3306" no
-option "mysql_user" - "default value: username from /etc/passwd" string no
-option "mysql_passwd" - "(required)" string no
-option "mysql_database" - "name of mysql database" string default="paraslash" no
-option "mysql_audio_file_dir" - "dir to search for audio files (required)" string no
-option "mysql_default_score" - "scoring rule to use if stream definition does not contain explicit score definition" string default="(LASTPLAYED() / 1440 - 1000 / (LASTPLAYED() + 1) - sqrt(NUMPLAYED()))" no
-
-section "random selector"
-option "random_dir" - "dir to search for audio files" string default="/home/music" no
+#############################
+
+
+option "logfile" L
+#~~~~~~~~~~~~~~~~~
+"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
+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
+
+
+##################################
+section "virtual streaming system"
+##################################
+
+
+option "autoplay" a
+#~~~~~~~~~~~~~~~~~~
+"start playing on startup"
+flag off
+
+option "autoplay_delay" -
+#~~~~~~~~~~~~~~~~~~~~~~~~
+"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
+#~~~~~~~~~~~~~~~~~~~~~~~
+"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"
+#############################
+
+option "afs_database_dir" D
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"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 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."
+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" no
-option "http_default_deny" - "deny connections from hosts which are not explicitly allowed" flag off
-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" no multiple
-option "http_no_autostart" - "do not open tcp port on server startup" flag off
-option "http_max_clients" - "maximal simultaneous connections, non-positive value means unlimited" int typestr="number" default="-1" no
+#####################
+
+
+option "http_port" -
+#~~~~~~~~~~~~~~~~~~~
+"tcp port for http streaming"
+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" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"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 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 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 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 http streaming" int typestr="portnumber" default="5001" no
+#####################
+
+option "dccp_port" -
+#~~~~~~~~~~~~~~~~~~~
+"port for dccp streaming"
+int typestr="portnumber"
+default="8000"
+optional
+details="
+ See http_port for details.
+"
+
+option "dccp_default_deny" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"make the dccp ACL a whitelist"
+flag off
+details="
+ See http_default_deny for details.
+"
+
+option "dccp_access" -
+#~~~~~~~~~~~~~~~~~~~~~
+"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" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"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" no multiple
-option "ortp_no_autostart" - "do not start to send automatically" flag off
-option "ortp_default_port" - "default udp port if not specified" int typestr="portnumber" default="1500" no
-option "ortp_header_interval" H "time between extra header sends" int typestr="milliseconds" default="2000" no
+#####################
+
+option "ortp_target" -
+#~~~~~~~~~~~~~~~~~~~~~
+"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 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" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"udp port to send to"
+int typestr="port"
+default="1500"
+optional
+
+option "ortp_header_interval" H
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"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
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"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.
+"
projects / paraslash.git / blobdiff