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-port]
 175                 summary = TCP port for http streaming
 176                 arg_info = required_arg
 177                 arg_type = uint32
 178                 typestr = portnumber
 179                 default_val = 8000
 180                 [help]
 181                         The http sender of para_server listens on this port for incoming
 182                         connections. Clients are expected to send the usual http request
 183                         message such as 'GET / HTTP/'.
 184                 [/help]
 185         [option http-default-deny]
 186                 summary = make the http access control list a whitelist
 187                 [help]
 188                         The default is to use blacklists, i.e. connections to the http sender
 189                         are allowed unless the connecting host matches a pattern given by a
 190                         http-access option. This allows to use access control the other way
 191                         round: Connections are denied from hosts which are not explicitly
 192                         allowed by one or more http-access options.
 193                 [/help]
 194         [option http-access]
 195                 summary = add an entry to the http access control list
 196                 arg_info = required_arg
 197                 arg_type = string
 198                 typestr = a.b.c.d/n
 199                 flag multiple
 200                 [help]
 201                         Add the given host/network to access control list (whitelist if
 202                         http-default-deny was given, blacklist otherwise) before opening
 203                         the tcp port. This option can be given multiple times. Example:
 204
 205                                 --http-access 192.168.0.0/24
 206
 207                         whitelists/blacklists the 256 hosts 192.168.0.x.
 208
 209                         This option may be given multiple times to blacklist/whitelist any
 210                         number of hosts or networks.
 211                 [/help]
 212         [option http-no-autostart]
 213                 summary = do not open TCP port for http streaming on startup
 214                 [help]
 215                         If this option is given, the http sender does not listen on its TCP
 216                         port until the "sender" command is executed to open the port.
 217                 [/help]
 218         [option http-max-clients]
 219                 summary = maximal number of simultaneous http connections
 220                 arg_info = required_arg
 221                 arg_type = int32
 222                 typestr = number
 223                 default_val = -1
 224                 [help]
 225                         The http sender will refuse connections if already that number of
 226                         clients are currently connected. A non-positive value (the default)
 227                         allows for an unlimited number of simultaneous connections.
 228                 [/help]
 229         [option dccp]
 230                 summary = Options for the dccp sender
 231                 flag ignored
 232         [option dccp-port]
 233                 summary = port for dccp streaming
 234                 arg_info = required_arg
 235                 arg_type = uint32
 236                 typestr = portnumber
 237                 default_val = 8000
 238                 [help]
 239                         See --http-port for details.
 240                 [/help]
 241         [option dccp-default-deny]
 242                 summary = make the dccp access control list a whitelist
 243                 [help]
 244                         See http-default-deny for details.
 245                 [/help]
 246         [option dccp-access]
 247                 summary = add an entry to the dccp access control list
 248                 arg_info = required_arg
 249                 arg_type = string
 250                 typestr = a.b.c.d/n
 251                 flag multiple
 252                 [help]
 253                         See --http-access for details.
 254                 [/help]
 255         [option dccp-max-clients]
 256                 summary = maximal number of simultaneous dccp connections
 257                 arg_info = required_arg
 258                 arg_type = int32
 259                 typestr = number
 260                 default_val = -1
 261                 [help]
 262                         See --http-max-clients for details.
 263                 [/help]
 264         [option dccp-max-slice-size]
 265                 summary = upper bound for the FEC slice size
 266                 arg_info = required_arg
 267                 arg_type = uint32
 268                 typestr = bytes
 269                 default_val = 0
 270                 [help]
 271                         If this value is zero (the default) the dccp sender uses the maximum
 272                         packet size (MPS) of the connection as the slice size. The MPS is a
 273                         network parameter and depends on the path maximum transmission unit
 274                         (path MTU) of an incoming connection, i.e. on the largest packet size
 275                         that can be transmitted without causing fragmentation.
 276
 277                         This option allows to use a value less than the MPS in order to
 278                         fine-tune application performance. Values greater than the MPS of an
 279                         incoming connection can not be set.
 280                 [/help]
 281         [option dccp-data-slices-per-group]
 282                 summary = the number of non-redundant slices per FEC group
 283                 arg_info = required_arg
 284                 arg_type = uint32
 285                 typestr = count
 286                 default_val = 3
 287                 [help]
 288                         This determines the number of slices in each FEC group which are
 289                         necessary to decode the group. The given number must be smaller than
 290                         the argument to the --dccp-slices-per-group option below.
 291
 292                         Note that the duration of a FEC group is proportional to the
 293                         product dccp-max-slice-size * dccp-data-slices-per-group.
 294                 [/help]
 295         [option dccp-slices-per-group]
 296                 summary = the total number of slices per FEC group
 297                 arg_info = required_arg
 298                 arg_type = uint32
 299                 typestr = count
 300                 default_val = 4
 301                 [help]
 302                         This value must be larger than the value of the argument to
 303                         --dccp-data-slices-per-group. The difference of the two values is
 304                         the number of redundant slices, that is, the number of slices which
 305                         may be lost without causing interruptions in the audio stream.
 306
 307                         Increase this value if you are on a lossy network.
 308                 [/help]
 309         [option udp]
 310                 summary = Options for the udp sender
 311                 flag ignored
 312         [option udp-target]
 313                 summary = add udp target with optional port
 314                 arg_info = required_arg
 315                 arg_type = string
 316                 typestr = host[:port]
 317                 flag multiple
 318                 [help]
 319                         Add the given host/port to the list of targets. The "host" argument
 320                         can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
 321                         "port" argument is an optional port number. If the "port" part is
 322                         absent, the "--udp-default-port" value (see below) is used.
 323
 324                         The following examples are possible targets: "10.10.1.2:8000"
 325                         (host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
 326                         (IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
 327                         (IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
 328                         "[FF00::beef]:1500" (IPv6 multicast).
 329
 330                         This option can be given multiple times, for multiple targets.
 331                 [/help]
 332         [option udp-default-port]
 333                 summary = default port for udp targets
 334                 arg_info = required_arg
 335                 arg_type = uint32
 336                 typestr = portnumber
 337                 default_val = 8000
 338         [option udp-no-autostart]
 339                 summary = do not send the audio stream to UDP targets
 340                 [help]
 341                         If this option is given, udp streaming may be activated at a later
 342                         time by executing the "sender" command.
 343                 [/help]
 344         [option udp-mcast-iface]
 345                 summary = outgoing udp multicast interface
 346                 arg_info = required_arg
 347                 arg_type = string
 348                 typestr = interface
 349         [option udp-header-interval]
 350                 short_opt = H
 351                 summary = duration for sending header
 352                 arg_info = required_arg
 353                 arg_type = uint32
 354                 typestr = milliseconds
 355                 default_val = 2000
 356                 [help]
 357                         As the udp sender has no idea about connected clients it sends the
 358                         audio file header periodically if necessary. This option specifies the
 359                         duration between subsequent headers are sent. Smaller values decrease
 360                         the average time clients have to wait before starting playback,
 361                         larger values decrease network traffic.
 362
 363                         Note that this affects only ogg/* and wma streams. Other audio formats,
 364                         including mp3, don't need an audio file header.
 365                 [/help]
 366         [option udp-ttl]
 367                 short_opt = t
 368                 summary = set time to live value
 369                 arg_info = required_arg
 370                 arg_type = int32
 371                 typestr = num
 372                 default_val = -1
 373                 [help]
 374                         This option applies exclusively to multicast UDPv4/v6 streaming.
 375
 376                         For the sending UDPv4 socket it sets the multicast Time-To-Live value
 377                         to "num".  Traditional TTL scope values are: 0=host, 1=network, 32=same
 378                         site, 64=same region, 128=same continent, 255=unrestricted. Please
 379                         note however that this scoping is not a good solution: RFC 2365
 380                         e.g. presents a better alternative.
 381
 382                         When using UDPv6 multicasting, the option sets the number of multicast
 383                         hops (as described in RFC 3493); a value of -1 allows the kernel to
 384                         auto-select the hop value.
 385                 [/help]