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