.\"
-.\" Copyright (C) 2004, 2005, 2006 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" 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
-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-.\" General Public License for more details.
-.\"
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH disorder 1
.SH NAME
.SH SYNOPSIS
.B disorder
.RI [ OPTIONS ]
-.RB [ -- ]
+.RB [ \-\- ]
.RI [ COMMANDS ...]
.SH DESCRIPTION
.B disorder
daemon.
.PP
If no commands are specified then \fBdisorder\fR connects to the
-daemon and then immediately disconnects. This can be used to test
-whether the daemon is running. Otherwise, it executes the commands
-specified.
+daemon and then immediately disconnects.
+This can be used to test whether the daemon is running.
+Otherwise, it executes the commands specified.
+.PP
+This man page documents the command-line client.
+See \fBdisorderd\fR (8) for information about the server process
+and \fBdisorder_config\fR (5) for documentation of the configuration file.
.SH OPTIONS
.TP
-.B --config \fIPATH\fR, \fB-c \fIPATH
-Set the configuration file. The default is
+.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
+Set the configuration file.
+The default is
.IR pkgconfdir/config .
.TP
-.B --debug\fR, \fB-d
+.B \-\-debug\fR, \fB\-d
Enable debugging.
.TP
-.B --help\fR, \fB-h
+.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
-.B --version\fR, \fB-V
+.B \-\-version\fR, \fB\-V
Display version number.
.TP
-.B --help-commands\fR, \fB-H
+.B \-\-help\-commands\fR, \fB\-H
List all known commands.
.SH COMMANDS
.TP
+.B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
+Create a new user.
+If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
+setting from the server's configuration file applies.
+.TP
+.B adopt \fIID\fR
+Adopts track \fIID\fR (in the queue).
+The track will show up as submitted by the calling user.
+.TP
+.B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
+Create user \fIUSERNAME\fR with a random password.
+User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
+If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
+setting from the server's configuration file applies.
+.IP
+\fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
+user should be able to log in immediately.
+.IP
+If writing the \fIpasswd\fR file fails then the user will already have been
+created in DisOrder's user database.
+Use \fBdisorder deluser\fR to remove them before trying again.
+.TP
+.B deluser \fIUSERNAME\fR
+Delete a user.
+.TP
.B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
List all the directories in \fIDIRECTORY\fR.
.IP
-An optional regexp may be specified, marked with an initial \fB~\fR. Only
-directories with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only directories with a basename matching the regexp will be returned.
.TP
.B disable
-Disables playing after the current track finishes.
+Disable playing after the current track finishes.
+.TP
+.B edituser \fIUSERNAME PROPERTY VALUE
+Set some property of a user.
.TP
.B enable
(Re-)enable playing.
.B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
List all the files in \fIDIRECTORY\fR.
.IP
-An optional regexp may be specified, marked with an initial \fB~\fR. Only
-files with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only files with a basename matching the regexp will be returned.
.TP
.B get \fITRACK\fR \fIKEY\fR
Display the preference \fIKEY\fR for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B get-global \fIKEY\fR
+.B get\-global \fIKEY\fR
Get a global preference.
+See \fBdisorder_preferences\fR (5).
.TP
-.B get-volume
-Displays the current volume settings.
+.B get\-volume
+Display the current volume settings.
.TP
.B length \fITRACK\fR
-Reports the length of \fITRACK\fR in seconds.
+Display the length of \fITRACK\fR in seconds.
.TP
.B log
-Writes event log messages to standard output, until the server is terminated.
+Write event log messages to standard output, until the server is terminated.
See \fBdisorder_protocol\fR (5) for details of the output syntax.
.TP
.B move \fITRACK\fR \fIDELTA\fR
.I TRACK
by
.I DELTA
-within the queue. Positive values move towards the head of the queue, negative
+within the queue.
+Positive values move towards the head of the queue, negative
values towards the tail.
.IP
Note that if you specify a negative value then the
-.B --
+.B \-\-
option separate (before all commands) becomes mandatory, as otherwise the
negative value is misinterpreted an an option.
.TP
.B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
Get a track name part.
.IP
-\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR. \fBpart\fR is the
-part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR.
+\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
+\fBpart\fR is the part of the name desired, typically \fBartist\fR,
+\fBalbum\fR or \fBtitle\fR.
.TP
.B pause
-Pause the current track. (Note that not all players support pausing.)
+Pause the current track.
+(Note that not all players support pausing.)
.TP
.B play \fITRACKS\fR...
Add \fITRACKS\fR to the end of the queue.
.TP
.B prefs \fITRACK\fR
Display all the preferences for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
.B queue
-List the current queue. The first entry in the list is the next track to play.
+List the current queue.
+The first entry in the list is the next track to play.
.TP
-.B random-disable
+.B random\-disable
Disable random play.
.TP
-.B random-enable
+.B random\-enable
Enable random play.
.TP
.B recent
-List recently played tracks. The first entry is the oldest track, the last
-entry is the most recently played one.
+List recently played tracks.
+The first entry is the oldest track, the last entry is the most
+recently played one.
+.TP
+.B reconfigure
+Make the daemon reload its configuration file.
.TP
.B remove \fITRACK\fR
Remove a track from the queue.
.TP
+.B rescan
+Rescan the filesystem for new tracks.
+There is an automatic daily rescan but if you've just added some tracks
+and want them to show up immediately, use this command.
+.TP
.B resolve \fITRACK\fR
Resolve aliases for \fITRACK\fR and print out the real track name.
.TP
.B resume
Resume the current track after a pause.
.TP
-.B rtp-address
+.B rtp\-address
Report the RTP brodcast address used by the server (if any).
.TP
+.B schedule-del \fIEVENT\fR
+Delete a scheduled event.
+.TP
+.B schedule-list
+List scheduled events.
+Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
+the user, the action and action-specific data.
+.TP
+.B schedule-play \fIWHEN PRIORITY TRACK\fI
+Play \fITRACK\fR at time \fIWHEN\fR.
+Various time/date formats are supported depending on locale but the following
+three will always work:
+.RS
+.RS
+.TP
+.B "YYYY-MM-DD HH:MM:SS"
+.TP
+.B "HH:MM:SS"
+.TP
+.B "HH:MM"
+.RE
+.RE
+.IP
+\fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
+This determines how the event is handled if it becomes due when the server is
+down.
+Junk events are just discarded in this case, while normal events will be
+executed when the server comes back up, even if this is much later.
+.TP
+.B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
+Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
+.TP
+.B schedule-unset-global \fIWHEN PRIORITY NAME\fI
+Unset global preference \fINAME\fR at time \fIWHEN\fR.
+.TP
.B scratch
Scratch the currently playing track.
.TP
-.B scratch-id \fIID\fR
+.B scratch\-id \fIID\fR
Scratch the currently playing track, provided it has the given ID.
.TP
.B search \fITERMS\fR
-Search for tracks containing all of the listed terms. The terms are
-separated by spaces and form a single argument, so must be quoted,
-for example:
+Search for tracks containing all of the listed terms.
+The terms are separated by spaces and form a single argument,
+so must be quoted, for example:
.IP
.B "disorder search 'bowie china'"
.IP
You can limit the search to tracks with a particular tag, too, using the
-\fBtag:\fR modifier. For example:
+\fBtag:\fR modifier.
+For example:
.IP
.B "disorder search 'love tag:depressing'"
.TP
.B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B set-global \fIKEY\fR \fIVALUE\fR
+.B set\-global \fIKEY\fR \fIVALUE\fR
Set a global preference.
+See \fBdisorder_preferences\fR (5).
.TP
-.B set-volume \fBLEFT\fR \fBRIGHT\fR
-Sets the volume.
+.B set\-volume \fBLEFT\fR \fBRIGHT\fR
+Set the volume.
+.TP
+.B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
+Create the "guest" user for use by the web interface.
+This user will have no password and will only have the "read" and
+"register" rights, the latter allowing new users to automatically
+register themselves via the web interface.
+.IP
+With the option \fB\-\-no-online\-registration\fR, the "register" right is
+suppressed and users must be manually created by an administrator.
+.IP
+If online registration is desired then \fBmail_sender\fR must be set in the
+configuration file.
+See \fBdisorder_config\fR(5).
+.TP
+.B shutdown
+Shut down the daemon.
.TP
.B stats
List server statistics.
.TP
.B unset \fITRACK\fR \fIKEY\fR
Unset the preference \fIKEY\fR for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B unset-global \fIKEY\fR
+.B unset\-global \fIKEY\fR
Unset the global preference \fIKEY\fR.
+See \fBdisorder_preferences\fR (5).
+.TP
+.B userinfo \fIUSERNAME PROPERTY
+Get some property of a user.
+.TP
+.B users
+List known users.
.TP
.B version
Report the daemon's version number.
.B move
and
.BR remove ,
-tracks may be specified by name or by ID. If you use the name and a track
-appears twice in the queue it is undefined which is affected.
-.SS "Privileged Commands"
-These commands are only available to privileged users.
-.TP
-.B become \fIUSER\fR
-Become another user.
-.TP
-.B reconfigure
-Make the daemon reload its configuration file.
-.TP
-.B rescan
-Rescan the filesystem for new tracks. There is an automatic daily rescan but
-if you've just added some tracks and want them to show up immediately, use this
-command.
-.TP
-.B shutdown
-Shut down the daemon.
-.SH PREFERENCES
-Currently the following preferences are supported. Some are expected
-to be set by users, others updated automatically by plugins.
-.TP
-.B pick_at_random
-If this preference is present and set to "0" then the track will not
-be picked for random play. Otherwise it may be.
-.TP
-.B played
-A decimal integer giving the number times the track was played. This
-includes tracks that are scratched or were picked at random.
-.TP
-.B played_time
-The last time the track was played, as a \fBtime_t\fR converted to a
-decimal integer.
-.TP
-.B scratched
-The number of times the track has been scratched.
-.TP
-.B requested
-A decimal integer giving the number of times the track was requested.
-(Tracks that are removed before being played are not counted.)
-.TP
-.B tags
-Tags that apply to this track, separated by commas. Tags can contain any
-printing character except comma. Leading and trailing spaces are not
-significant but internal spaces are.
-.IP
-Using the
-.B required-tags
-and
-.B prohibited-tags
-global preferences, it is possible to limit the tracks that will be selected at
-random.
-.TP
-.B trackname_\fICONTEXT\fB_\fIPART\fR
-These preferences can be used to override the filename parsing rules
-to find a track name part. For backwards compatibility,
-\fBtrackname_\fIPART\fR will be used if the full version
-is not present.
-.TP
-.B unscratched
-The number of times the track has been played to completion without
-being scratched.
-.SH "Superuser Commands"
-These commands will (generally) only work for root, who must be a privileged
-user.
-.TP
-.B authorize \fIUSER\fR
-Chooses a password for \fIUSER\fR and adds it to \fIconfig.private\fR. Also
-creates an appropriate \fIconfig.USER\fR, be owned by the user.
-.IP
-If at least one \fBauthorize\fR command succeeds then the server is
-automatically told to re-read its configuration.
+tracks may be specified by name or by ID.
+If you use the name and a track appears twice in the queue it is
+undefined which is affected.
.SH NOTES
.B disorder
-is locale-aware. If you do not set the locale correctly then it may
-not handle non-ASCII data properly.
+is locale-aware.
+If you do not set the locale correctly then it may not handle non-ASCII
+data properly.
+.PP
+The client determines which user to attempt to authenticate as by examining the
+current UID.
+This can be overridden in a per-user configuration file, see
+\fBdisorder_config\fR(5).
.PP
-The client determines which user to attempt to authenticate as by
-examining the current UID.
+See \fBdisorder_protocol\fR(5) for the rights required to run each command.
+(For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
+would not normally have.)
.PP
This program is not intended to run in a setuid environment.
.PP
The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
-syntax described in \fBpcrepattern\fR(3). Matching is case-independent. It is
-strongly recommended that you quote regexps, since they often contain
-characters treated specially by the shell. For example:
+syntax described in \fBpcrepattern\fR(3).
+Matching is case-independent.
+It is strongly recommended that you quote regexps, since they often
+contain characters treated specially by the shell.
+For example:
.PP
.B "disorder dirs /Music ~'^(?!the [^t])t'"
.SH TROUBLESHOOTING
.B .
Is the track in a known format? Have a look at
.I pkgconfdir/config
-for the formats recognized by the local installation. The filename matching is
-case-sensitive.
+for the formats recognized by the local installation.
+The filename matching is case-sensitive.
.TP
.B .
Do permissions on the track allow the server to read it?
execute them?
.PP
The user the server runs as is determined by the \fBuser\fR directive in the
-configuration file. The README recommends using \fBjukebox\fR for this purpose
-but it could be different locally.
+configuration file.
+The README recommends using \fBjukebox\fR for this purpose but it could
+be different locally.
.SH ENVIRONMENT
.TP
-.B LOGNAME
-The default username.
-.TP
.B HOME
The user's home directory.
.TP
.B LC_ALL\fR, \fBLANG\fR, etc
-Current locale. See \fBlocale\fR(7).
+Current locale.
+See \fBlocale\fR(7).
.SH FILES
.TP
.I pkgconfdir/config
-Global configuration file. See \fBdisorder_config\fR(5).
+Global configuration file.
+See \fBdisorder_config\fR(5).
.TP
.I ~/.disorder/passwd
Per-user password file
Communication socket for \fBdisorder\fR(1).
.SH "SEE ALSO"
\fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
-\fBpcrepattern\fR(3), \fBdisobedience\fR(1)
+\fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
+\fBdisorder_preferences\fR(5)
.PP
"\fBpydoc disorder\fR" for the Python API documentation.
.\" Local Variables:
~mdw / disorder / blobdiff