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