2a5fabc30e61e3385475407897ce45879e86fe4b
[paraslash.git] / server.ggo
1 #########################
2 section "General options"
3 #########################
4
5 option "loglevel" l
6 #~~~~~~~~~~~~~~~~~~
7 "set loglevel (0-6)"
8 int typestr="level"
9 default="3"
10 optional
11 details="
12 Larger values mean less verbose output. Loglevel 0 (debug) gets
13 really noisy; a value of 1 (info) produces still noisy output,
14 but this won't fill up the disk quicky. Messaged logged with
15 loglevel 2 (notice) indicate normal but significant events
16 while level 3 (warning) logs unexpected events that can be
17 handled. Unhandled error conditions are logged with loglevel
18 4 (error) and crititcal errors are logged using loglevel 5
19 (crit). Finally, loglevel 6 (emerg) is reserved for messages
20 that cause para_server to terminate immediately.
21 "
22
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 option "daemon" d
37 #~~~~~~~~~~~~~~~~
38 "run as background daemon"
39 flag off
40 dependon="logfile"
41 details="
42 Note that para_server refuses to start in daemon mode if no
43 logfile was specified.
44 "
45
46 option "user" u
47 #~~~~~~~~~~~~~~
48 "run as the given user"
49 string typestr="name"
50 optional
51 details="
52 para_server does not need any special privileges. If started
53 as root (EUID == 0) this option must be given at the command
54 line (not in the configuration file) so that para_server
55 can drop the root privileges right after parsing the command
56 line options, but before parsing the configuration file. In
57 this case, real/effective/saved UID are all set to the UID
58 of 'name'. As the configuration file is read afterwards,
59 those options that have a default value depending on the UID
60 (e.g. the directory for the configuration file) are computed
61 by using the uid of 'name'. This option has no effect if
62 para_server is started as a non-root user (i.e. EUID != 0)
63 "
64
65
66 option "group" g
67 #~~~~~~~~~~~~~~~
68 "set group id"
69 string typestr="group"
70 optional
71 details="
72 This option sets the group id according to 'group'. This option
73 is silently ignored if EUID != 0. Otherwise, real/effective
74 GID and the saved set-group ID are all set to the GID given by
75 'group'. Must not be given in the config file.
76 "
77
78 #############################
79 section "Configuration files"
80 #############################
81
82
83 option "logfile" L
84 #~~~~~~~~~~~~~~~~~
85 "where to write log output"
86 string typestr="filename"
87 optional
88 details="
89 If this option is not given, para_server writes the log
90 messages to to stderr
91 "
92
93 option "config_file" c
94 #~~~~~~~~~~~~~~~~~~~~~
95 "(default='~/.paraslash/server.conf'"
96 string typestr="filename"
97 optional
98 details="
99 para_server reads its config file right after parsing
100 the options that were given at the command line. If an
101 option is given both at the command line and in the
102 config file, the value that was specified at the command line
103 takes precedence.
104 "
105
106 option "user_list" -
107 #~~~~~~~~~~~~~~~~~~~
108 "(default='~/.paraslash/server.users')"
109
110 string typestr="filename"
111 optional
112
113
114 ##################################
115 section "virtual streaming system"
116 ##################################
117
118
119 option "autoplay" a
120 #~~~~~~~~~~~~~~~~~~
121 "start playing on startup"
122 flag off
123
124 option "autoplay_delay" -
125 #~~~~~~~~~~~~~~~~~~~~~~~~
126 "time to wait before streaming"
127 int typestr="ms"
128 default="0"
129 optional
130 dependon="autoplay"
131 details="
132 If para_server is started with the autoplay option, this option
133 may be used to set up a delay before para_server streams its
134 first audio file. This is useful for example if para_server
135 and para_audiod are started during system startup. The delay
136 time should be choosen large enough so that para_audiod is
137 already up when para_server starts to stream. Of course, this
138 option depends on the autoplay option.
139 "
140 option "announce_time" A
141 #~~~~~~~~~~~~~~~~~~~~~~~
142 "grace time for clients"
143
144 int typestr="ms"
145 default="300"
146 optional
147 details="
148 Clients such as para_audiod connect to para_server and execute
149 the stat command to find out whether an audio stream is
150 currently available. This sets the delay betweeen announcing
151 the stream via the output of the stat command and sending
152 the first chunk of data.
153 "
154
155 #############################
156 section "audio file selector"
157 #############################
158
159 option "afs_database_dir" D
160 #~~~~~~~~~~~~~~~~~~~~~~~~~~
161 "location of the database"
162 string typestr="path"
163 optional
164 details="
165 Where para_server should look for the osl database of the audio
166 file selector. The default is '~/.paraslash/afs_database'.
167 "
168
169 option "afs_socket" s
170 #~~~~~~~~~~~~~~~~~~~~
171 "Command socket for afs"
172 string typestr="path"
173 default="/var/paraslash/afs_command_socket"
174 optional
175 details="
176 For each server command that is handled by the audio file
177 selector, the child process of para_server connects to the
178 audio file selector via a local socket. This option specifies
179 the location of that socket in the file system.
180 "
181 option "afs_initial_mode" i
182 #~~~~~~~~~~~~~~~~~~~~~~~~~~
183
184 "Mood or playlist to load on startup."
185 string typestr="<specifier>/<name>"
186 optional
187
188 details="
189 The argument of this option must be prefixed with either 'p/'
190 or 'm/' to indicate whether a playlist or a mood should be
191 loaded. Example:
192 --afs_initial_mode p/foo
193 loads the playlist named 'foo'.
194 "
195
196 #####################
197 section "http sender"
198 #####################
199
200
201 option "http_port" -
202 #~~~~~~~~~~~~~~~~~~~
203 "tcp port for http streaming"
204 int typestr="portnumber"
205 default="8000"
206 optional
207 details="
208 The http sender of para_server listens on this port for
209 incoming connections. Clients are expected to send the usual
210 http request message such as 'GET / HTTP/'.
211 "
212
213 option "http_default_deny" -
214 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
215 "make the http ACL a whitelist"
216 flag off
217 details="
218 The default is to use blacklists instead, i.e. connections
219 to the http sender are allowed unless the connecting host
220 matches a pattern given by a http_access option. This allows
221 to use access control the other way round: Connections are
222 denied from hosts which are not explicitly allowed by one or
223 more http_access options.
224 "
225
226 option "http_access" -
227 #~~~~~~~~~~~~~~~~~~~~~
228 "add an entry to the http ACL"
229 string typestr="a.b.c.d/n"
230 optional
231 multiple
232 details="
233 Add given host/network to access control list (whitelist if
234 http_default_deny was given, blacklist otherwise) before
235 opening the tcp port. This option can be given multiple
236 times. Example: '192.168.0.0/24' whitelists/blacklists the
237 256 hosts 192.168.0.x
238 "
239
240 option "http_no_autostart" -
241 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
242 "do not open tcp port on startup"
243 flag off
244 details="
245 If this option is given, the http sender does not listen on
246 its tcp port. It may be instructed to open this port at a
247 later time by using the sender command.
248 "
249
250 option "http_max_clients" -
251 #~~~~~~~~~~~~~~~~~~~~~~~~~~
252 "maximal number of connections"
253 int typestr="number"
254 default="-1"
255 optional
256 details="
257 The http sender will refuse connections if already that number
258 of clients are currently connected. A non-positive value
259 (the default) allows an unlimited number of simultaneous
260 connections.
261 "
262
263 #####################
264 section "dccp sender"
265 #####################
266
267
268 option "dccp_port" -
269 #~~~~~~~~~~~~~~~~~~~
270 "port for dccp streaming"
271 int typestr="portnumber"
272 default="8000"
273 optional
274 details="
275 See http_port for details.
276 "
277
278 option "dccp_default_deny" -
279 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
280 "make the dccp ACL a whitelist"
281 flag off
282 details="
283 See http_default_deny for details.
284 "
285
286 option "dccp_access" -
287 #~~~~~~~~~~~~~~~~~~~~~
288 "add an entry to the dccp ACL"
289 string typestr="a.b.c.d/n"
290 optional
291 multiple
292 details="
293 See http_access for details.
294 "
295
296 option "dccp_max_clients" -
297 #~~~~~~~~~~~~~~~~~~~~~~~~~~
298 "maximal number of connections"
299 int typestr="number"
300 default="-1"
301 optional
302 details="
303 See http_max_clients for details.
304 "
305
306 ####################
307 section "udp sender"
308 ####################
309
310 option "udp_target" -
311 #~~~~~~~~~~~~~~~~~~~~
312 "add udp target"
313 string typestr="a.b.c.d:p"
314 optional
315 multiple
316 details="
317 Add given host/port to the list of targets. This option
318 can be given multiple times. Example: '224.0.1.38:1500'
319 instructs the udp sender to send to udp port 1500 on host
320 224.0.1.38 (unassigned ip in the Local Network Control Block
321 224.0.0/24). This is useful for multicast streaming.
322 "
323
324 option "udp_no_autostart" -
325 #~~~~~~~~~~~~~~~~~~~~~~~~~~
326 "do not start sending"
327 flag off
328 details="
329 If this option is given, udp streaming may be activated at
330 a later time by using the sender command.
331 "
332
333 option "udp_default_port" -
334 #~~~~~~~~~~~~~~~~~~~~~~~~~~
335 "udp port to send to"
336 int typestr="port"
337 default="8000"
338 optional
339
340 option "udp_header_interval" H
341 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
342 "duration for sending header"
343 int typestr="ms"
344 default="2000"
345 optional
346 details="
347 As the udp sender has no idea about connected clients it
348 sends the audio file header periodically if necessary. This
349 option is used to specify the duration of the interval between
350 sending the header. Shorter values decrease the average time
351 clients have to wait before being able to start playback,
352 but this also increases the amount network traffic. Note
353 that this affects only ogg vorbis streams as this is the only
354 audio format that needs an audio file header.
355 "
356
357 option "udp_ttl" t
358 #~~~~~~~~~~~~~~~~~
359 "set time to live value"
360 int typestr="num"
361 default="10"
362 optional
363 details="
364 This option instructs the udp sender to set the time to live to
365 \"num\" for the sending udp socket. Only useful for multicast
366 udp streaming.
367 "