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.4.
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
175 summary = TCP port for http streaming
176 arg_info = required_arg
181 The http sender of para_server listens on this port for incoming
182 connections. Clients are expected to send the usual http request
183 message such as 'GET / HTTP/'.
185 [option http-default-deny]
186 summary = make the http access control list a whitelist
188 The default is to use blacklists, i.e. connections to the http sender
189 are allowed unless the connecting host matches a pattern given by a
190 http-access option. This allows to use access control the other way
191 round: Connections are denied from hosts which are not explicitly
192 allowed by one or more http-access options.
195 summary = add an entry to the http access control list
196 arg_info = required_arg
201 Add the given host/network to access control list (whitelist if
202 http-default-deny was given, blacklist otherwise) before opening
203 the tcp port. This option can be given multiple times. Example:
205 --http-access 192.168.0.0/24
207 whitelists/blacklists the 256 hosts 192.168.0.x.
209 This option may be given multiple times to blacklist/whitelist any
210 number of hosts or networks.
212 [option http-no-autostart]
213 summary = do not open TCP port for http streaming on startup
215 If this option is given, the http sender does not listen on its TCP
216 port until the "sender" command is executed to open the port.
218 [option http-max-clients]
219 summary = maximal number of simultaneous http connections
220 arg_info = required_arg
225 The http sender will refuse connections if already that number of
226 clients are currently connected. A non-positive value (the default)
227 allows for an unlimited number of simultaneous connections.
230 summary = Options for the dccp sender
233 summary = port for dccp streaming
234 arg_info = required_arg
239 See --http-port for details.
241 [option dccp-default-deny]
242 summary = make the dccp access control list a whitelist
244 See http-default-deny for details.
247 summary = add an entry to the dccp access control list
248 arg_info = required_arg
253 See --http-access for details.
255 [option dccp-max-clients]
256 summary = maximal number of simultaneous dccp connections
257 arg_info = required_arg
262 See --http-max-clients for details.
264 [option dccp-max-slice-size]
265 summary = upper bound for the FEC slice size
266 arg_info = required_arg
271 If this value is zero (the default) the dccp sender uses the maximum
272 packet size (MPS) of the connection as the slice size. The MPS is a
273 network parameter and depends on the path maximum transmission unit
274 (path MTU) of an incoming connection, i.e. on the largest packet size
275 that can be transmitted without causing fragmentation.
277 This option allows to use a value less than the MPS in order to
278 fine-tune application performance. Values greater than the MPS of an
279 incoming connection can not be set.
281 [option dccp-data-slices-per-group]
282 summary = the number of non-redundant slices per FEC group
283 arg_info = required_arg
288 This determines the number of slices in each FEC group which are
289 necessary to decode the group. The given number must be smaller than
290 the argument to the --dccp-slices-per-group option below.
292 Note that the duration of a FEC group is proportional to the
293 product dccp-max-slice-size * dccp-data-slices-per-group.
295 [option dccp-slices-per-group]
296 summary = the total number of slices per FEC group
297 arg_info = required_arg
302 This value must be larger than the value of the argument to
303 --dccp-data-slices-per-group. The difference of the two values is
304 the number of redundant slices, that is, the number of slices which
305 may be lost without causing interruptions in the audio stream.
307 Increase this value if you are on a lossy network.
310 summary = Options for the udp sender
313 summary = add udp target with optional port
314 arg_info = required_arg
316 typestr = host[:port]
319 Add the given host/port to the list of targets. The "host" argument
320 can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
321 "port" argument is an optional port number. If the "port" part is
322 absent, the "--udp-default-port" value (see below) is used.
324 The following examples are possible targets: "10.10.1.2:8000"
325 (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
326 (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
327 (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
328 "[FF00::beef]:1500" (IPv6 multicast).
330 This option can be given multiple times, for multiple targets.
332 [option udp-default-port]
333 summary = default port for udp targets
334 arg_info = required_arg
338 [option udp-no-autostart]
339 summary = do not send the audio stream to UDP targets
341 If this option is given, udp streaming may be activated at a later
342 time by executing the "sender" command.
344 [option udp-mcast-iface]
345 summary = outgoing udp multicast interface
346 arg_info = required_arg
349 [option udp-header-interval]
351 summary = duration for sending header
352 arg_info = required_arg
354 typestr = milliseconds
357 As the udp sender has no idea about connected clients it sends the
358 audio file header periodically if necessary. This option specifies the
359 duration between subsequent headers are sent. Smaller values decrease
360 the average time clients have to wait before starting playback,
361 larger values decrease network traffic.
363 Note that this affects only ogg/* and wma streams. Other audio formats,
364 including mp3, don't need an audio file header.
368 summary = set time to live value
369 arg_info = required_arg
374 This option applies exclusively to multicast UDPv4/v6 streaming.
376 For the sending UDPv4 socket it sets the multicast Time-To-Live value
377 to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
378 site, 64=same region, 128=same continent, 255=unrestricted. Please
379 note however that this scoping is not a good solution: RFC 2365
380 e.g. presents a better alternative.
382 When using UDPv6 multicasting, the option sets the number of multicast
383 hops (as described in RFC 3493); a value of -1 allows the kernel to
384 auto-select the hop value.