-
.\"
-.\" 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
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
.IP
The default is \fB{/artist}{/album}{/title}{ext}\fR.
.TP
+.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
.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
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
it affects all output devices.
.RE
.IP
-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).
+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
\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 (the default).
+.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_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
+\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
-\fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a
+\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]]
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.
.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.
-.TP
.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
Describes the sample format expected by the \fBspeaker_command\fR (below). The
components of the format specification are as follows:
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.
-.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). 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
\fICOMMAND\fR, rather than writing to a local sound card. The sample format is
.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
.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
.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
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.
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
~mdw / disorder / blobdiff