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