path: root/m4/lls/server.suite.m4

m4_define(PROGRAM, para_server)
m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/server.conf)
[suite server]
version-string = GIT_VERSION()
[supercommand para_server]
	purpose = manage and stream audio files
	[description]
		para_server streams audio files over a local or remote network. It
		is controlled by para_client(1), which connects para_server through
		the paraslash control service.

		On startup the server spawns a second process, the audio file selector,
		which maintains the database of all known audio files. This database
		contains file format, duration and tag information of each known file
		and statistics such as last-played time, and the number of times each
		file was streamed. Lyrics and cover art may be added to the database
		and associated with one or more audio files.

		Besides ordinary playlists the audio file selector supports so-called
		moods. Moods instruct the server to determine the files to be streamed
		and their order in terms of properties stored in the database.
	[/description]
	m4_include(common-option-section.m4)
	m4_include(help.m4)
	m4_include(detailed-help.m4)
	m4_include(version.m4)
	m4_include(config-file.m4)
	m4_include(priority.m4)
	m4_include(daemon.m4)
	m4_include(logfile.m4)
	m4_include(user.m4)
	m4_include(group.m4)
	m4_include(loglevel.m4)
	m4_include(log-timing.m4)
	m4_include(color.m4)
	m4_include(per-command-options-section.m4)
	[option listen-address]
		summary = local listening addresses for the control service
		arg_info = required_arg
		arg_type = string
		typestr = addr
		flag multiple
		[help]
			para_server listens on a TCP socket for incoming connections from
			para_client or para_audiod. This option controls on which addresses
			the server should listen. If the option is not given, the server
			listens on all local addresses (INADDR_ANY for IPv4 addresses,
			IN6ADDR_ANY_INIT for IPv6 addresses).

			The argument specifies an IPv4 or an IPv6 address, either a numerical
			network address (for IPv4, numbers-and-dots notation as supported
			by inet_aton(3); for IPv6, hexadecimal string format as supported
			by inet_pton(3)), or a network hostname, whose network addresses is
			looked up and resolved. The address can optionally include a port
			number. For addresses for which no port number is given, the argument
			of the --port option (see below) is implied.

			This option may be given multiple times. The server will then listen
			on each of the specified addresses.

			Examples: 10.10.1.1, 10.10.1.2:2991, localhost, localhost:2991,
			[::1]:2991, [badc0de::1].
		[/help]
	[option port]
		short_opt = p
		summary = listening port of the control service
		arg_info = required_arg
		arg_type = uint32
		typestr = portnumber
		default_val = 2990
		[help]
			This option applies only to addresses given to --listen-address
			(see above) which do no include a port number. If the default port
			is changed, the corresponding option of para_client must be used to
			connect to para_server.
		[/help]
	[option user-list]
		summary = file which contains user names and credentials
		arg_info = required_arg
		arg_type = string
		typestr = path
		[help]
			This file contains one line per user of the form

				user <username> <key> <perms>

			See the manual for more information.
		[/help]
	[option vss]
		summary = Options for the virtual streaming system
		flag ignored
	[option autoplay]
		summary = start streaming on startup
		short_opt = a
		[help]
			The default is to defer streaming until para_client connects and
			executes the "play" command.
		[/help]
	[option autoplay-delay]
		summary = time to wait before streaming
		arg_info = required_arg
		arg_type = uint32
		typestr = milliseconds
		default_val = 0
		[help]
			This option is ignored if --autoplay is not given. Otherwise, its
			argument defines for how long streaming is delayed at startup.

			This is useful to make sure para_audiod has established its link to para_server
			when para_server starts to stream.
		[/help]
	[option announce-time]
		short_opt = A
		summary = grace time for data connections
		arg_info = required_arg
		arg_type = uint32
		typestr = milliseconds
		default_val = 300
		[help]
			para_server tells para_audiod through the control service connection
			whether an audio stream is currently available. This option defines
			the delay between announcing the stream and sending the first chunk
			of audio data.
		[/help]
	[option afs]
		summary = Options for the audio file selector
		flag ignored
	[option afs-database-dir]
		summary = location of the afs database
		short_opt = D
		arg_info = required_arg
		arg_type = string
		typestr = directory
		[help]
			The directory which contains the database for the audio file selector. The
			default is ~/.paraslash/afs_database-0.7. Unless --init is given, it is a
			fatal error if no database is found.
		[/help]
	[option init]
		summary = initialize the database of the audio file selector
		[help]
			This option needs to be given if the database does not yet exist, for example
			because the server is started for the very first time. The option instructs
			the server to create the database directory given by --afs-database-dir and
			a few empty tables therein. It is an error if this option is given and the
			database directory already exists.
		[/help]
	[option afs-socket]
		summary = socket for afs connections
		short_opt = s
		arg_info = required_arg
		arg_type = string
		typestr = path
		default_val = /var/paraslash/afs_command_socket-0.4
		[help]
			Server commands communicate with the audio file selector, via a
			local socket. This option specifies the location of the socket in
			the file system.
		[/help]
	[option afs-initial-mode]
		summary = mood or playlist to load on startup
		short_opt = i
		arg_info = required_arg
		arg_type = string
		typestr = specifier/name
		[help]
			The argument of this option consists of a prefix, either 'm/' or
			'p/', to indicate whether a mood or a playlist should be loaded,
			followed by the name of the mood or playlist. Example:

				--afs-initial-mode p/foo

			loads the playlist named "foo".

			If this option is not given, the dummy mood is loaded at startup.
		[/help]
	[option http]
		summary = Options for the http sender
		flag ignored
	[option http-listen-address]
		summary = listening addresses of the http sender
		arg_info = required_arg
		arg_type = string
		typestr = addr
		flag multiple
		[help]
			This option controls on which addresses the http sender should listen for
			incoming data connections. See the documentation of --listen-address above
			for the format of the address argument and its default.
		[/help]
	[option http-port]
		summary = TCP port for http streaming
		arg_info = required_arg
		arg_type = uint32
		typestr = portnumber
		default_val = 8000
		[help]
			This option has the same meaning as --port, but applies to http
			data connections and applies to the addresses specified as arguments
			to --http-listen-address.
		[/help]
	[option http-default-deny]
		summary = make the http access control list a whitelist
		[help]
			The default is to use blacklists, i.e. connections to the http sender
			are allowed unless the connecting host matches a pattern given by
			a http-access option. This option allows using access control lists
			the other way round: Connections are denied from hosts which are not
			explicitly allowed by one or more http-access options.
		[/help]
	[option http-access]
		summary = add an entry to the http access control list
		arg_info = required_arg
		arg_type = string
		typestr = a.b.c.d/n
		flag multiple
		[help]
			Add the given host/network to access control list (whitelist if
			http-default-deny was given, blacklist otherwise) before opening
			the tcp port. This option can be given multiple times. Example:

				--http-access 192.168.0.0/24

			whitelists/blacklists the 256 hosts 192.168.0.x.

			This option may be given multiple times to blacklist/whitelist any
			number of hosts or networks.
		[/help]
	[option http-no-autostart]
		summary = do not open TCP port for http streaming on startup
		[help]
			If this option is given, the http sender does not listen on its TCP
			port until the "sender" command is executed to open the port.
		[/help]
	[option http-max-clients]
		summary = maximal number of simultaneous http connections
		arg_info = required_arg
		arg_type = int32
		typestr = number
		default_val = -1
		[help]
			The http sender will refuse connections if already that number of
			clients are currently connected. A non-positive value (the default)
			allows for an unlimited number of simultaneous connections.
		[/help]
	[option udp]
		summary = Options for the udp sender
		flag ignored
	[option udp-target]
		summary = add udp target with optional port
		arg_info = required_arg
		arg_type = string
		typestr = host[:port]
		flag multiple
		[help]
			Add the given host/port to the list of targets. The "host" argument
			can be either an IPv4/v6 address or hostname (RFC 3986 syntax). The
			"port" argument is an optional port number. If the "port" part is
			absent, the "--udp-default-port" value (see below) is used.

			The following examples are possible targets: "10.10.1.2:8000"
			(host:port); "10.10.1.2" (with default port); "224.0.1.38:1500"
			(IPv4 multicast); "localhost:8001" (hostname with port); "[::1]:8001"
			(IPv6 localhost); "[badc0de::1]" (IPv6 host with default port);
			"[FF00::beef]:1500" (IPv6 multicast).

			This option can be given multiple times, for multiple targets.
		[/help]
	[option udp-default-port]
		summary = default port for udp targets
		arg_info = required_arg
		arg_type = uint32
		typestr = portnumber
		default_val = 8000
	[option udp-no-autostart]
		summary = do not send the audio stream to UDP targets
		[help]
			If this option is given, udp streaming may be activated at a later
			time by executing the "sender" command.
		[/help]
	[option udp-mcast-iface]
		summary = outgoing udp multicast interface
		arg_info = required_arg
		arg_type = string
		typestr = interface
	[option udp-header-interval]
		short_opt = H
		summary = duration for sending header
		arg_info = required_arg
		arg_type = uint32
		typestr = milliseconds
		default_val = 2000
		[help]
			As the udp sender has no idea about connected clients it sends the
			audio file header periodically if necessary. This option specifies the
			duration between subsequent headers are sent. Smaller values decrease
			the average time clients have to wait before starting playback,
			larger values decrease network traffic.

			Note that this affects only ogg/* and wma streams. Other audio formats,
			including mp3, don't need an audio file header.
		[/help]
	[option udp-ttl]
		short_opt = t
		summary = set time to live value
		arg_info = required_arg
		arg_type = int32
		typestr = num
		default_val = -1
		[help]
			This option applies exclusively to multicast UDPv4/v6 streaming.

			For the sending UDPv4 socket it sets the multicast Time-To-Live value
			to "num".  Traditional TTL scope values are: 0=host, 1=network, 32=same
			site, 64=same region, 128=same continent, 255=unrestricted. Please
			note however that this scoping is not a good solution: RFC 2365
			e.g. presents a better alternative.

			When using UDPv6 multicasting, the option sets the number of multicast
			hops (as described in RFC 3493); a value of -1 allows the kernel to
			auto-select the hop value.
		[/help]