1 m4_define(PROGRAM, para_server)
2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
4 version-string = GIT_VERSION()
5 [supercommand para_server]
6 purpose = manage and stream audio files
8 para_server streams audio files over a local or remote network. It
9 is controlled by para_client(1), which connects para_server through
10 the paraslash control service.
12 On startup the server spawns a second process, the audio file selector,
13 which maintains the database of all known audio files. This database
14 contains file format, duration and tag information of each known file
15 and statistics such as last-played time, and the number of times each
16 file was streamed. Lyrics and cover art may be added to the database
17 and associated with one or more audio files.
19 Besides ordinary playlists the audio file selector supports so-called
20 moods. Moods instruct the server to determine the files to be streamed
21 and their order in terms of properties stored in the database.
23 m4_include(common-option-section.m4)
25 m4_include(detailed-help.m4)
26 m4_include(version.m4)
27 m4_include(config-file.m4)
28 m4_include(priority.m4)
30 m4_include(logfile.m4)
33 m4_include(loglevel.m4)
34 m4_include(log-timing.m4)
36 m4_include(per-command-options-section.m4)
37 [option listen-address]
38 summary = local listening addresses for the control service
39 arg_info = required_arg
44 para_server listens on a TCP socket for incoming connections from
45 para_client or para_audiod. This option controls on which addresses
46 the server should listen. If the option is not given, the server
47 listens on all local addresses (INADDR_ANY for IPv4 addresses,
48 IN6ADDR_ANY_INIT for IPv6 addresses).
50 The argument specifies an IPv4 or an IPv6 address, either a numerical
51 network address (for IPv4, numbers-and-dots notation as supported
52 by inet_aton(3); for IPv6, hexadecimal string format as supported
53 by inet_pton(3)), or a network hostname, whose network addresses is
54 looked up and resolved. The address can optionally include a port
55 number. For addresses for which no port number is given, the argument
56 of the --port option (see below) is implied.
58 This option may be given multiple times. The server will then listen
59 on each of the specified addresses.
61 Examples: 10.10.1.1, 10.10.1.2:2991, localhost, localhost:2991,
62 [::1]:2991, [badc0de::1].
66 summary = listening port of the control service
67 arg_info = required_arg
72 This option applies only to addresses given to --listen-address
73 (see above) which do no include a port number. If the default port
74 is changed, the corresponding option of para_client must be used to
75 connect to para_server.
78 summary = file which contains user names and credentials
79 arg_info = required_arg
83 This file contains one line per user of the form
85 user <username> <key> <perms>
87 See the manual for more information.
90 summary = Options for the virtual streaming system
93 summary = start streaming on startup
96 The default is to defer streaming until para_client connects and
97 executes the "play" command.
99 [option autoplay-delay]
100 summary = time to wait before streaming
101 arg_info = required_arg
103 typestr = milliseconds
106 This option is ignored if --autplay is not given. Otherwise, its
107 argument defines for how long streaming is delayed at startup.
109 This is useful in init scripts to set the delay large enough to make
110 sure para_audiod is up when para_server starts to stream.
112 [option announce-time]
114 summary = grace time for data connections
115 arg_info = required_arg
117 typestr = milliseconds
120 para_server tells para_audiod through the control service connection
121 whether an audio stream is currently available. This option defines
122 the delay between announcing the stream and sending the first chunk
126 summary = Options for the audio file selector
128 [option afs-database-dir]
129 summary = location of the afs database
131 arg_info = required_arg
135 The directory which contains the database for the audio file
136 selector. The default is ~/.paraslash/afs_database-0.7.
138 If no database was found, the "init" command must be executed to
139 initialize the database. Once initialized, audio files may added with
143 summary = socket for afs connections
145 arg_info = required_arg
148 default_val = /var/paraslash/afs_command_socket-0.4
150 Server commands communicate with the audio file selector, via a
151 local socket. This option specifies the location of the socket in
154 [option afs-initial-mode]
155 summary = mood or playlist to load on startup
157 arg_info = required_arg
159 typestr = specifier/name
161 The argument of this option consists of a prefix, either 'm/' or
162 'p/', to indicate whether a mood or a playlist should be loaded,
163 followed by the name of the mood or playlist. Example:
165 --afs-initial-mode p/foo
167 loads the playlist named "foo".
169 If this option is not given, the dummy mood is loaded at startup.
172 summary = Options for the http sender
174 [option http-listen-address]
175 summary = listening addresses of the http sender
176 arg_info = required_arg
181 The http sender of para_server listens on this port for incoming data
182 connections. This option controls on which addresses the http sender
183 should listen. See the documentation of the --listen-address above
184 for the format of the address argument and the defaults.
187 summary = TCP port for http streaming
188 arg_info = required_arg
193 This option has the same meaning as --port, but applies to http
194 data connections and applies to the addresses specified as arguments
195 to --http-listen-address.
197 [option http-default-deny]
198 summary = make the http access control list a whitelist
200 The default is to use blacklists, i.e. connections to the http sender
201 are allowed unless the connecting host matches a pattern given by
202 a http-access option. This option allows using access control lists
203 the other way round: Connections are denied from hosts which are not
204 explicitly allowed by one or more http-access options.
207 summary = add an entry to the http access control list
208 arg_info = required_arg
213 Add the given host/network to access control list (whitelist if
214 http-default-deny was given, blacklist otherwise) before opening
215 the tcp port. This option can be given multiple times. Example:
217 --http-access 192.168.0.0/24
219 whitelists/blacklists the 256 hosts 192.168.0.x.
221 This option may be given multiple times to blacklist/whitelist any
222 number of hosts or networks.
224 [option http-no-autostart]
225 summary = do not open TCP port for http streaming on startup
227 If this option is given, the http sender does not listen on its TCP
228 port until the "sender" command is executed to open the port.
230 [option http-max-clients]
231 summary = maximal number of simultaneous http connections
232 arg_info = required_arg
237 The http sender will refuse connections if already that number of
238 clients are currently connected. A non-positive value (the default)
239 allows for an unlimited number of simultaneous connections.
242 summary = Options for the dccp sender
244 [option dccp-listen-address]
245 summary = listening addresses of the dccp sender
246 arg_info = required_arg
251 Like --http-listen-address, but for the dccp sender.
254 summary = port for dccp streaming
255 arg_info = required_arg
260 See --http-port for details.
262 [option dccp-default-deny]
263 summary = make the dccp access control list a whitelist
265 See http-default-deny for details.
268 summary = add an entry to the dccp access control list
269 arg_info = required_arg
274 See --http-access for details.
276 [option dccp-no-autostart]
277 summary = do not open the DCCP port on startup
279 This is like --http-no-autostart but applies to the dccp sender.
281 [option dccp-max-clients]
282 summary = maximal number of simultaneous dccp connections
283 arg_info = required_arg
288 See --http-max-clients for details.
290 [option dccp-max-slice-size]
291 summary = upper bound for the FEC slice size
292 arg_info = required_arg
297 If this value is zero (the default) the dccp sender uses the maximum
298 packet size (MPS) of the connection as the slice size. The MPS is a
299 network parameter and depends on the path maximum transmission unit
300 (path MTU) of an incoming connection, i.e. on the largest packet size
301 that can be transmitted without causing fragmentation.
303 This option allows values less than the MPS in order to fine-tune
304 application performance. Values greater than the MPS of an incoming
305 connection can not be set.
307 [option dccp-data-slices-per-group]
308 summary = the number of non-redundant slices per FEC group
309 arg_info = required_arg
314 This determines the number of slices in each FEC group which are
315 necessary to decode the group. The given number must be smaller than
316 the argument to the --dccp-slices-per-group option below.
318 Note that the duration of a FEC group is proportional to the
319 product dccp-max-slice-size * dccp-data-slices-per-group.
321 [option dccp-slices-per-group]
322 summary = the total number of slices per FEC group
323 arg_info = required_arg
328 This value must be larger than the value of the argument to
329 --dccp-data-slices-per-group. The difference of the two values is
330 the number of redundant slices, that is, the number of slices which
331 may be lost without causing interruptions in the audio stream.
333 Increase this value if you are on a lossy network.
336 summary = Options for the udp sender
339 summary = add udp target with optional port
340 arg_info = required_arg
342 typestr = host[:port]
345 Add the given host/port to the list of targets. The "host" argument
346 can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
347 "port" argument is an optional port number. If the "port" part is
348 absent, the "--udp-default-port" value (see below) is used.
350 The following examples are possible targets: "10.10.1.2:8000"
351 (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
352 (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
353 (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
354 "[FF00::beef]:1500" (IPv6 multicast).
356 This option can be given multiple times, for multiple targets.
358 [option udp-default-port]
359 summary = default port for udp targets
360 arg_info = required_arg
364 [option udp-no-autostart]
365 summary = do not send the audio stream to UDP targets
367 If this option is given, udp streaming may be activated at a later
368 time by executing the "sender" command.
370 [option udp-mcast-iface]
371 summary = outgoing udp multicast interface
372 arg_info = required_arg
375 [option udp-header-interval]
377 summary = duration for sending header
378 arg_info = required_arg
380 typestr = milliseconds
383 As the udp sender has no idea about connected clients it sends the
384 audio file header periodically if necessary. This option specifies the
385 duration between subsequent headers are sent. Smaller values decrease
386 the average time clients have to wait before starting playback,
387 larger values decrease network traffic.
389 Note that this affects only ogg/* and wma streams. Other audio formats,
390 including mp3, don't need an audio file header.
394 summary = set time to live value
395 arg_info = required_arg
400 This option applies exclusively to multicast UDPv4/v6 streaming.
402 For the sending UDPv4 socket it sets the multicast Time-To-Live value
403 to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
404 site, 64=same region, 128=same continent, 255=unrestricted. Please
405 note however that this scoping is not a good solution: RFC 2365
406 e.g. presents a better alternative.
408 When using UDPv6 multicasting, the option sets the number of multicast
409 hops (as described in RFC 3493); a value of -1 allows the kernel to
410 auto-select the hop value.