m4/lls/server.suite.m4

   1 m4_define(PROGRAM, para_server)
   2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
   3 [suite server]
   4 version-string = GIT_VERSION()
   5 [supercommand para_server]
   6         purpose = manage and stream audio files
   7         [description]
   8                 para_server streams audio files over a local or remote network. It
   9                 is controlled by para_client(1), which connects para_server through
  10                 the paraslash control service.
  11
  12                 On startup the server spawns a second process, the audio file selector,
  13                 which maintains the database of all known audio files. This database
  14                 contains file format, duration and tag information of each known file
  15                 and statistics such as last-played time, and the number of times each
  16                 file was streamed. Lyrics and cover art may be added to the database
  17                 and associated with one or more audio files.
  18
  19                 Besides ordinary playlists the audio file selector supports so-called
  20                 moods. Moods instruct the server to determine the files to be streamed
  21                 and their order in terms of properties stored in the database.
  22         [/description]
  23         m4_include(common-option-section.m4)
  24         m4_include(help.m4)
  25         m4_include(detailed-help.m4)
  26         m4_include(version.m4)
  27         m4_include(config-file.m4)
  28         m4_include(priority.m4)
  29         m4_include(daemon.m4)
  30         m4_include(logfile.m4)
  31         m4_include(user.m4)
  32         m4_include(group.m4)
  33         m4_include(loglevel.m4)
  34         m4_include(log-timing.m4)
  35         m4_include(color.m4)
  36         m4_include(per-command-options-section.m4)
  37         [option listen-address]
  38                 summary = local listening addresses for the control service
  39                 arg_info = required_arg
  40                 arg_type = string
  41                 typestr = addr
  42                 flag multiple
  43                 [help]
  44                         para_server listens on a TCP socket for incoming connections from
  45                         para_client or para_audiod. This option controls on which addresses
  46                         the server should listen. If the option is not given, the server
  47                         listens on all local addresses (INADDR_ANY for IPv4 addresses,
  48                         IN6ADDR_ANY_INIT for IPv6 addresses).
  49
  50                         The argument specifies an IPv4 or an IPv6 address, either a numerical
  51                         network address (for IPv4, numbers-and-dots notation as supported
  52                         by inet_aton(3); for IPv6, hexadecimal string format as supported
  53                         by inet_pton(3)), or a network hostname, whose network addresses is
  54                         looked up and resolved. The address can optionally include a port
  55                         number. For addresses for which no port number is given, the argument
  56                         of the --port option (see below) is implied.
  57
  58                         This option may be given multiple times. The server will then listen
  59                         on each of the specified addresses.
  60
  61                         Examples: 10.10.1.1, 10.10.1.2:2991, localhost, localhost:2991,
  62                         [::1]:2991, [badc0de::1].
  63                 [/help]
  64         [option port]
  65                 short_opt = p
  66                 summary = listening port of the control service
  67                 arg_info = required_arg
  68                 arg_type = uint32
  69                 typestr = portnumber
  70                 default_val = 2990
  71                 [help]
  72                         This option applies only to addresses given to --listen-address
  73                         (see above) which do no include a port number. If the default port
  74                         is changed, the corresponding option of para_client must be used to
  75                         connect to para_server.
  76                 [/help]
  77         [option user-list]
  78                 summary = file which contains user names and credentials
  79                 arg_info = required_arg
  80                 arg_type = string
  81                 typestr = path
  82                 [help]
  83                         This file contains one line per user of the form
  84
  85                                 user <username> <key> <perms>
  86
  87                         See the manual for more information.
  88                 [/help]
  89         [option vss]
  90                 summary = Options for the virtual streaming system
  91                 flag ignored
  92         [option autoplay]
  93                 summary = start streaming on startup
  94                 short_opt = a
  95                 [help]
  96                         The default is to defer streaming until para_client connects and
  97                         executes the "play" command.
  98                 [/help]
  99         [option autoplay-delay]
 100                 summary = time to wait before streaming
 101                 arg_info = required_arg
 102                 arg_type = uint32
 103                 typestr = milliseconds
 104                 default_val = 0
 105                 [help]
 106                         This option is ignored if --autplay is not given. Otherwise, its
 107                         argument defines for how long streaming is delayed at startup.
 108
 109                         This is useful in init scripts to set the delay large enough to make
 110                         sure para_audiod is up when para_server starts to stream.
 111                 [/help]
 112         [option announce-time]
 113                 short_opt = A
 114                 summary = grace time for data connections
 115                 arg_info = required_arg
 116                 arg_type = uint32
 117                 typestr = milliseconds
 118                 default_val = 300
 119                 [help]
 120                         para_server tells para_audiod through the control service connection
 121                         whether an audio stream is currently available. This option defines
 122                         the delay between announcing the stream and sending the first chunk
 123                         of audio data.
 124                 [/help]
 125         [option afs]
 126                 summary = Options for the audio file selector
 127                 flag ignored
 128         [option afs-database-dir]
 129                 summary = location of the afs database
 130                 short_opt = D
 131                 arg_info = required_arg
 132                 arg_type = string
 133                 typestr = directory
 134                 [help]
 135                         The directory which contains the database for the audio file
 136                         selector. The default is ~/.paraslash/afs_database-0.4.
 137
 138                         If no database was found, the "init" command must be executed to
 139                         initialize the database. Once initialized, audio files may added with
 140                         the "add" command.
 141                 [/help]
 142         [option afs-socket]
 143                 summary = socket for afs connections
 144                 short_opt = s
 145                 arg_info = required_arg
 146                 arg_type = string
 147                 typestr = path
 148                 default_val = /var/paraslash/afs_command_socket-0.4
 149                 [help]
 150                         Server commands communicate with the audio file selector, via a
 151                         local socket. This option specifies the location of the socket in
 152                         the file system.
 153                 [/help]
 154         [option afs-initial-mode]
 155                 summary = mood or playlist to load on startup
 156                 short_opt = i
 157                 arg_info = required_arg
 158                 arg_type = string
 159                 typestr = specifier/name
 160                 [help]
 161                         The argument of this option consists of a prefix, either 'm/' or
 162                         'p/', to indicate whether a mood or a playlist should be loaded,
 163                         followed by the name of the mood or playlist. Example:
 164
 165                                 --afs-initial-mode p/foo
 166
 167                         loads the playlist named "foo".
 168
 169                         If this option is not given, the dummy mood is loaded at startup.
 170                 [/help]
 171         [option http]
 172                 summary = Options for the http sender
 173                 flag ignored
 174         [option http-listen-address]
 175                 summary = listening addresses of the http sender
 176                 arg_info = required_arg
 177                 arg_type = string
 178                 typestr = addr
 179                 flag multiple
 180                 [help]
 181                         The http sender of para_server listens on this port for incoming data
 182                         connections. This option controls on which addresses the http sender
 183                         should listen. See the documentation of the --listen-address above
 184                         for the format of the address argument and the defaults.
 185                 [/help]
 186         [option http-port]
 187                 summary = TCP port for http streaming
 188                 arg_info = required_arg
 189                 arg_type = uint32
 190                 typestr = portnumber
 191                 default_val = 8000
 192                 [help]
 193                         This option has the same meaning as --port, but applies to http
 194                         data connections and applies to the addresses specified as arguments
 195                         to --http-listen-address.
 196                 [/help]
 197         [option http-default-deny]
 198                 summary = make the http access control list a whitelist
 199                 [help]
 200                         The default is to use blacklists, i.e. connections to the http sender
 201                         are allowed unless the connecting host matches a pattern given by
 202                         a http-access option. This option allows using access control lists
 203                         the other way round: Connections are denied from hosts which are not
 204                         explicitly allowed by one or more http-access options.
 205                 [/help]
 206         [option http-access]
 207                 summary = add an entry to the http access control list
 208                 arg_info = required_arg
 209                 arg_type = string
 210                 typestr = a.b.c.d/n
 211                 flag multiple
 212                 [help]
 213                         Add the given host/network to access control list (whitelist if
 214                         http-default-deny was given, blacklist otherwise) before opening
 215                         the tcp port. This option can be given multiple times. Example:
 216
 217                                 --http-access 192.168.0.0/24
 218
 219                         whitelists/blacklists the 256 hosts 192.168.0.x.
 220
 221                         This option may be given multiple times to blacklist/whitelist any
 222                         number of hosts or networks.
 223                 [/help]
 224         [option http-no-autostart]
 225                 summary = do not open TCP port for http streaming on startup
 226                 [help]
 227                         If this option is given, the http sender does not listen on its TCP
 228                         port until the "sender" command is executed to open the port.
 229                 [/help]
 230         [option http-max-clients]
 231                 summary = maximal number of simultaneous http connections
 232                 arg_info = required_arg
 233                 arg_type = int32
 234                 typestr = number
 235                 default_val = -1
 236                 [help]
 237                         The http sender will refuse connections if already that number of
 238                         clients are currently connected. A non-positive value (the default)
 239                         allows for an unlimited number of simultaneous connections.
 240                 [/help]
 241         [option dccp]
 242                 summary = Options for the dccp sender
 243                 flag ignored
 244         [option dccp-listen-address]
 245                 summary = listening addresses of the dccp sender
 246                 arg_info = required_arg
 247                 arg_type = string
 248                 typestr = addr
 249                 flag multiple
 250                 [help]
 251                         Like --http-listen-address, but for the dccp sender.
 252                 [/help]
 253         [option dccp-port]
 254                 summary = port for dccp streaming
 255                 arg_info = required_arg
 256                 arg_type = uint32
 257                 typestr = portnumber
 258                 default_val = 8000
 259                 [help]
 260                         See --http-port for details.
 261                 [/help]
 262         [option dccp-default-deny]
 263                 summary = make the dccp access control list a whitelist
 264                 [help]
 265                         See http-default-deny for details.
 266                 [/help]
 267         [option dccp-access]
 268                 summary = add an entry to the dccp access control list
 269                 arg_info = required_arg
 270                 arg_type = string
 271                 typestr = a.b.c.d/n
 272                 flag multiple
 273                 [help]
 274                         See --http-access for details.
 275                 [/help]
 276         [option dccp-no-autostart]
 277                 summary = do not open the DCCP port on startup
 278                 [help]
 279                         This is like --http-no-autostart but applies to the dccp sender.
 280                 [/help]
 281         [option dccp-max-clients]
 282                 summary = maximal number of simultaneous dccp connections
 283                 arg_info = required_arg
 284                 arg_type = int32
 285                 typestr = number
 286                 default_val = -1
 287                 [help]
 288                         See --http-max-clients for details.
 289                 [/help]
 290         [option dccp-max-slice-size]
 291                 summary = upper bound for the FEC slice size
 292                 arg_info = required_arg
 293                 arg_type = uint32
 294                 typestr = bytes
 295                 default_val = 0
 296                 [help]
 297                         If this value is zero (the default) the dccp sender uses the maximum
 298                         packet size (MPS) of the connection as the slice size. The MPS is a
 299                         network parameter and depends on the path maximum transmission unit
 300                         (path MTU) of an incoming connection, i.e. on the largest packet size
 301                         that can be transmitted without causing fragmentation.
 302
 303                         This option allows values less than the MPS in order to fine-tune
 304                         application performance. Values greater than the MPS of an incoming
 305                         connection can not be set.
 306                 [/help]
 307         [option dccp-data-slices-per-group]
 308                 summary = the number of non-redundant slices per FEC group
 309                 arg_info = required_arg
 310                 arg_type = uint32
 311                 typestr = count
 312                 default_val = 3
 313                 [help]
 314                         This determines the number of slices in each FEC group which are
 315                         necessary to decode the group. The given number must be smaller than
 316                         the argument to the --dccp-slices-per-group option below.
 317
 318                         Note that the duration of a FEC group is proportional to the
 319                         product dccp-max-slice-size * dccp-data-slices-per-group.
 320                 [/help]
 321         [option dccp-slices-per-group]
 322                 summary = the total number of slices per FEC group
 323                 arg_info = required_arg
 324                 arg_type = uint32
 325                 typestr = count
 326                 default_val = 4
 327                 [help]
 328                         This value must be larger than the value of the argument to
 329                         --dccp-data-slices-per-group. The difference of the two values is
 330                         the number of redundant slices, that is, the number of slices which
 331                         may be lost without causing interruptions in the audio stream.
 332
 333                         Increase this value if you are on a lossy network.
 334                 [/help]
 335         [option udp]
 336                 summary = Options for the udp sender
 337                 flag ignored
 338         [option udp-target]
 339                 summary = add udp target with optional port
 340                 arg_info = required_arg
 341                 arg_type = string
 342                 typestr = host[:port]
 343                 flag multiple
 344                 [help]
 345                         Add the given host/port to the list of targets. The "host" argument
 346                         can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
 347                         "port" argument is an optional port number. If the "port" part is
 348                         absent, the "--udp-default-port" value (see below) is used.
 349
 350                         The following examples are possible targets: "10.10.1.2:8000"
 351                         (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
 352                         (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
 353                         (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
 354                         "[FF00::beef]:1500" (IPv6 multicast).
 355
 356                         This option can be given multiple times, for multiple targets.
 357                 [/help]
 358         [option udp-default-port]
 359                 summary = default port for udp targets
 360                 arg_info = required_arg
 361                 arg_type = uint32
 362                 typestr = portnumber
 363                 default_val = 8000
 364         [option udp-no-autostart]
 365                 summary = do not send the audio stream to UDP targets
 366                 [help]
 367                         If this option is given, udp streaming may be activated at a later
 368                         time by executing the "sender" command.
 369                 [/help]
 370         [option udp-mcast-iface]
 371                 summary = outgoing udp multicast interface
 372                 arg_info = required_arg
 373                 arg_type = string
 374                 typestr = interface
 375         [option udp-header-interval]
 376                 short_opt = H
 377                 summary = duration for sending header
 378                 arg_info = required_arg
 379                 arg_type = uint32
 380                 typestr = milliseconds
 381                 default_val = 2000
 382                 [help]
 383                         As the udp sender has no idea about connected clients it sends the
 384                         audio file header periodically if necessary. This option specifies the
 385                         duration between subsequent headers are sent. Smaller values decrease
 386                         the average time clients have to wait before starting playback,
 387                         larger values decrease network traffic.
 388
 389                         Note that this affects only ogg/* and wma streams. Other audio formats,
 390                         including mp3, don't need an audio file header.
 391                 [/help]
 392         [option udp-ttl]
 393                 short_opt = t
 394                 summary = set time to live value
 395                 arg_info = required_arg
 396                 arg_type = int32
 397                 typestr = num
 398                 default_val = -1
 399                 [help]
 400                         This option applies exclusively to multicast UDPv4/v6 streaming.
 401
 402                         For the sending UDPv4 socket it sets the multicast Time-To-Live value
 403                         to "num".  Traditional TTL scope values are: 0=host, 1=network, 32=same
 404                         site, 64=same region, 128=same continent, 255=unrestricted. Please
 405                         note however that this scoping is not a good solution: RFC 2365
 406                         e.g. presents a better alternative.
 407
 408                         When using UDPv6 multicasting, the option sets the number of multicast
 409                         hops (as described in RFC 3493); a value of -1 allows the kernel to
 410                         auto-select the hop value.
 411                 [/help]