-
.\"
-.\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
.\" 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
reporting, not to provide different views of the world: i.e. preferences and so
on are global.
.PP
-It's possible to restrict a small number of operations to a specific subset of
-users. However, it is assumed that every user is supposed to be able to do
-most operations - since the users are all sharing the same audio environment
-they are expected to cooperate with each other.
+Each user has an associated set of rights which contorl 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).
+.PP
+The full set of rights are:
+.TP
+.B read
+User can perform read-only operations
+.TP
+.B play
+User can add tracks to the queue
+.TP
+.B "move any"
+User can move any track
+.TP
+.B "move mine"
+User can move their own tracks
+.TP
+.B "move random"
+User can move randomly chosen tracks
+.TP
+.B "remove any"
+User can remove any track
+.TP
+.B "remove mine"
+User can remove their own tracks
+.TP
+.B "remove random"
+User can remove randomly chosen tracks
+.TP
+.B "scratch any"
+User can scratch any track
+.TP
+.B "scratch mine"
+User can scratch their own tracks
+.TP
+.B "scratch random"
+User can scratch randomly chosen tracks
+.TP
+.B volume
+User can change the volume
+.TP
+.B admin
+User can perform admin operations
+.TP
+.B rescan
+User can initiate a rescan
+.TP
+.B register
+User can register new users. Normally only the
+.B guest
+user would have this right.
+.TP
+.B userinfo
+User can edit their own userinfo
+.TP
+.B prefs
+User can modify track preferences
+.TP
+.B "global prefs"
+User can modify global preferences
+.TP
+.B pause
+User can pause/resume
.PP
Access control is entirely used-based. If you configure DisOrder to listen for
TCP/IP connections then it will accept a connection from anywhere provided the
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.)
+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.
+.SS "Searching And Tags"
+Search strings contain a list of search terms separated by spaces. A search
+term can either be a single word or a tag, prefixed with "tag:".
+.PP
+Search words are compared without regard to letter case or accents; thus, all
+of the following will be considered to be equal to one another:
+.PP
+.nf
+ LATIN CAPITAL LETTER E
+ LATIN SMALL LETTER E
+ LATIN CAPITAL LETTER E WITH GRAVE
+ LATIN SMALL LETTER E WITH GRAVE
+ LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT
+ LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT
+.fi
+.PP
+The same rules apply to tags but in addition leading and trailing whitespace is
+disregarded and all whitespace sequences are treated as equal when they appear
+as internal whitespace.
+.PP
+Where several tags are listed, for instance the tags preference for a track,
+the tags are separated by commas. Therefore tags may not contain commas.
.SH "CONFIGURATION FILE"
.SS "General Syntax"
Lines are split into fields separated by whitespace (space, tab, line
record a log message and ignore the new config file. (You should fix
it before next terminating and restarting the daemon, as it cannot
start up without a valid config file.)
+.SS "Configuration Files"
+Configuration files are read in the following order:
+.TP
+.I pkgconfdir/config
+.TP
+.I pkgconfdir/config.private
+Should be readable only by the jukebox group. Not really useful any more and
+will be abolished in future.
+.TP
+.I ~\fRUSER\fI/.disorder/passwd
+Per-user client configuration. Optional but if it exists must be
+readable only by the relevant user. Would normally contain a
+\fBpassword\fR directive.
+.TP
+.I pkgconfdir/config.\fRUSER
+Per-user system-controlled client configuration. Optional but if it
+exists must be readable only by the relevant user. Would normally
+contain a \fBpassword\fR directive.
+.IP
+The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and
+\fBdisorder authorize\fR writes there now.
.SS "Global Configuration"
.TP
.B home \fIDIRECTORY\fR
Plugins are opened the first time they are required and never after,
so after changing a plugin you must restart the server before it is
guaranteed to take effect.
+.IP
+If
+.B plugins
+is used without arguments the plugin path is cleared.
.SS "Server Configuration"
.TP
.B alias \fIPATTERN\fR
.IP
The default is \fB{/artist}{/album}{/title}{ext}\fR.
.TP
-.B authorization_algorthm \fIALGORITHM\fR
+.B api \fINAME\fR
+Selects the backend used to play sound and to set the volume. The following
+options are available:
+.RS
+.TP
+.B alsa
+Use the ALSA API. This is only available on Linux systems, on which it is the
+default.
+.TP
+.B coreaudio
+Use Apple Core Audio. This only available on OS X systems, on which it is the
+default.
+.TP
+.B oss
+Use the OSS (/dev/dsp) API. Not available on all platforms.
+.TP
+.B command
+Execute a command. This is the default if
+.B speaker_command
+is specified, or if no native is available.
+.TP
+.B network
+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.
+.RE
+.TP
+.B authorization_algorithm \fIALGORITHM\fR
Defines the algorithm used to authenticate clients. The valid options
are sha1 (the default), sha256, sha384 and sha512. See
.BR disorder_protocol (5)
.TP
.B broadcast \fIADDRESS\fR \fIPORT\fR
Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. This implies
-\fBspeaker_backend network\fR.
+\fBapi network\fR.
+.IP
+See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
.TP
.B broadcast_from \fIADDRESS\fR \fIPORT\fR
Sets the (local) source address used by \fBbroadcast\fR.
.TP
.B channel \fICHANNEL\fR
-The mixer channel that the volume control should use. Valid names depend on
-your operating system and hardware, but some standard ones that might be useful
-are:
+The mixer channel that the volume control should use.
+.IP
+For \fBapi oss\fR the possible values are:
.RS
.TP 8
.B pcm
-Output level for the audio device. This is probably what you want.
+Output level for the audio device. This is probably what you want and is the
+default.
.TP
.B speaker
Output level for the PC speaker, if that is connected to the sound card.
.RE
.IP
You can also specify channels by number, if you know the right value.
+.IP
+For \fBapi alsa\fR, this is the name of the mixer control to use. The default
+is \fBPCM\fR. Use \fBamixer scontrols\fR or similar to get a full list.
+.IP
+For \fBapi coreaudio\fR, volume setting is not currently supported.
.TP
.B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR
+.TP
+.B collection \fIMODULE\fR \fIROOT\fR
+.TP
+.B collection \fIROOT\fR
Define a collection of tracks.
.IP
\fIMODULE\fR defines which plugin module should be used for this
-collection. Use the supplied \fBfs\fR module for tracks that exists
-as ordinary files in the filesystem.
+collection. Use the supplied \fBfs\fR module for tracks that exist
+as ordinary files in the filesystem. If no \fIMODULE\fR is specified
+then \fBfs\fR is assumed.
+.IP
+\fIENCODING\fR defines the encoding of filenames in this collection. For
+\fBfs\fR this would be the encoding you use for filenames. Examples might be
+\fBiso-8859-1\fR or \fButf-8\fR. If no encoding is specified then the current
+locale's character encoding is used.
.IP
-\fIENCODING\fR defines the encoding of filenames in this collection.
-For \fBfs\fR this would be the encoding you use for filenames.
-Examples might be \fBiso-8859-1\fR or \fButf-8\fR.
+NB that this default depends on the locale the server runs in, which is not
+necessarily the same as that of ordinary users, depending how the system is
+configured. It's best to explicitly specify it to be certain.
.IP
\fIROOT\fR is the root in the filesystem of the filenames and is
-passed to the plugin module.
+passed to the plugin module. It must be an absolute path and should not
+end with a "/".
+.TP
+.B default_rights \fIRIGHTS\fR
+Defines the set of rights given to new users. The argument is a
+comma-separated list of rights. For the possible values see
+.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).
.TP
.B device \fINAME\fR
-ALSA device to play raw-format audio. Default is \fBdefault\fR, i.e. to use
-the whatever the ALSA configured default is.
+Sound output device.
+.IP
+For \fBapi oss\fR this is the path to the device to use. If it is set to
+\fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR will be tried.
+.IP
+For \fBapi alsa\fR this is the device name to use.
+.IP
+For \fBapi coreaudio\fR this is currently ignored.
+.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 2.
+is 0.
.TP
.B history \fIINTEGER\fR
Specifies the number of recently played tracks to remember (including
.TP
.B lock yes\fR|\fBno
Determines whether the server locks against concurrent operation. Default is
-\fByes\fR.
+\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 \fIPATH\fR
-The path to the mixer device, if you want access to the volume control,
-e.g. \fB/dev/mixer\fR.
+.B mixer \fIDEVICE\fR
+The mixer device name, if it needs to be specified separately from
+\fBdevice\fR.
+.IP
+For \fBapi oss\fR this should be the path to the mixer device and the default
+is \fI/dev/mixer\fR.
+.IP
+For \fBapi alsa\fR, this is the index of the mixer control to use. The default
+is 0.
+.IP
+For \fBapi coreaudio\fR, volume setting is not currently supported.
.TP
-.B multicast_ttl \fIHOPS\fR
-Set the maximum number of hops to send multicast packets. This only applies is
-\fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a
+.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 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 \fBbroadcast\fR is actually a
+multicast address. The default is 1.
+.TP
.B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
Determines how to extract trackname part \fIPART\fR from a
track name (with the collection root part removed).
.IP
If you supply no \fBnamepart\fR directives at all then a default set will be
supplied automatically. But if you supply even one then you must supply all of
-them. See the example config file for the defaults.
+them. The defaults are equivalent to:
+.PP
+.nf
+namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
+namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort
+namepart album "/([^/]+)/[^/]+$" $1 *
+namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 *
+namepart ext "(\\.[a-zA-Z0-9]+)$" $1 *
+.fi
+.TP
+.B new_max \fIMAX\fR
+The maximum number of tracks to list when reporting newly noticed tracks. The
+default is 100.
.TP
.B nice_rescan \fIPRIORITY\fR
Set the recan subprocess priority. The default is 10.
command corresponding to each
.B player
command.
+.IP
+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
.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.
+tracks will be added until the queue is at least this big. The default is 10.
.TP
-.B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR]
-Determine which operations are restricted to the submitter of a
-track. By default, no operations are restricted, i.e. anyone can
-scratch or remove anything.
-.IP
-If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user
-that submitted a track can scratch or remove it, respectively.
-.IP
-If \fBrestrict move\fR is set then only trusted users can move tracks around in
-the queue.
-.IP
-If \fBrestrict\fR is used more than once then only the final use has any
-effect.
+.B reminder_interval \fISECONDS\fR
+The minimum number of seconds that must elapse between password reminders. The
+default is 600, i.e. 10 minutes.
.TP
.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
Describes the sample format expected by the \fBspeaker_command\fR (below). The
Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR
or \fBInterrupted\fR or whatever.
.TP
-.B speaker_backend \fINAME\fR
-Selects the backend use by the speaker process. The following options are
-available:
-.RS
-.TP
-.B alsa
-Use the ALSA API. This is only available on Linux systems, on which it is the
-default.
-.TP
-.B coreaudio
-Use Apple Core Audio. This only available on OS X systems, on which it is the
-default.
-.TP
-.B oss
-Use the OSS (/dev/dsp) API. Not available on all platforms. Not well
-maintained at the moment.
-.TP
-.B command
-Execute a command. This is the default if
-.B speaker_command
-is specified, or if no native is available.
-.TP
-.B network
-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.
-.RE
-.TP
.B sox_generation \fB0\fR|\fB1
Determines whether calls to \fBsox\fR(1) should use \fB-b\fR, \fB-x\fR, etc (if
-the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1). The default
-is 0.
+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.
+.TP
+.B speaker_backend \fINAME
+This is an alias for \fBapi\fR; see above.
.TP
.B speaker_command \fICOMMAND
Causes the speaker subprocess to pipe audio data into shell command
.IP
At least for the time being, path names of scratches must be encoded using
UTF-8 (which means that ASCII will do).
+.IP
+If \fBscratch\fR is used without arguments then the list of scratches is
+cleared.
.TP
.B stopword \fIWORD\fR ...
Specifies one or more stopwords that should not take part in searches
over track names.
+.IP
+If \fBstopword\fR is used without arguments then the list of stopwords is
+cleared.
+.IP
+There is a default set of stopwords built in, but this option can be used to
+augment or replace that list.
.TP
.B tracklength \fIPATTERN\fR \fIMODULE\fR
Specifies the module used to calculate the length of files matching
\fIPATTERN\fR. \fIMODULE\fR specifies which plugin module to use.
+.IP
+If \fBtracklength\fR is used without arguments then the list of modules is
+cleared.
+.TP
+.B user \fIUSER\fR
+Specifies the user to run as. Only makes sense if invoked as root (or
+the target user).
.SS "Client Configuration"
.TP
.B connect \fIHOST SERVICE\fR
\fISERVICE\fR.
.SS "Web Interface Configuration"
.TP
+.B mail_sender \fIADDRESS\fR
+The email address that appears in the From: field of any mail messages sent by
+the web interface. This must be set if you have online registration enabled.
+.TP
.B refresh \fISECONDS\fR
Specifies the maximum refresh period in seconds. Default 15.
.TP
Defines the maximum number of characters to include in a \fBshort\fR name
part. Default 30.
.TP
+.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.
.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
If you supply no \fBtransform\fR directives at all then a default set will be
supplied automatically. But if you supply even one then you must supply all of
-them. See the example config file for the defaults.
+them. The defaults are:
+.PP
+.nf
+transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
+transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort
+transform dir "^.*/([^/]+)$" $1 *
+transform dir "^(the) ([^/]*)" "$2 $1" sort i
+transform dir "[[:punct:]]" "" sort g
+.fi
.TP
.B url \fIURL\fR
Specifies the URL of the web interface. This URL will be used in
-generated web pages.
+generated web pages. The default is inferred at runtime, so this option no
+longer needs to be specified.
.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"
-.TP
-.B allow \fIUSERNAME\fR \fIPASSWORD\fR
-Specify a username/password pair.
+These options would normally be used in \fI~\fRUSER\fI/.disorder/passwd\fR or
+\fIpkgconfdir/config.\fRUSER.
.TP
.B password \fIPASSWORD\fR
Specify password.
.TP
-.B trust \fIUSERNAME\fR
-Allow \fIUSERNAME\fR to perform privileged operations such as shutting
-down or reconfiguring the daemon, or becoming another user.
-.TP
-.B user \fIUSER\fR
-Specifies the user to run as. Only makes sense if invoked as root (or
-the target user).
-.TP
.B username \fIUSERNAME\fR
Specify username. The default is taken from the environment variable
\fBLOGNAME\fR.
-.PP
-Configuration files are read in the following order:
-.TP
-.I pkgconfdir/config
-.TP
-.I pkgconfdir/config.private
-Should be readable only by the jukebox group, and contain \fBallow\fR
-commands for authorised users.
-.IP
-If this file does not exist at startup then the server will create it with a
-randomly chosen password for the root user.
-.TP
-.I pkgconfdir/config.\fRUSER
-Per-user system-controlled client configuration. Optional but if it
-exists must be readable only by the relevant user. Would normally
-contain a \fBpassword\fR directive.
-.TP
-.I ~\fRUSER\fI/.disorder/passwd
-Per-user client configuration. Optional but if it exists must be
-readable only by the relevant user. Would normally contain a
-\fBpassword\fR directive.
.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.
-.IP
-Tags can contain any printing character except comma. Leading and trailing
-spaces are not significant but internal spaces are. Tags in a list are
-separated by commas.
.TP
.B prohibited-tags
If this is set an nonempty then randomly played tracks will never have any of
Included at the end of the main content \fB<DIV>\fR element.
.TP
.B topbar.html
-Included at the start of the \fB<BODY>\fR element. (This supplants
-\fBsidebar.html\fR, though the latter is still available; override label
-\fBmenu\fR to choose between them.)
+Included at the start of the \fB<BODY>\fR element.
+.TP
+.B topbarend.html
+Included at the end of the \fB<BODY>\fR element.
.TP
.B stdhead.html
Included in the \fB<HEAD>\fR element.
\fBtrue\fR, otherwise to \fBfalse\fR.
.TP
.B @arg:\fINAME\fB@
-Expands to the value of CGI script argument \fINAME\fR.
+Expands to the value of CGI argument \fINAME\fR.
.TP
.B @basename@
The basename of the current directory component, in \fB@navigate@\fR.
argument to \fBchoose\fR.
.TP
.B @files{\fITEMPLATE\fB}
-Expands \fITEMPLATE\fB once for each file indicated by the \fBdirectory\fR CGI
+Expands \fITEMPLATE\fR once for each file indicated by the \fBdirectory\fR CGI
arg if it is present, or otherwise for the list of files counted by \fBfiles\fR
with names \fB0_file\fR, \fB1_file\fR etc.
.TP
If \fIBOOL\fR expands to \fBtrue\fR then expands to \fITRUEPART\fR, otherwise
to \fIFALSEPART\fR (which may be omitted).
.TP
-.B @include:\fIPATH\fR@
+.B @image:\fINAME\fB@
+Expands to the (possibly relative) URL for image \fINAME\fR.
+.IP
+If there is a label \fBimages.\fINAME\fR then that will be the image base name.
+Otherwise the image base name is \fINAME\fB.png\fR or just \fINAME\fR if it
+alraedy has an extension. Thus labels may be defined to give images role
+names.
+.IP
+If there is a label \fBurl.static\fR then that is the base URL for images. If
+it is not defined then \fB/disorder\fR is used as a default.
+.TP
+.B @include:\fIPATH\fB@
Include the named file as if it were a template file. If \fIPATH\fR
starts with a \fB/\fR then it is used as-is; otherwise, ".html" is
appended and the template path is searched.
.B @length@
Expands to the length of the current track.
.TP
+.B @movable@
+Expands to \fBtrue\fR if the current track is movable, otherwise to
+\fBfalse\fR.
+.TP
.B @navigate{\fIDIRECTORY\fB}{\fITEMPLATE\fB}
Expands \fITEMPLATE\fR for each component of \fIDIRECTORY\fR in turn.
Use \fB@dirname\fR and \fB@basename@\fR to get the components of the path to
Expands \fITEMPLATE\fR repeatedly using the each recently played track in turn
as the current track. The most recently played track comes first.
.TP
+.B @removable@
+Expands to \fBtrue\fR if the current track is removable, otherwise to
+\fBfalse\fR.
+.TP
.B @resolve{\fITRACK\fB}@
Resolve aliases for \fITRACK\fR and expands to the result.
.TP
+.B @right{\fIRIGHT\fB}@
+Exapnds to \fBtrue\fR if the user has right \fIRIGHT\fR, otherwise to
+\fBfalse\fR.
+.TP
+.B @right{\fIRIGHT\fB}{\fITRUEPART\fB}{\fIFALSEPART\fB}@
+Expands to \fITRUEPART\fR if the user right \fIRIGHT\fR, otherwise to
+\fIFALSEPART\fR (which may be omitted).
+.TP
+.B @scratchable@
+Expands to \fBtrue\fR if the currently playing track is scratchable, otherwise
+to \fBfalse\fR.
+.TP
.B @search{\fIPART\fB}\fR[\fB{\fICONTEXT\fB}\fR]\fB{\fITEMPLATE\fB}@
Expands \fITEMPLATE\fR once for each group of search results that have
a common value of track part \fIPART\fR.
.B @urlquote{\fISTRING\fB}@
URL-quote \fISTRING\fR.
.TP
+.B @user@
+The current username. This will be "guest" if nobody is logged in.
+.TP
+.B @userinfo{\fIPROPERTY\fB}@
+Look up a property of the logged-in user.
+.TP
.B @version@
Expands to \fBdisorder.cgi\fR's version string.
.TP
.B @volume:\fISPEAKER\fB@
-The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fB or
+The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fR or
\fBright\fR.
.TP
.B @when@