X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/ca83183166cfcc9e6cfa412a2d870746e9dad5ae..5c1ae3bc9c3a3cbed192fed2d68fc9b7bbe5c96f:/doc/disorder.1.in diff --git a/doc/disorder.1.in b/doc/disorder.1.in index a05ca8c..bd22e56 100644 --- a/doc/disorder.1.in +++ b/doc/disorder.1.in @@ -1,5 +1,5 @@ .\" -.\" 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 .\" it under the terms of the GNU General Public License as published by @@ -22,16 +22,9 @@ disorder \- DisOrder jukebox client .SH SYNOPSIS .B disorder .RI [ OPTIONS ] -.RB [ -- ] +.RB [ \-\- ] .RI [ COMMANDS ...] -.br -.B disorder -.B --length -.RI [ OPTIONS ] -.RB [ -- ] -.IR PATH ... .SH DESCRIPTION -Without the \fB--length\fR option, .B disorder is used to query the \fBdisorderd\fR(8) daemon from the command line. It may be used to request tracks, scratch tracks, query the current @@ -39,40 +32,61 @@ state, etc, and by an administrator to shutdown or reconfigure the 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. .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 --length\fR, \fB-L -Calculate the length in seconds of the files specified using the tracklength -plugin. -.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 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. @@ -80,23 +94,23 @@ Disables playing after the current track finishes. .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. .TP -.B get-global \fIKEY\fR +.B get\-global \fIKEY\fR Get a global preference. .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 @@ -104,22 +118,25 @@ Move .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. @@ -131,56 +148,83 @@ Report the currently playing track. Display all the preferences for \fITRACK\fR. .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 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. .TP -.B set-global \fIKEY\fR \fIVALUE\fR +.B set\-global \fIKEY\fR \fIVALUE\fR Set a global preference. .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. @@ -191,9 +235,15 @@ List known tags. .B unset \fITRACK\fR \fIKEY\fR Unset the preference \fIKEY\fR for \fITRACK\fR. .TP -.B unset-global \fIKEY\fR +.B unset\-global \fIKEY\fR Unset the global preference \fIKEY\fR. .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. .PP @@ -201,35 +251,21 @@ For .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. +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 PREFERENCES -Currently the following preferences are supported. Some are expected -to be set by users, others updated automatically by plugins. +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. +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. +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 @@ -243,50 +279,65 @@ 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. +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 +.B required\-tags and -.B prohibited-tags +.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. +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. +.B weight +The weight for this track. Weights are non-negative integers which determine +the relative likelihood of a track being picked at random (i.e. if track A has +twice the weight of track B then it is twice as likely to be picked at random). +A track with weight 0 will not be picked at random, though \fBpick_at_random\fR +is a more sensible way to configure this. .IP -If at least one \fBauthorize\fR command succeeds then the server is -automatically told to re-read its configuration. +The default weight, used if no weight is set or the weight value is invalid, is +90000. Note that many other factors than track weight affect whether a track +will be played - tracks already in the queue will not be picked at random for +instance. +.IP +The maximum allowed weight is 2147483647. If you set a larger value it will be +clamped to this value. Negative weights will be completely ignored and the +default value used instead. .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 @@ -304,8 +355,8 @@ though this depends on local configuration. .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? @@ -315,8 +366,9 @@ Do the permissions on the containing directories allow the server to read and 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 @@ -326,11 +378,13 @@ The default username. 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 @@ -339,7 +393,7 @@ 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) .PP "\fBpydoc disorder\fR" for the Python API documentation. .\" Local Variables: