server: Add --http-listen-address and --dccp-listen-address.
[paraslash.git] / m4 / lls / server.suite.m4
1 m4_define(PROGRAM, para_server)
2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
3 [suite server]
4 version-string = GIT_VERSION()
5 [supercommand para_server]
6 purpose = manage and stream audio files
7 [description]
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.
11
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.
18
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.
22 [/description]
23 m4_include(common-option-section.m4)
24 m4_include(help.m4)
25 m4_include(detailed-help.m4)
26 m4_include(version.m4)
27 m4_include(config-file.m4)
28 m4_include(priority.m4)
29 m4_include(daemon.m4)
30 m4_include(logfile.m4)
31 m4_include(user.m4)
32 m4_include(group.m4)
33 m4_include(loglevel.m4)
34 m4_include(log-timing.m4)
35 m4_include(color.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
40 arg_type = string
41 typestr = addr
42 flag multiple
43 [help]
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).
49
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.
57
58 This option may be given multiple times. The server will then listen
59 on each of the specified addresses.
60
61 Examples: 10.10.1.1, 10.10.1.2:2991, localhost, localhost:2991,
62 [::1]:2991, [badc0de::1].
63 [/help]
64 [option port]
65 short_opt = p
66 summary = listening port of the control service
67 arg_info = required_arg
68 arg_type = uint32
69 typestr = portnumber
70 default_val = 2990
71 [help]
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.
76 [/help]
77 [option user-list]
78 summary = file which contains user names and credentials
79 arg_info = required_arg
80 arg_type = string
81 typestr = path
82 [help]
83 This file contains one line per user of the form
84
85 user <username> <key> <perms>
86
87 See the manual for more information.
88 [/help]
89 [option vss]
90 summary = Options for the virtual streaming system
91 flag ignored
92 [option autoplay]
93 summary = start streaming on startup
94 short_opt = a
95 [help]
96 The default is to defer streaming until para_client connects and
97 executes the "play" command.
98 [/help]
99 [option autoplay-delay]
100 summary = time to wait before streaming
101 arg_info = required_arg
102 arg_type = uint32
103 typestr = milliseconds
104 default_val = 0
105 [help]
106 This option is ignored if --autplay is not given. Otherwise, its
107 argument defines for how long streaming is delayed at startup.
108
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.
111 [/help]
112 [option announce-time]
113 short_opt = A
114 summary = grace time for data connections
115 arg_info = required_arg
116 arg_type = uint32
117 typestr = milliseconds
118 default_val = 300
119 [help]
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
123 of audio data.
124 [/help]
125 [option afs]
126 summary = Options for the audio file selector
127 flag ignored
128 [option afs-database-dir]
129 summary = location of the afs database
130 short_opt = D
131 arg_info = required_arg
132 arg_type = string
133 typestr = directory
134 [help]
135 The directory which contains the database for the audio file
136 selector. The default is ~/.paraslash/afs_database-0.4.
137
138 If no database was found, the "init" command must be executed to
139 initialize the database. Once initialized, audio files may added with
140 the "add" command.
141 [/help]
142 [option afs-socket]
143 summary = socket for afs connections
144 short_opt = s
145 arg_info = required_arg
146 arg_type = string
147 typestr = path
148 default_val = /var/paraslash/afs_command_socket-0.4
149 [help]
150 Server commands communicate with the audio file selector, via a
151 local socket. This option specifies the location of the socket in
152 the file system.
153 [/help]
154 [option afs-initial-mode]
155 summary = mood or playlist to load on startup
156 short_opt = i
157 arg_info = required_arg
158 arg_type = string
159 typestr = specifier/name
160 [help]
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:
164
165 --afs-initial-mode p/foo
166
167 loads the playlist named "foo".
168
169 If this option is not given, the dummy mood is loaded at startup.
170 [/help]
171 [option http]
172 summary = Options for the http sender
173 flag ignored
174 [option http-listen-address]
175 summary = listening addresses of the http sender
176 arg_info = required_arg
177 arg_type = string
178 typestr = addr
179 flag multiple
180 [help]
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.
185 [/help]
186 [option http-port]
187 summary = TCP port for http streaming
188 arg_info = required_arg
189 arg_type = uint32
190 typestr = portnumber
191 default_val = 8000
192 [help]
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.
196 [/help]
197 [option http-default-deny]
198 summary = make the http access control list a whitelist
199 [help]
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 a
202 http-access option. This allows to use access control the other way
203 round: Connections are denied from hosts which are not explicitly
204 allowed by one or more http-access options.
205 [/help]
206 [option http-access]
207 summary = add an entry to the http access control list
208 arg_info = required_arg
209 arg_type = string
210 typestr = a.b.c.d/n
211 flag multiple
212 [help]
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:
216
217 --http-access 192.168.0.0/24
218
219 whitelists/blacklists the 256 hosts 192.168.0.x.
220
221 This option may be given multiple times to blacklist/whitelist any
222 number of hosts or networks.
223 [/help]
224 [option http-no-autostart]
225 summary = do not open TCP port for http streaming on startup
226 [help]
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.
229 [/help]
230 [option http-max-clients]
231 summary = maximal number of simultaneous http connections
232 arg_info = required_arg
233 arg_type = int32
234 typestr = number
235 default_val = -1
236 [help]
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.
240 [/help]
241 [option dccp]
242 summary = Options for the dccp sender
243 flag ignored
244 [option dccp-listen-address]
245 summary = listening addresses of the dccp sender
246 arg_info = required_arg
247 arg_type = string
248 typestr = addr
249 flag multiple
250 [help]
251 Like --http-listen-address, but for the dccp sender.
252 [/help]
253 [option dccp-port]
254 summary = port for dccp streaming
255 arg_info = required_arg
256 arg_type = uint32
257 typestr = portnumber
258 default_val = 8000
259 [help]
260 See --http-port for details.
261 [/help]
262 [option dccp-default-deny]
263 summary = make the dccp access control list a whitelist
264 [help]
265 See http-default-deny for details.
266 [/help]
267 [option dccp-access]
268 summary = add an entry to the dccp access control list
269 arg_info = required_arg
270 arg_type = string
271 typestr = a.b.c.d/n
272 flag multiple
273 [help]
274 See --http-access for details.
275 [/help]
276 [option dccp-max-clients]
277 summary = maximal number of simultaneous dccp connections
278 arg_info = required_arg
279 arg_type = int32
280 typestr = number
281 default_val = -1
282 [help]
283 See --http-max-clients for details.
284 [/help]
285 [option dccp-max-slice-size]
286 summary = upper bound for the FEC slice size
287 arg_info = required_arg
288 arg_type = uint32
289 typestr = bytes
290 default_val = 0
291 [help]
292 If this value is zero (the default) the dccp sender uses the maximum
293 packet size (MPS) of the connection as the slice size. The MPS is a
294 network parameter and depends on the path maximum transmission unit
295 (path MTU) of an incoming connection, i.e. on the largest packet size
296 that can be transmitted without causing fragmentation.
297
298 This option allows to use a value less than the MPS in order to
299 fine-tune application performance. Values greater than the MPS of an
300 incoming connection can not be set.
301 [/help]
302 [option dccp-data-slices-per-group]
303 summary = the number of non-redundant slices per FEC group
304 arg_info = required_arg
305 arg_type = uint32
306 typestr = count
307 default_val = 3
308 [help]
309 This determines the number of slices in each FEC group which are
310 necessary to decode the group. The given number must be smaller than
311 the argument to the --dccp-slices-per-group option below.
312
313 Note that the duration of a FEC group is proportional to the
314 product dccp-max-slice-size * dccp-data-slices-per-group.
315 [/help]
316 [option dccp-slices-per-group]
317 summary = the total number of slices per FEC group
318 arg_info = required_arg
319 arg_type = uint32
320 typestr = count
321 default_val = 4
322 [help]
323 This value must be larger than the value of the argument to
324 --dccp-data-slices-per-group. The difference of the two values is
325 the number of redundant slices, that is, the number of slices which
326 may be lost without causing interruptions in the audio stream.
327
328 Increase this value if you are on a lossy network.
329 [/help]
330 [option udp]
331 summary = Options for the udp sender
332 flag ignored
333 [option udp-target]
334 summary = add udp target with optional port
335 arg_info = required_arg
336 arg_type = string
337 typestr = host[:port]
338 flag multiple
339 [help]
340 Add the given host/port to the list of targets. The "host" argument
341 can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
342 "port" argument is an optional port number. If the "port" part is
343 absent, the "--udp-default-port" value (see below) is used.
344
345 The following examples are possible targets: "10.10.1.2:8000"
346 (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
347 (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
348 (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
349 "[FF00::beef]:1500" (IPv6 multicast).
350
351 This option can be given multiple times, for multiple targets.
352 [/help]
353 [option udp-default-port]
354 summary = default port for udp targets
355 arg_info = required_arg
356 arg_type = uint32
357 typestr = portnumber
358 default_val = 8000
359 [option udp-no-autostart]
360 summary = do not send the audio stream to UDP targets
361 [help]
362 If this option is given, udp streaming may be activated at a later
363 time by executing the "sender" command.
364 [/help]
365 [option udp-mcast-iface]
366 summary = outgoing udp multicast interface
367 arg_info = required_arg
368 arg_type = string
369 typestr = interface
370 [option udp-header-interval]
371 short_opt = H
372 summary = duration for sending header
373 arg_info = required_arg
374 arg_type = uint32
375 typestr = milliseconds
376 default_val = 2000
377 [help]
378 As the udp sender has no idea about connected clients it sends the
379 audio file header periodically if necessary. This option specifies the
380 duration between subsequent headers are sent. Smaller values decrease
381 the average time clients have to wait before starting playback,
382 larger values decrease network traffic.
383
384 Note that this affects only ogg/* and wma streams. Other audio formats,
385 including mp3, don't need an audio file header.
386 [/help]
387 [option udp-ttl]
388 short_opt = t
389 summary = set time to live value
390 arg_info = required_arg
391 arg_type = int32
392 typestr = num
393 default_val = -1
394 [help]
395 This option applies exclusively to multicast UDPv4/v6 streaming.
396
397 For the sending UDPv4 socket it sets the multicast Time-To-Live value
398 to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
399 site, 64=same region, 128=same continent, 255=unrestricted. Please
400 note however that this scoping is not a good solution: RFC 2365
401 e.g. presents a better alternative.
402
403 When using UDPv6 multicasting, the option sets the number of multicast
404 hops (as described in RFC 3493); a value of -1 allows the kernel to
405 auto-select the hop value.
406 [/help]