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-max-clients]
 277                 summary = maximal number of simultaneous dccp connections
 278                 arg_info = required_arg
 279                 arg_type = int32
 280                 typestr = number
 281                 default_val = -1
 282                 [help]
 283                         See --http-max-clients for details.
 284                 [/help]
 285         [option dccp-max-slice-size]
 286                 summary = upper bound for the FEC slice size
 287                 arg_info = required_arg
 288                 arg_type = uint32
 289                 typestr = bytes
 290                 default_val = 0
 291                 [help]
 292                         If this value is zero (the default) the dccp sender uses the maximum
 293                         packet size (MPS) of the connection as the slice size. The MPS is a
 294                         network parameter and depends on the path maximum transmission unit
 295                         (path MTU) of an incoming connection, i.e. on the largest packet size
 296                         that can be transmitted without causing fragmentation.
 297
 298                         This option allows values less than the MPS in order to fine-tune
 299                         application performance. Values greater than the MPS of an incoming
 300                         connection can not be set.
 301                 [/help]
 302         [option dccp-data-slices-per-group]
 303                 summary = the number of non-redundant slices per FEC group
 304                 arg_info = required_arg
 305                 arg_type = uint32
 306                 typestr = count
 307                 default_val = 3
 308                 [help]
 309                         This determines the number of slices in each FEC group which are
 310                         necessary to decode the group. The given number must be smaller than
 311                         the argument to the --dccp-slices-per-group option below.
 312
 313                         Note that the duration of a FEC group is proportional to the
 314                         product dccp-max-slice-size * dccp-data-slices-per-group.
 315                 [/help]
 316         [option dccp-slices-per-group]
 317                 summary = the total number of slices per FEC group
 318                 arg_info = required_arg
 319                 arg_type = uint32
 320                 typestr = count
 321                 default_val = 4
 322                 [help]
 323                         This value must be larger than the value of the argument to
 324                         --dccp-data-slices-per-group. The difference of the two values is
 325                         the number of redundant slices, that is, the number of slices which
 326                         may be lost without causing interruptions in the audio stream.
 327
 328                         Increase this value if you are on a lossy network.
 329                 [/help]
 330         [option udp]
 331                 summary = Options for the udp sender
 332                 flag ignored
 333         [option udp-target]
 334                 summary = add udp target with optional port
 335                 arg_info = required_arg
 336                 arg_type = string
 337                 typestr = host[:port]
 338                 flag multiple
 339                 [help]
 340                         Add the given host/port to the list of targets. The "host" argument
 341                         can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
 342                         "port" argument is an optional port number. If the "port" part is
 343                         absent, the "--udp-default-port" value (see below) is used.
 344
 345                         The following examples are possible targets: "10.10.1.2:8000"
 346                         (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
 347                         (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
 348                         (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
 349                         "[FF00::beef]:1500" (IPv6 multicast).
 350
 351                         This option can be given multiple times, for multiple targets.
 352                 [/help]
 353         [option udp-default-port]
 354                 summary = default port for udp targets
 355                 arg_info = required_arg
 356                 arg_type = uint32
 357                 typestr = portnumber
 358                 default_val = 8000
 359         [option udp-no-autostart]
 360                 summary = do not send the audio stream to UDP targets
 361                 [help]
 362                         If this option is given, udp streaming may be activated at a later
 363                         time by executing the "sender" command.
 364                 [/help]
 365         [option udp-mcast-iface]
 366                 summary = outgoing udp multicast interface
 367                 arg_info = required_arg
 368                 arg_type = string
 369                 typestr = interface
 370         [option udp-header-interval]
 371                 short_opt = H
 372                 summary = duration for sending header
 373                 arg_info = required_arg
 374                 arg_type = uint32
 375                 typestr = milliseconds
 376                 default_val = 2000
 377                 [help]
 378                         As the udp sender has no idea about connected clients it sends the
 379                         audio file header periodically if necessary. This option specifies the
 380                         duration between subsequent headers are sent. Smaller values decrease
 381                         the average time clients have to wait before starting playback,
 382                         larger values decrease network traffic.
 383
 384                         Note that this affects only ogg/* and wma streams. Other audio formats,
 385                         including mp3, don't need an audio file header.
 386                 [/help]
 387         [option udp-ttl]
 388                 short_opt = t
 389                 summary = set time to live value
 390                 arg_info = required_arg
 391                 arg_type = int32
 392                 typestr = num
 393                 default_val = -1
 394                 [help]
 395                         This option applies exclusively to multicast UDPv4/v6 streaming.
 396
 397                         For the sending UDPv4 socket it sets the multicast Time-To-Live value
 398                         to "num".  Traditional TTL scope values are: 0=host, 1=network, 32=same
 399                         site, 64=same region, 128=same continent, 255=unrestricted. Please
 400                         note however that this scoping is not a good solution: RFC 2365
 401                         e.g. presents a better alternative.
 402
 403                         When using UDPv6 multicasting, the option sets the number of multicast
 404                         hops (as described in RFC 3493); a value of -1 allows the kernel to
 405                         auto-select the hop value.
 406                 [/help]