write: Improve help text of --writer.
[paraslash.git] / m4 / gengetopt / server.m4
1 args "--conf-parser --no-handle-version --no-handle-help"
2
3 purpose "Manage and stream audio files"
4
5 include(header.m4)
6 define(CURRENT_PROGRAM,para_server)
7 define(DEFAULT_CONFIG_FILE,~/.paraslash/server.conf)
8
9 <qu>
10 #########################
11 section "General options"
12 #########################
13 </qu>
14
15 include(loglevel.m4)
16 include(log_timing.m4)
17 include(color.m4)
18 include(daemon.m4)
19 include(user.m4)
20 include(group.m4)
21 include(priority.m4)
22
23 <qu>
24 option "port" p
25 #~~~~~~~~~~~~~~
26 "listening port"
27 int typestr="portnumber"
28 default="2990"
29 optional
30 details="
31 para_server listens on this tcp port for incoming connections
32 from clients such as para_client. If the default port is
33 changed, the corresponding option of para_client must be used
34 to connect to para_server.
35 "
36
37 #############################
38 section "Configuration files"
39 #############################
40 </qu>
41
42 include(logfile.m4)
43 include(config_file.m4)
44
45 <qu>
46 option "user-list" -
47 #~~~~~~~~~~~~~~~~~~~
48 "(default='~/.paraslash/server.users')"
49
50 string typestr="filename"
51 optional
52
53
54 ##################################
55 section "virtual streaming system"
56 ##################################
57
58
59 option "autoplay" a
60 #~~~~~~~~~~~~~~~~~~
61 "start playing on startup"
62 flag off
63
64 option "autoplay-delay" -
65 #~~~~~~~~~~~~~~~~~~~~~~~~
66 "time to wait before streaming"
67 int typestr="ms"
68 default="0"
69 optional
70 dependon="autoplay"
71 details="
72 If para_server is started with the autoplay option, this option
73 may be used to set up a delay before para_server streams its
74 first audio file. This is useful for example if para_server
75 and para_audiod are started during system startup. The delay
76 time should be choosen large enough so that para_audiod is
77 already up when para_server starts to stream. Of course, this
78 option depends on the autoplay option.
79 "
80 option "announce-time" A
81 #~~~~~~~~~~~~~~~~~~~~~~~
82 "grace time for clients"
83
84 int typestr="ms"
85 default="300"
86 optional
87 details="
88 Clients such as para_audiod connect to para_server and execute
89 the stat command to find out whether an audio stream is
90 currently available. This sets the delay betweeen announcing
91 the stream via the output of the stat command and sending
92 the first chunk of data.
93 "
94
95 #############################
96 section "audio file selector"
97 #############################
98
99 option "afs-database-dir" D
100 #~~~~~~~~~~~~~~~~~~~~~~~~~~
101 "location of the database"
102 string typestr="path"
103 optional
104 details="
105 Where para_server should look for the osl database of the audio
106 file selector. The default is '~/.paraslash/afs_database-0.4'.
107 "
108
109 option "afs-socket" s
110 #~~~~~~~~~~~~~~~~~~~~
111 "Command socket for afs"
112 string typestr="path"
113 default="/var/paraslash/afs_command_socket-0.4"
114 optional
115 details="
116 For each server command that is handled by the audio file
117 selector, the child process of para_server connects to the
118 audio file selector via a local socket. This option specifies
119 the location of that socket in the file system.
120 "
121 option "afs-initial-mode" i
122 #~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124 "Mood or playlist to load on startup."
125 string typestr="<specifier>/<name>"
126 optional
127
128 details="
129 The argument of this option must be prefixed with either 'p/'
130 or 'm/' to indicate whether a playlist or a mood should be
131 loaded. Example:
132 --afs-initial-mode p/foo
133 loads the playlist named 'foo'.
134 "
135
136 #####################
137 section "http sender"
138 #####################
139
140
141 option "http-port" -
142 #~~~~~~~~~~~~~~~~~~~
143 "tcp port for http streaming"
144 int typestr="portnumber"
145 default="8000"
146 optional
147 details="
148 The http sender of para_server listens on this port for
149 incoming connections. Clients are expected to send the usual
150 http request message such as 'GET / HTTP/'.
151 "
152
153 option "http-default-deny" -
154 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
155 "make the http ACL a whitelist"
156 flag off
157 details="
158 The default is to use blacklists instead, i.e. connections
159 to the http sender are allowed unless the connecting host
160 matches a pattern given by a http-access option. This allows
161 to use access control the other way round: Connections are
162 denied from hosts which are not explicitly allowed by one or
163 more http-access options.
164 "
165
166 option "http-access" -
167 #~~~~~~~~~~~~~~~~~~~~~
168 "add an entry to the http ACL"
169 string typestr="a.b.c.d/n"
170 optional
171 multiple
172 details="
173 Add given host/network to access control list (whitelist if
174 http-default-deny was given, blacklist otherwise) before
175 opening the tcp port. This option can be given multiple
176 times. Example: '192.168.0.0/24' whitelists/blacklists the
177 256 hosts 192.168.0.x
178 "
179
180 option "http-no-autostart" -
181 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
182 "do not open tcp port on startup"
183 flag off
184 details="
185 If this option is given, the http sender does not listen on
186 its tcp port. It may be instructed to open this port at a
187 later time by using the sender command.
188 "
189
190 option "http-max-clients" -
191 #~~~~~~~~~~~~~~~~~~~~~~~~~~
192 "maximal number of connections"
193 int typestr="number"
194 default="-1"
195 optional
196 details="
197 The http sender will refuse connections if already that number
198 of clients are currently connected. A non-positive value
199 (the default) allows an unlimited number of simultaneous
200 connections.
201 "
202
203 #####################
204 section "dccp sender"
205 #####################
206
207
208 option "dccp-port" -
209 #~~~~~~~~~~~~~~~~~~~
210 "port for dccp streaming"
211 int typestr="portnumber"
212 default="8000"
213 optional
214 details="
215 See http-port for details.
216 "
217
218 option "dccp-default-deny" -
219 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
220 "make the dccp ACL a whitelist"
221 flag off
222 details="
223 See http-default-deny for details.
224 "
225
226 option "dccp-access" -
227 #~~~~~~~~~~~~~~~~~~~~~
228 "add an entry to the dccp ACL"
229 string typestr="a.b.c.d/n"
230 optional
231 multiple
232 details="
233 See http-access for details.
234 "
235
236 option "dccp-max-clients" -
237 #~~~~~~~~~~~~~~~~~~~~~~~~~~
238 "maximal number of connections"
239 int typestr="number"
240 default="-1"
241 optional
242 details="
243 See http-max-clients for details.
244 "
245
246 option "dccp-max-slice-size" -
247 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248 "Upper bound for the FEC slice size"
249 int typestr = "size"
250 optional
251 default = "0"
252 details = "
253 If this value is non-positive (the default) the dccp sender
254 uses the maximum packet size (MPS) of the connection as the
255 slice size. The MPS is a network parameter and depends on
256 the path maximum transmission unit (path MTU) of an incoming
257 connection, i.e. on the largest packet size that can be
258 transmitted without causing fragmentation.
259
260 This option allows to use a value less than the MPS in order
261 to fine-tune application performance. Values greater than
262 the MPS of an incoming connection can not be set.
263 "
264
265 option "dccp-data-slices-per-group" -
266 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
267 "The number of non-redundant slices per FEC group"
268 int typestr = "num"
269 optional
270 default = "3"
271 details = "
272 This determines the number of slices in each FEC group that are
273 necessary to decode the group. The given number must be smaller
274 than the value of the dccp-slices-per-group option below.
275
276 Note that the duration of a FEC group is proportional to the
277 product dccp-max-slice-size * dccp-data-slices-per-group.
278 "
279
280 option "dccp-slices-per-group" -
281 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282 "The total number of slices per FEC group"
283 int typestr = "num"
284 optional
285 default = "4"
286 details = "
287 This value must be larger than the value given for above
288 dccp-data-slices-per-group above. The difference being the
289 number of redundant slices per group, i.e. the number of
290 data packets that may be lost without causing interruptions
291 of the resulting audio stream.
292
293 Increase this value if for lossy networks.
294 "
295
296 ####################
297 section "udp sender"
298 ####################
299
300 option "udp-target" -
301 #~~~~~~~~~~~~~~~~~~~~
302 "add udp target with optional port"
303 string typestr="host[:port]"
304 optional
305 multiple
306 details="
307 Add given host/port to the list of targets. The 'host' argument
308 can be either an IPv4/v6 address or hostname (RFC 3986 syntax).
309 The 'port' argument is an optional port number. If the 'port'
310 part is absent, the 'udp-default-port' value is used.
311
312 The following examples are possible targets:
313 '10.10.1.2:8000' (host:port); '10.10.1.2' (with default port);
314 '224.0.1.38:1500' (IPv4 multicast); 'localhost:8001' (hostname
315 with port); '[::1]:8001' (IPv6 localhost); '[badc0de::1]' (IPv6
316 host with default port); '[FF00::beef]:1500' (IPv6 multicast).
317
318 This option can be given multiple times, for multiple targets.
319 "
320
321 option "udp-no-autostart" -
322 #~~~~~~~~~~~~~~~~~~~~~~~~~~
323 "do not start sending"
324 flag off
325 details="
326 If this option is given, udp streaming may be activated at
327 a later time by using the sender command.
328 "
329
330 option "udp-default-port" -
331 #~~~~~~~~~~~~~~~~~~~~~~~~~~
332 "udp port to send to"
333 int typestr="port"
334 default="8000"
335 optional
336
337 option "udp-mcast-iface" -
338 #~~~~~~~~~~~~~~~~~~~~~~~~~~
339 "outgoing udp multicast interface"
340 string
341 optional
342
343 option "udp-header-interval" H
344 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345 "duration for sending header"
346 int typestr = "ms"
347 default = "2000"
348 optional
349 details = "
350 As the udp sender has no idea about connected clients it
351 sends the audio file header periodically if necessary. This
352 option specifies the duration between subsequent headers are
353 sent. Smaller values decrease the average time clients have
354 to wait before starting playback, larger values decrease
355 network traffic.
356
357 Note that this affects only ogg/* and wma streams. Other
358 audio formats, including mp3, don't need an audio file header.
359 "
360
361 option "udp-ttl" t
362 #~~~~~~~~~~~~~~~~~
363 "set time to live value"
364 int typestr="num"
365 default="-1"
366 optional
367 details="
368 This option applies exclusively to multicast UDPv4/v6 streaming.
369
370 For the sending UDPv4 socket it sets the multicast Time-To-Live
371 value to \"num\". Traditional TTL scope values are: 0=host,
372 1=network, 32=same site, 64=same region, 128=same continent,
373 255=unrestricted. Please note however that this scoping is not
374 a good solution: RFC 2365 e.g. presents a better alternative.
375
376 When using UDPv6 multicasting, the option sets the number of
377 multicast hops (as described in RFC 3493); a value of -1
378 allows the kernel to auto-select the hop value.
379 "
380 </qu>