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