.\"
-.\" Copyright (C) 2004-2008 Richard Kettlewell
+.\" Copyright (C) 2004-2011, 2013 Richard Kettlewell
.\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-.\" General Public License for more details.
-.\"
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH disorder_config 5
.SH NAME
.SH DESCRIPTION
The purpose of DisOrder is to organize and play digital audio files, under the
control of multiple users.
-\fIpkgconfdir/config\fR is the primary configuration file but this
-man page currently documents all of its various configuration files.
+\fIpkgconfdir/config\fR is the primary configuration file; the web interface
+uses a number of others (see \fBdisorder.cgi\fR(8)).
.SS Tracks
DisOrder can be configured with multiple collections of tracks, indexing them
by their filename, and picking players on the basis of filename patterns (for
Each track can have a set of preferences associated with it.
These are simple key-value pairs; they can be used for anything you
like, but a number of keys have specific meanings.
-See \fBdisorder\fR(1) for more details about these.
+See \fBdisorder_preferences\fR(5) for more details about these.
.SS "Track Names"
Track names are derived from filenames under the control of regular
expressions, rather than attempting to interpret format-specific embedded name
.SS "Server State"
A collection of global preferences define various bits of server state: whether
random play is enabled, what tags to check for when picking at random, etc.
+See \fBdisorder_preferences\fR(5) for more information.
.SS "Users And Access Control"
DisOrder distinguishes between multiple users.
This is for access control and reporting, not to provide different
views of the world: i.e. preferences and so on are global.
.PP
-Each user has an associated set of rights which contorl which commands they may
+Each user has an associated set of rights which control which commands they may
execute.
Normally you would give all users most rights, and expect them to
cooperate (they are after all presumed to be in a shared sound environment).
The web interface is controlled by a collection of template files, one for each
kind of page, and a collection of option files.
These are split up and separate from the main configuration file to
-make it more convenient to override specific bits.
-.PP
-The web interface connects to the DisOrder server like any other user, though
-it is given a special privilege to "become" any other user.
-(Thus, any process with the same UID as the web interface is very
-powerful as far as DisOrder goes.
-This model will be changed in a future version.)
-.PP
-Access control to the web interface is (currently) separate from DisOrder's own
-access control (HTTP authentication is required) but uses the same user
-namespace.
.PP
See \fBdisorder.cgi\fR(8) for more information.
.SS "Searching And Tags"
Quotation mark
.\" "
.TP
-.B \e'
+.B \e\(aq
Apostrophe
.TP
.B \en
Defaults to
.IR pkgstatedir .
The server will create this directory on startup if it does not exist.
+.IP
+This setting cannot be changed during the lifetime of the server.
.TP
.B plugins \fIPATH\fR
Adds a directory to the plugin path.
automatically included, but should include the proper extension.
.IP
The default is \fB{/artist}{/album}{/title}{ext}\fR.
+.IP
+This setting cannot be changed during the lifetime of the server.
.TP
.B api \fINAME\fR
Selects the backend used to play sound and to set the volume.
This is the default if
.B speaker_command
is specified, or if no native is available.
+.IP
+You might want to set
+.B pause_mode
+with this backend.
.TP
-.B network
+.B rtp
Transmit audio over the network.
This is the default if \fBbroadcast\fR is specified.
You can use
.BR disorder-playrtp (1)
to receive and play the resulting stream on Linux and OS X.
+.B network
+is a deprecated synonym for this API.
.RE
.TP
.B authorization_algorithm \fIALGORITHM\fR
.BR disorder_protocol (5)
for more details.
.TP
-.B broadcast \fIADDRESS\fR \fIPORT\fR
+.B broadcast \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR
Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR.
-This implies \fBapi network\fR.
+This implies \fBapi rtp\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIADDRESS\fR.
+Note that IPv6 is not currently well tested.
.IP
See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
.TP
-.B broadcast_from \fIADDRESS\fR \fIPORT\fR
+.B broadcast_from \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR
Sets the (local) source address used by \fBbroadcast\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIADDRESS\fR.
+Note that IPv6 is not currently well tested.
.TP
.B channel \fICHANNEL\fR
The mixer channel that the volume control should use.
.B cookie_key_lifetime \fISECONDS\fR
Lifetime of the signing key used in constructing cookies. The default is one
week.
+.IP
+If this is changed during the lifetime of the server, the current key doesn't
+hvave its lifetime retroactively changed.
.TP
.B cookie_login_lifetime \fISECONDS\fR
Lifetime of a cookie enforced by the server. When the cookie expires the user
will have to log in again even if their browser has remembered the cookie that
long. The default is one day.
+.IP
+If this is changed during the lifetime of the server, cookies that have already
+een generated don't hvave their lifetime retroactively changed.
.TP
.B default_rights \fIRIGHTS\fR
Defines the set of rights given to new users.
.B "Users And Access Control"
above.
.IP
-The default is to allow everything except \fBadmin\fR and \fBregister\fR
-(modified in legacy configurations by the obsolete \fBrestrict\fR directive).
+The default is to allow everything except \fBadmin\fR and \fBregister\fR.
.TP
.B device \fINAME\fR
Sound output device.
.IP
For \fBapi alsa\fR this is the device name to use.
.IP
-For \fBapi coreaudio\fR this is currently ignored.
+For \fBapi coreaudio\fR this can be either the UID or the human-readable
+name of the desired device.
+For a list of names, visit System Preferences -> Sound and look at the Type column.
+For example, you might use "Built-in Output" for the built-in speaker
+or "Built-in Line Output" if you have connected external speakers.
+Remember to quote the name.
.IP
The default is \fBdefault\fR, which is intended to map to whatever the system's
default is.
.TP
-.B gap \fISECONDS\fR
-Specifies the number of seconds to leave between tracks.
-The default is 0.
-.IP
-NB this option currently DOES NOT WORK. If there is genuine demand it might be
-reinstated.
-.TP
.B history \fIINTEGER\fR
Specifies the number of recently played tracks to remember (including
failed tracks and scratches).
+.IP
+If this is changed during the lifetime of the server, it won't actually reduce
+the size of the list until it is next modified.
.TP
-.B listen \fR[\fIHOST\fR] \fISERVICE\fR
+.B listen \fR[\fIFAMILY\fR] \fR[\fIHOST\fR] \fISERVICE\fR
Listen for connections on the address specified by \fIHOST\fR and port
specified by \fISERVICE\fR.
-If \fIHOST\fR is omitted then listens on all local addresses.
+If \fIHOST\fR is omitted, or is \fB*\fR, then listens on all local addresses.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIHOST\fR.
+Note that IPv6 is not currently well tested.
.IP
Normally the server only listens on a UNIX domain socket.
.TP
-.B lock yes\fR|\fBno
-Determines whether the server locks against concurrent operation.
-Default is \fByes\fR.
-There is no good reason to set this to \fBno\fR and the option will
-probably be removed in a future version.
-.TP
.B mixer \fIDEVICE\fR
The mixer device name, if it needs to be specified separately from
\fBdevice\fR.
.IP
For \fBapi coreaudio\fR, volume setting is not currently supported.
.TP
+.B mount_rescan yes\fR|\fBno
+Determines whether mounts and unmounts will cause an automatic rescan.
+The default is \fByes\fR.
+.TP
.B multicast_loop yes\fR|\fBno
Determines whether multicast packets are loop backed to the sending host.
The default is \fByes\fR.
-This only applies if \fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR
+This only applies if \fBapi\fR is set to \fBrtp\fR and \fBbroadcast\fR
is actually a multicast address.
.TP
.B multicast_ttl \fIHOPS\fR
Set the maximum number of hops to send multicast packets.
-This only applies if \fBapi\fR is set to \fBnetwork\fR and
+This only applies if \fBapi\fR is set to \fBrtp\fR and
\fBbroadcast\fR is actually a multicast address.
The default is 1.
.TP
namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 *
namepart ext "(\\.[a-zA-Z0-9]+)$" $1 *
.fi
+.IP
+This setting cannot be changed during the lifetime of the server.
.TP
.B new_bias \fIWEIGHT\fR
The weight for new tracks.
-The default is 900000, i.e. recently added tracks are a hundred times as likely
+The default is 450000, i.e. recently added tracks are a fifty times as likely
to be picked as normal.
+.IP
+New values of this option may be picked up from the configuration file even
+without a reload.
.TP
.B new_bias_age \fISECONDS\fR
The maximum age of tracks that \fBnew_bias\fR applies to, in seconds.
The default is one week.
+.IP
+New values of this option may be picked up from the configuration file even
+without a reload.
.TP
.B new_max \fIMAX\fR
The maximum number of tracks to list when reporting newly noticed tracks.
If you have limited CPU then it might help to set this to a small
negative value.
The default is 0.
+.IP
+Changes to this value during the lifetime of the server are ignored.
.TP
.B nice_speaker \fIPRIORITY\fR
Set the speaker process priority.
If you have limited CPU then it might help to set this to a small
negative value.
The default is 0.
+.IP
+Changes to this value during the lifetime of the server are ignored.
.TP
.B noticed_history
The maximum days that a track can survive in the database of newly added
tracks.
The default is 31.
.TP
+.B pause_mode \fIMODE
+Sets the pause mode for the \fBcommand\fR backend.
+The possible values are:
+.RS
+.TP
+.B silence
+Send silent (0-value) samples when paused.
+This is the default.
+.TP
+.B suspend
+Stop writing when paused.
+.RE
+.TP
.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR...
Specifies the player for files matching the glob \fIPATTERN\fR.
\fIMODULE\fR specifies which plugin module to use.
The following options are supported:
.RS
.TP
-.B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]
-Waits (for up to a couple of seconds) for the default, or specified, libao
-device to become openable.
-.TP
.B \-\-
Defines the end of the list of options.
Needed if the first argument to the plugin starts with a "\-".
DisOrder raw player protocol.
.BR disorder-decode (8)
can decode several common audio file formats to this format.
-If your favourite format is not supported, but you have a player
-which uses libao, there is also a libao driver which supports this format;
-see below for more information about this.
.TP
.B shell \fR[\fISHELL\fR] \fICOMMAND\fR
The command is executed using the shell.
If
.B player
is used without arguments, the list of players is cleared.
-.TP
-.B prefsync \fISECONDS\fR
-The interval at which the preferences log file will be synchronised.
-Defaults to 3600, i.e. one hour.
+.IP
+Although players can be changed during the lifetime of the server, note that
+background decoders will not be stopped and restarted using changed
+configuration once they have been started.
.TP
.B queue_pad \fICOUNT\fR
The target size of the queue.
If random play is enabled then randomly picked tracks will be added until
the queue is at least this big.
The default is 10.
+.IP
+If this is reduced during the lifetime of the server, the queue won't be
+reduced in size to fit; it just won't start growing again until it is under the
+new value.
+However, if it is increased, new tracks will start being added immediately.
.TP
.B reminder_interval \fISECONDS\fR
The minimum number of seconds that must elapse between password reminders.
before it can be picked at random. The default is 8 hours. If this is set to
0 then there is no limit, though current \fBdisorder-choose\fR will not pick
anything currently listed in the recently-played list.
+.IP
+New values of this option may be picked up from the configuration file even
+without a reload.
+.TP
+.B rtp_always_request yes\fR|\fBno
+If
+.B yes
+then
+.BR disorder-playrtp (1)
+will always request a dedicated RTP stream,
+rather than contacting the server to discover
+a broadcast or multicast address.
+(This behaviour can be overridden by
+setting a suitable address on the command-line.)
+The default is
+.BR no .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_maxbuffer \fIFRAMES\fR
+Set
+.BR disorder-playrtp (1)'s
+buffer size to the given number of
+.IR FRAMES .
+If this is zero, then
+.B disorder-playrtp
+will select a default buffer size.
+(This setting can be overridden by passing
+a suitable command-line option.)
+The default value is
+.BR 0 .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_max_payload \fBYTES\fR
+Don't send RTP packets with a UDP payload larger than
+.I BYTES
+(including the 12-byte RTP header). If you know that you will be transmitting
+RTP over networks with an unusually low MTU size, then it is probably useful to
+set this option.
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_minbuffer \fIFRAMES\fR
+Set
+.BR disorder-playrtp (1)'s
+buffer low-water-mark to the given number of
+.IR FRAMES .
+If this is zero, then
+.B disorder-playrtp
+will select a default low-water-mark.
+(This setting can be overridden by passing
+a suitable command-line option.)
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+The default value is
+.BR 0 .
+.IP
+This option is experimental, and may change or be removed in a future release.
+.TP
+.B rtp_mode \fIMODE\fR
+The network transmission mode for the \fBrtp\fR backend.
+Possible values are:
+.RS
+.TP
+.B unicast
+Unicast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B broadcast
+Broadcast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B multicast
+Multicast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B request
+Unicast transmission to addresses requested by clients.
+.TP
+.B auto
+Choose one of the above based on the destination address.
+This is the default, for backwards compatibility reasons.
+.RE
+.TP
+.B rtp_rcvbuf \fISIZE\fR
+Set
+.BR disorder-playrtp (1)'s
+socket receive buffer to at least
+.IB SIZE .
+(This setting can be overridden by passing
+a suitable command-line option.)
+The default value is
+.BR 0 .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_request_address \fR[\fIFAMILY\fR] \fR[\fIHOST\fR] \fISERVICE\fR
+If
+.BR disorder-playrtp (1)
+is to request a unicast RTP stream,
+then it should establish its receiving socket
+to listen on the given address.
+The
+.I FAMILY
+and
+.I HOST
+may be omitted, in which case
+.B disorder-playrtp
+uses heuristics to determine suitable values.
+The
+.I PORT
+may be omitted, in which case
+.B disorder-playrtp
+uses a kernel-allocated port.
+(This setting can be overridden by passing
+a suitable address on the command line.)
+The default is
+.RB ` "\- 0" ',
+which uses a heuristically-chosen address and a kernel-allocated port.
+.IP
+This option is experimental,
+and may change or be removed in a future release.
.TP
.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
Describes the sample format expected by the \fBspeaker_command\fR (below).
.BR 16/44100/2 .
.PP
With the
-.B network
+.B rtp
backend the sample format is forced to
.B 16b/44100/2
and with the
the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1).
See the documentation for your installed copy of \fBsox\fR to determine
which you need.
-The default is 0.
+The default is set according to the version of sox found when DisOrder was
+built.
+If you run on a system with a different version of sox, you will need to
+set this option.
.TP
.B speaker_backend \fINAME
This is an alias for \fBapi\fR; see above.
.IP
There is a default set of stopwords built in, but this option can be used to
augment or replace that list.
+.IP
+This setting cannot be changed during the lifetime of the server.
.TP
.B tracklength \fIPATTERN\fR \fIMODULE\fR
Specifies the module used to calculate the length of files matching
.IP
If \fBtracklength\fR is used without arguments then the list of modules is
cleared.
+.IP
+Track lengths are cached in the database, and changing this setting won't cause
+them to be regenerated.
.TP
.B user \fIUSERNAME\fR
Specifies the user to run as.
Only makes sense if invoked as root (or the target user).
+.IP
+This setting cannot be changed during the lifetime of the server
+(and if it is changed with a restart, you will need to adjust file permissions
+on the server's database).
.SS "Client Configuration"
+These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
+or
+\fIpkgconfdir/config.\fRUSERNAME.
.TP
-.B connect \fIHOST SERVICE\fR
+.B connect \fR[\fIFAMILY\fR] \fIHOST SERVICE\fR
Connect to the address specified by \fIHOST\fR and port specified by
\fISERVICE\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIHOST\fR.
+Note that IPv6 is not currently well tested.
+.TP
+.B password \fIPASSWORD\fR
+Specify password.
+.TP
+.B username \fIUSERNAME\fR
+Specify username.
+The default is inferred from the current UID.
.SS "Web Interface Configuration"
+.\" TODO this section is misnamed really...
.TP
.B mail_sender \fIADDRESS\fR
The email address that appears in the From: field of any mail messages sent by
.TP
.B refresh \fISECONDS\fR
Specifies the maximum refresh period in seconds.
+The refresh period is the time after which the web interface's queue and manage
+pages will automatically reload themselves.
Default 15.
.TP
+.B refresh_min \fISECONDS\fR
+Specifies the minimum refresh period in seconds.
+Default 1.
+.TP
+.B sendmail \fIPATH\fR
+The path to the Sendmail executable.
+This must support the \fB-bs\fR option (Postfix, Exim and Sendmail should all
+work).
+The default is the sendmail executable found at compile time.
+.TP
.B short_display \fICHARACTERS\fR
Defines the maximum number of characters to include in a \fBshort\fR name
part.
.B smtp_server \fIHOSTNAME\fR
The hostname (or address) of the SMTP server to use for sending mail.
The default is 127.0.0.1.
-.TP
-.B templates \fIPATH\fR ...
-Specifies the directory containing templates used by the web
-interface.
-If a template appears in more than one template directory
-then the one in the earliest directory specified is chosen.
-.IP
-See below for further details.
-.IP
-If \fBtemplates\fR is used without arguments then the template path is cleared.
+If \fBsendmail\fR is set then that is used instead.
.TP
.B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
Determines how names are sorted and displayed in track choice displays.
.IP
This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
\fB/cgi-bin/jukebox\fR.
-.SS "Authentication Configuration"
-These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
-or
-\fIpkgconfdir/config.\fRUSERNAME.
-.TP
-.B password \fIPASSWORD\fR
-Specify password.
-.TP
-.B username \fIUSERNAME\fR
-Specify username.
-The default is taken from the environment variable \fBLOGNAME\fR.
-.SH "GLOBAL PREFERENCES"
-These are the values set with \fBset\-global\fR.
-.TP
-.B required\-tags
-If this is set an nonempty then randomly played tracks will always have at
-least one of the listed tags.
-.TP
-.B prohibited\-tags
-If this is set an nonempty then randomly played tracks will never have any of
-the listed tags.
-.TP
-.B playing
-If unset or \fByes\fR then play is enabled.
-Otherwise it is disabled.
-Use \fBdisable\fR rather than setting it directly.
-.TP
-.B random\-play
-If unset or \fByes\fR then random play is enabled.
-Otherwise it is disabled.
-Use \fBdisable\fR rather than setting it directly.
-.PP
-Global preferences starting '_' are read-only (in the sense that you cannot
-modify them; the server may modify them as part of its normal operation).
-They are:
-.TP
-.B _dbversion
-The database version string.
-This is used by DisOrder to detect when it must
-modify the database after an upgrade.
-.SH "LIBAO DRIVER"
-.SS "Raw Protocol Players"
-Raw protocol players are expected to use the \fBdisorder\fR libao driver.
-Programs that use libao generally have command line options to select the
-driver and pass options to it.
-.SS "Driver Options"
-The known driver options are:
-.TP
-.B fd
-The file descriptor to write to.
-If this is not specified then the driver looks like the environment
-variable \fBDISORDER_RAW_FD\fR.
-If that is not set then the default is 1 (i.e. standard output).
-.TP
-.B fragile
-If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a
-write to the output file descriptor fails.
-This is a workaround for buggy players such as \fBogg123\fR that ignore
-write errors.
.SH "REGEXP SUBSTITUTION RULES"
Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3).
The only option used is \fBPCRE_UTF8\fR.
.SH "SEE ALSO"
\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),
\fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5),
-\fBdisorder.cgi\fR(8)
+\fBdisorder.cgi\fR(8), \fBdisorder_preferences\fR(5)
.\" Local Variables:
.\" mode:nroff
.\" fill-column:79
~mdw / disorder / blobdiff