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