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