X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/299a14ee0d61b7994dc4ce5246b55b4d75fdcb2e..8f9616f198b617214724183e32d598339c3bbbc4:/doc/disorder_config.5.in?ds=sidebyside diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index badedeb..a2e6383 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -1,6 +1,5 @@ - .\" -.\" 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 @@ -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 @@ -148,7 +247,35 @@ 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 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) @@ -156,19 +283,22 @@ for more details. .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. @@ -182,28 +312,62 @@ it affects all output devices. .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 @@ -218,17 +382,32 @@ 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. +.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). @@ -253,7 +432,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. @@ -341,21 +528,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 @@ -394,39 +567,14 @@ scratched. The default is \fBSIGKILL\fR. 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 @@ -458,6 +606,9 @@ 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 @@ -465,6 +616,10 @@ 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. +.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 @@ -472,6 +627,10 @@ Connect to the address specified by \fIHOST\fR and port specified by \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 @@ -479,6 +638,10 @@ Specifies the maximum refresh period in seconds. Default 15. 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 @@ -507,71 +670,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. -.IP -If -.B allow -is used without arguments, the list of allowed users is cleared. +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. -.IP -If \fBtrust\fR is used without arguments then the list of trusted users is -cleared. -.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 @@ -663,9 +794,10 @@ Additionally, other standard files are included by these: Included at the end of the main content \fB