X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/0c6bcae0c6dfbc196885c79c2847d5c05135bcf1..b64c2805b65538c7ad9a8b373e00060bbe453b8c:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index 0b1535f..269abe8 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -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@