Merge branch 'refs/heads/t/clean_server_exit'
[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 port]
38 short_opt = p
39 summary = listening port of the paraslash control service
40 arg_info = required_arg
41 arg_type = uint32
42 typestr = portnumber
43 default_val = 2990
44 [help]
45 para_server listens on this TCP port for incoming connections
46 from clients such as para_client. If the default port is changed,
47 the corresponding option of para_client must be used to connect
48 to para_server.
49 [/help]
50 [option user-list]
51 summary = file which contains user names and credentials
52 arg_info = required_arg
53 arg_type = string
54 typestr = path
55 [help]
56 This file contains one line per user of the form
57
58 user <username> <key> <perms>
59
60 See the manual for more information.
61 [/help]
62 [option vss]
63 summary = Options for the virtual streaming system
64 flag ignored
65 [option autoplay]
66 summary = start streaming on startup
67 short_opt = a
68 [help]
69 The default is to defer streaming until para_client connects and
70 executes the "play" command.
71 [/help]
72 [option autoplay-delay]
73 summary = time to wait before streaming
74 arg_info = required_arg
75 arg_type = uint32
76 typestr = milliseconds
77 default_val = 0
78 [help]
79 This option is ignored if --autplay is not given. Otherwise, its
80 argument defines for how long streaming is delayed at startup.
81
82 This is useful in init scripts to set the delay large enough to make
83 sure para_audiod is up when para_server starts to stream.
84 [/help]
85 [option announce-time]
86 short_opt = A
87 summary = grace time for data connections
88 arg_info = required_arg
89 arg_type = uint32
90 typestr = milliseconds
91 default_val = 300
92 [help]
93 para_server tells para_audiod through the control service connection
94 whether an audio stream is currently available. This option defines
95 the delay between announcing the stream and sending the first chunk
96 of audio data.
97 [/help]
98 [option afs]
99 summary = Options for the audio file selector
100 flag ignored
101 [option afs-database-dir]
102 summary = location of the afs database
103 short_opt = D
104 arg_info = required_arg
105 arg_type = string
106 typestr = directory
107 [help]
108 The directory which contains the database for the audio file
109 selector. The default is ~/.paraslash/afs_database-0.4.
110
111 If no database was found, the "init" command must be executed to
112 initialize the database. Once initialized, audio files may added with
113 the "add" command.
114 [/help]
115 [option afs-socket]
116 summary = socket for afs connections
117 short_opt = s
118 arg_info = required_arg
119 arg_type = string
120 typestr = path
121 default_val = /var/paraslash/afs_command_socket-0.4
122 [help]
123 Server commands communicate with the audio file selector, via a
124 local socket. This option specifies the location of the socket in
125 the file system.
126 [/help]
127 [option afs-initial-mode]
128 summary = mood or playlist to load on startup
129 short_opt = i
130 arg_info = required_arg
131 arg_type = string
132 typestr = specifier/name
133 [help]
134 The argument of this option consists of a prefix, either 'm/' or
135 'p/', to indicate whether a mood or a playlist should be loaded,
136 followed by the name of the mood or playlist. Example:
137
138 --afs-initial-mode p/foo
139
140 loads the playlist named "foo".
141
142 If this option is not given, the dummy mood is loaded at startup.
143 [/help]
144 [option http]
145 summary = Options for the http sender
146 flag ignored
147 [option http-port]
148 summary = TCP port for http streaming
149 arg_info = required_arg
150 arg_type = uint32
151 typestr = portnumber
152 default_val = 8000
153 [help]
154 The http sender of para_server listens on this port for incoming
155 connections. Clients are expected to send the usual http request
156 message such as 'GET / HTTP/'.
157 [/help]
158 [option http-default-deny]
159 summary = make the http access control list a whitelist
160 [help]
161 The default is to use blacklists, i.e. connections to the http sender
162 are allowed unless the connecting host matches a pattern given by
163 a http-access option. This option allows using access control lists
164 the other way round: Connections are denied from hosts which are not
165 explicitly allowed by one or more http-access options.
166 [/help]
167 [option http-access]
168 summary = add an entry to the http access control list
169 arg_info = required_arg
170 arg_type = string
171 typestr = a.b.c.d/n
172 flag multiple
173 [help]
174 Add the given host/network to access control list (whitelist if
175 http-default-deny was given, blacklist otherwise) before opening
176 the tcp port. This option can be given multiple times. Example:
177
178 --http-access 192.168.0.0/24
179
180 whitelists/blacklists the 256 hosts 192.168.0.x.
181
182 This option may be given multiple times to blacklist/whitelist any
183 number of hosts or networks.
184 [/help]
185 [option http-no-autostart]
186 summary = do not open TCP port for http streaming on startup
187 [help]
188 If this option is given, the http sender does not listen on its TCP
189 port until the "sender" command is executed to open the port.
190 [/help]
191 [option http-max-clients]
192 summary = maximal number of simultaneous http connections
193 arg_info = required_arg
194 arg_type = int32
195 typestr = number
196 default_val = -1
197 [help]
198 The http sender will refuse connections if already that number of
199 clients are currently connected. A non-positive value (the default)
200 allows for an unlimited number of simultaneous connections.
201 [/help]
202 [option dccp]
203 summary = Options for the dccp sender
204 flag ignored
205 [option dccp-port]
206 summary = port for dccp streaming
207 arg_info = required_arg
208 arg_type = uint32
209 typestr = portnumber
210 default_val = 8000
211 [help]
212 See --http-port for details.
213 [/help]
214 [option dccp-default-deny]
215 summary = make the dccp access control list a whitelist
216 [help]
217 See http-default-deny for details.
218 [/help]
219 [option dccp-access]
220 summary = add an entry to the dccp access control list
221 arg_info = required_arg
222 arg_type = string
223 typestr = a.b.c.d/n
224 flag multiple
225 [help]
226 See --http-access for details.
227 [/help]
228 [option dccp-max-clients]
229 summary = maximal number of simultaneous dccp connections
230 arg_info = required_arg
231 arg_type = int32
232 typestr = number
233 default_val = -1
234 [help]
235 See --http-max-clients for details.
236 [/help]
237 [option dccp-max-slice-size]
238 summary = upper bound for the FEC slice size
239 arg_info = required_arg
240 arg_type = uint32
241 typestr = bytes
242 default_val = 0
243 [help]
244 If this value is zero (the default) the dccp sender uses the maximum
245 packet size (MPS) of the connection as the slice size. The MPS is a
246 network parameter and depends on the path maximum transmission unit
247 (path MTU) of an incoming connection, i.e. on the largest packet size
248 that can be transmitted without causing fragmentation.
249
250 This option allows values less than the MPS in order to fine-tune
251 application performance. Values greater than the MPS of an incoming
252 connection can not be set.
253 [/help]
254 [option dccp-data-slices-per-group]
255 summary = the number of non-redundant slices per FEC group
256 arg_info = required_arg
257 arg_type = uint32
258 typestr = count
259 default_val = 3
260 [help]
261 This determines the number of slices in each FEC group which are
262 necessary to decode the group. The given number must be smaller than
263 the argument to the --dccp-slices-per-group option below.
264
265 Note that the duration of a FEC group is proportional to the
266 product dccp-max-slice-size * dccp-data-slices-per-group.
267 [/help]
268 [option dccp-slices-per-group]
269 summary = the total number of slices per FEC group
270 arg_info = required_arg
271 arg_type = uint32
272 typestr = count
273 default_val = 4
274 [help]
275 This value must be larger than the value of the argument to
276 --dccp-data-slices-per-group. The difference of the two values is
277 the number of redundant slices, that is, the number of slices which
278 may be lost without causing interruptions in the audio stream.
279
280 Increase this value if you are on a lossy network.
281 [/help]
282 [option udp]
283 summary = Options for the udp sender
284 flag ignored
285 [option udp-target]
286 summary = add udp target with optional port
287 arg_info = required_arg
288 arg_type = string
289 typestr = host[:port]
290 flag multiple
291 [help]
292 Add the given host/port to the list of targets. The "host" argument
293 can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
294 "port" argument is an optional port number. If the "port" part is
295 absent, the "--udp-default-port" value (see below) is used.
296
297 The following examples are possible targets: "10.10.1.2:8000"
298 (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
299 (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
300 (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
301 "[FF00::beef]:1500" (IPv6 multicast).
302
303 This option can be given multiple times, for multiple targets.
304 [/help]
305 [option udp-default-port]
306 summary = default port for udp targets
307 arg_info = required_arg
308 arg_type = uint32
309 typestr = portnumber
310 default_val = 8000
311 [option udp-no-autostart]
312 summary = do not send the audio stream to UDP targets
313 [help]
314 If this option is given, udp streaming may be activated at a later
315 time by executing the "sender" command.
316 [/help]
317 [option udp-mcast-iface]
318 summary = outgoing udp multicast interface
319 arg_info = required_arg
320 arg_type = string
321 typestr = interface
322 [option udp-header-interval]
323 short_opt = H
324 summary = duration for sending header
325 arg_info = required_arg
326 arg_type = uint32
327 typestr = milliseconds
328 default_val = 2000
329 [help]
330 As the udp sender has no idea about connected clients it sends the
331 audio file header periodically if necessary. This option specifies the
332 duration between subsequent headers are sent. Smaller values decrease
333 the average time clients have to wait before starting playback,
334 larger values decrease network traffic.
335
336 Note that this affects only ogg/* and wma streams. Other audio formats,
337 including mp3, don't need an audio file header.
338 [/help]
339 [option udp-ttl]
340 short_opt = t
341 summary = set time to live value
342 arg_info = required_arg
343 arg_type = int32
344 typestr = num
345 default_val = -1
346 [help]
347 This option applies exclusively to multicast UDPv4/v6 streaming.
348
349 For the sending UDPv4 socket it sets the multicast Time-To-Live value
350 to "num". Traditional TTL scope values are: 0=host, 1=network, 32=same
351 site, 64=same region, 128=same continent, 255=unrestricted. Please
352 note however that this scoping is not a good solution: RFC 2365
353 e.g. presents a better alternative.
354
355 When using UDPv6 multicasting, the option sets the number of multicast
356 hops (as described in RFC 3493); a value of -1 allows the kernel to
357 auto-select the hop value.
358 [/help]