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