chiark / gitweb /
The web interface now automaticallty figures out its own URL, so this
[disorder] / doc / disorder_config.5.in
index 0b1535f6e74221c10b06adcd69ddf47406735ec6..269abe855c7aad4348030e997145d162328eb6f3 100644 (file)
@@ -1,4 +1,3 @@
-
 .\"
 .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
 .\"
@@ -53,10 +52,70 @@ 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
-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
@@ -72,11 +131,33 @@ override specific bits.
 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
@@ -112,6 +193,24 @@ it re-read it.  If there is anything wrong with it the daemon will
 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
+may be abolished in future.
+.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.
 .SS "Global Configuration"
 .TP
 .B home \fIDIRECTORY\fR
@@ -126,6 +225,10 @@ interface.)
 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
@@ -144,7 +247,7 @@ automatically included, but should include the proper extension.
 .IP
 The default is \fB{/artist}{/album}{/title}{ext}\fR.
 .TP
-.B authorization_algorthm \fIALGORITHM\fR
+.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)
@@ -153,6 +256,8 @@ for more details.
 .B broadcast \fIADDRESS\fR \fIPORT\fR
 Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR.  This implies
 \fBspeaker_backend 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.
@@ -164,7 +269,8 @@ 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.
@@ -177,7 +283,8 @@ Master output level.  The OSS documentation recommends against using this, as
 it affects all output devices.
 .RE
 .IP
-You can also specify channels by number, if you know the right value.
+You can also specify channels by number, if you know the right value.  NB that
+volume setting only works on OSS systems (including ALSA, via emulation).
 .TP
 .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR
 Define a collection of tracks.
@@ -193,6 +300,15 @@ Examples might be \fBiso-8859-1\fR or \fButf-8\fR.
 \fIROOT\fR is the root in the filesystem of the filenames and is
 passed to the plugin module.
 .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.
@@ -214,17 +330,24 @@ 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.
+\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.
+e.g. \fB/dev/mixer\fR (the default).
 .TP
-.B multicast_ttl \fIHOPS\fR
-Set the maximum number of hops to send multicast packets.  This only applies is
+.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
 \fBspeaker_backend\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
+\fBspeaker_backend\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).
@@ -249,7 +372,15 @@ that aren't in the original track name will lead to confusing results.
 .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 nice_rescan \fIPRIORITY\fR
 Set the recan subprocess priority.  The default is 10.
@@ -326,6 +457,10 @@ For the server to be able to calculate track lengths, there should be a
 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
@@ -333,21 +468,7 @@ to 3600, i.e. one hour.
 .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.
-.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.
+tracks will be added until the queue is at least this big.  The default is 10.
 .TP
 .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
 Describes the sample format expected by the \fBspeaker_command\fR (below).  The
@@ -400,8 +521,7 @@ 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.
+Use the OSS (/dev/dsp) API.  Not available on all platforms.
 .TP
 .B command
 Execute a command.  This is the default if
@@ -417,8 +537,9 @@ to receive and play the resulting stream on Linux and OS X.
 .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_command \fICOMMAND
 Causes the speaker subprocess to pipe audio data into shell command
@@ -440,14 +561,27 @@ Scratches are played using the same logic as other tracks.
 .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.
 .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
@@ -468,6 +602,8 @@ 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.
@@ -488,64 +624,39 @@ match then each is executed in order.
 .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
@@ -558,6 +669,14 @@ If unset or \fByes\fR then play is enabled.  Otherwise it is disabled.  Use
 .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.
@@ -697,7 +816,7 @@ If there are no arguments, or all the arguments are \fBtrue\fB, then expands to
 \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.
@@ -731,7 +850,7 @@ Expands to the filename of the current file or directory, inside the template
 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
@@ -972,11 +1091,14 @@ Expands to the canonical URL as defined in \fIpkgconfdir/config\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 @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@