chiark / gitweb /
Improve server man page a bit
[disorder] / doc / disorder.1.in
1 .\"
2 .\" Copyright (C) 2004-2008 Richard Kettlewell
3 .\"
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
8 .\"
9 .\" This program is distributed in the hope that it will be useful, but
10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12 .\" General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program; if not, write to the Free Software
16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17 .\" USA
18 .\"
19 .TH disorder 1
20 .SH NAME
21 disorder \- DisOrder jukebox client
22 .SH SYNOPSIS
23 .B disorder
24 .RI [ OPTIONS ]
25 .RB [ \-\- ]
26 .RI [ COMMANDS ...]
27 .SH DESCRIPTION
28 .B disorder
29 is used to query the \fBdisorderd\fR(8) daemon from the command line.
30 It may be used to request tracks, scratch tracks, query the current
31 state, etc, and by an administrator to shutdown or reconfigure the
32 daemon.
33 .PP
34 If no commands are specified then \fBdisorder\fR connects to the
35 daemon and then immediately disconnects.
36 This can be used to test whether the daemon is running.
37 Otherwise, it executes the commands specified.
38 .SH OPTIONS
39 .TP
40 .B \-\-config \fIPATH\fR, \fB\-c \fIPATH
41 Set the configuration file.
42 The default is
43 .IR pkgconfdir/config .
44 .TP
45 .B \-\-debug\fR, \fB\-d
46 Enable debugging.
47 .TP
48 .B \-\-help\fR, \fB\-h
49 Display a usage message.
50 .TP
51 .B \-\-version\fR, \fB\-V
52 Display version number.
53 .TP
54 .B \-\-help\-commands\fR, \fB\-H
55 List all known commands.
56 .SH COMMANDS
57 .TP
58 .B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
59 Create a new user.
60 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
61 setting from the server's configuration file applies.
62 .TP
63 .B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
64 Create user \fIUSERNAME\fR with a random password.
65 User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
66 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
67 setting from the server's configuration file applies.
68 .IP
69 \fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
70 user should be able to log in immediately.
71 .IP
72 If writing the \fIpasswd\fR file fails then the user will already have been
73 created in DisOrder's user database.
74 Use \fBdisorder deluser\fR to remove them before trying again.
75 .TP
76 .B deluser \fIUSERNAME\fR
77 Delete a user.
78 .TP
79 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
80 List all the directories in \fIDIRECTORY\fR.
81 .IP
82 An optional regexp may be specified, marked with an initial \fB~\fR.
83 Only directories with a basename matching the regexp will be returned.
84 .TP
85 .B disable
86 Disable playing after the current track finishes.
87 .TP
88 .B edituser \fIUSERNAME PROPERTY VALUE
89 Set some property of a user.
90 .TP
91 .B enable
92 (Re-)enable playing.
93 .TP
94 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
95 List all the files in \fIDIRECTORY\fR.
96 .IP
97 An optional regexp may be specified, marked with an initial \fB~\fR.
98 Only files with a basename matching the regexp will be returned.
99 .TP
100 .B get \fITRACK\fR \fIKEY\fR
101 Display the preference \fIKEY\fR for \fITRACK\fR.
102 .TP
103 .B get\-global \fIKEY\fR
104 Get a global preference.
105 .TP
106 .B get\-volume
107 Display the current volume settings.
108 .TP
109 .B length \fITRACK\fR
110 Display the length of \fITRACK\fR in seconds.
111 .TP
112 .B log
113 Write event log messages to standard output, until the server is terminated.
114 See \fBdisorder_protocol\fR (5) for details of the output syntax.
115 .TP
116 .B move \fITRACK\fR \fIDELTA\fR
117 Move
118 .I TRACK
119 by
120 .I DELTA
121 within the queue.
122 Positive values move towards the head of the queue, negative
123 values towards the tail.
124 .IP
125 Note that if you specify a negative value then the
126 .B \-\-
127 option separate (before all commands) becomes mandatory, as otherwise the
128 negative value is misinterpreted an an option.
129 .TP
130 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
131 Get a track name part.
132 .IP
133 \fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
134 \fBpart\fR is the part of the name desired, typically \fBartist\fR,
135 \fBalbum\fR or \fBtitle\fR.
136 .TP
137 .B pause
138 Pause the current track.
139 (Note that not all players support pausing.)
140 .TP
141 .B play \fITRACKS\fR...
142 Add \fITRACKS\fR to the end of the queue.
143 .TP
144 .B playing
145 Report the currently playing track.
146 .TP
147 .B prefs \fITRACK\fR
148 Display all the preferences for \fITRACK\fR.
149 .TP
150 .B queue
151 List the current queue.
152 The first entry in the list is the next track to play.
153 .TP
154 .B random\-disable
155 Disable random play.
156 .TP
157 .B random\-enable
158 Enable random play.
159 .TP
160 .B recent
161 List recently played tracks.
162 The first entry is the oldest track, the last entry is the most
163 recently played one.
164 .TP
165 .B reconfigure
166 Make the daemon reload its configuration file.
167 .TP
168 .B remove \fITRACK\fR
169 Remove a track from the queue.
170 .TP
171 .B rescan
172 Rescan the filesystem for new tracks.
173 There is an automatic daily rescan but if you've just added some tracks
174 and want them to show up immediately, use this command.
175 .TP
176 .B resolve \fITRACK\fR
177 Resolve aliases for \fITRACK\fR and print out the real track name.
178 .TP
179 .B resume
180 Resume the current track after a pause.
181 .TP
182 .B rtp\-address
183 Report the RTP brodcast address used by the server (if any).
184 .TP
185 .B schedule-del \fIEVENT\fR
186 Delete a scheduled event.
187 .TP
188 .B schedule-list
189 List scheduled events.
190 Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
191 the user, the action and action-specific data.
192 .TP
193 .B schedule-play \fIWHEN PRIORITY TRACK\fI
194 Play \fITRACK\fR at time \fIWHEN\fR.
195 Various time/date formats are supported depending on locale but the following
196 three will always work:
197 .RS
198 .RS
199 .TP
200 .B "YYYY-MM-DD HH:MM:SS"
201 .TP
202 .B "HH:MM:SS"
203 .TP
204 .B "HH:MM"
205 .RE
206 .RE
207 .IP
208 \fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
209 This determines how the event is handled if it becomes due when the server is
210 down.
211 Junk events are just discarded in this case, while normal events will be
212 executed when the server comes back up, even if this is much later.
213 .TP
214 .B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
215 Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
216 .TP
217 .B schedule-unset-global \fIWHEN PRIORITY NAME\fI
218 Unset global preference \fINAME\fR at time \fIWHEN\fR.
219 .TP
220 .B scratch
221 Scratch the currently playing track.
222 .TP
223 .B scratch\-id \fIID\fR
224 Scratch the currently playing track, provided it has the given ID.
225 .TP
226 .B search \fITERMS\fR
227 Search for tracks containing all of the listed terms.
228 The terms are separated by spaces and form a single argument,
229 so must be quoted, for example:
230 .IP
231 .B "disorder search 'bowie china'"
232 .IP
233 You can limit the search to tracks with a particular tag, too, using the
234 \fBtag:\fR modifier.
235 For example:
236 .IP
237 .B "disorder search 'love tag:depressing'"
238 .TP
239 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
240 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
241 .TP
242 .B set\-global \fIKEY\fR \fIVALUE\fR
243 Set a global preference.
244 .TP
245 .B set\-volume \fBLEFT\fR \fBRIGHT\fR
246 Set the volume.
247 .TP
248 .B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
249 Create the "guest" user for use by the web interface.
250 This user will have no password and will only have the "read" and
251 "register" rights, the latter allowing new users to automatically
252 register themselves via the web interface.
253 .IP
254 With the option \fB\-\-no-online\-registration\fR, the "register" right is
255 suppressed and users must be manually created by an administrator.
256 .IP
257 If online registration is desired then \fBmail_sender\fR must be set in the
258 configuration file.
259 See \fBdisorder_config\fR(5).
260 .TP
261 .B shutdown
262 Shut down the daemon.
263 .TP
264 .B stats
265 List server statistics.
266 .TP
267 .B tags
268 List known tags.
269 .TP
270 .B unset \fITRACK\fR \fIKEY\fR
271 Unset the preference \fIKEY\fR for \fITRACK\fR.
272 .TP
273 .B unset\-global \fIKEY\fR
274 Unset the global preference \fIKEY\fR.
275 .TP
276 .B userinfo \fIUSERNAME PROPERTY
277 Get some property of a user.
278 .TP
279 .B users
280 List known users.
281 .TP
282 .B version
283 Report the daemon's version number.
284 .PP
285 For
286 .B move
287 and
288 .BR remove ,
289 tracks may be specified by name or by ID.
290 If you use the name and a track appears twice in the queue it is
291 undefined which is affected.
292 .SH PREFERENCES
293 Currently the following preferences are supported.
294 Some are expected to be set by users, others updated automatically by plugins.
295 .TP
296 .B pick_at_random
297 If this preference is present and set to "0" then the track will not
298 be picked for random play.
299 Otherwise it may be.
300 .TP
301 .B played
302 A decimal integer giving the number times the track was played.
303 This includes tracks that are scratched or were picked at random.
304 .TP
305 .B played_time
306 The last time the track was played, as a \fBtime_t\fR converted to a
307 decimal integer.
308 .TP
309 .B scratched
310 The number of times the track has been scratched.
311 .TP
312 .B requested
313 A decimal integer giving the number of times the track was requested.
314 (Tracks that are removed before being played are not counted.)
315 .TP
316 .B tags
317 Tags that apply to this track, separated by commas.
318 Tags can contain any printing character except comma.
319 Leading and trailing spaces are not significant but internal spaces are.
320 .IP
321 Using the
322 .B required\-tags
323 and
324 .B prohibited\-tags
325 global preferences, it is possible to limit the tracks that will be selected at
326 random.
327 .TP
328 .B trackname_\fICONTEXT\fB_\fIPART\fR
329 These preferences can be used to override the filename parsing rules
330 to find a track name part.
331 For backwards compatibility, \fBtrackname_\fIPART\fR will be used
332 if the full version is not present.
333 .TP
334 .B unscratched
335 The number of times the track has been played to completion without
336 being scratched.
337 .TP
338 .B weight
339 The weight for this track.  Weights are non-negative integers which determine
340 the relative likelihood of a track being picked at random (i.e. if track A has
341 twice the weight of track B then it is twice as likely to be picked at random).
342 A track with weight 0 will not be picked at random, though \fBpick_at_random\fR
343 is a more sensible way to configure this.
344 .IP
345 The default weight, used if no weight is set or the weight value is invalid, is
346 90000.  Note that many other factors than track weight affect whether a track
347 will be played - tracks already in the queue will not be picked at random for
348 instance.
349 .IP
350 The maximum allowed weight is 2147483647.  If you set a larger value it will be
351 clamped to this value.  Negative weights will be completely ignored and the
352 default value used instead.
353 .SH NOTES
354 .B disorder
355 is locale-aware.
356 If you do not set the locale correctly then it may not handle non-ASCII
357 data properly.
358 .PP
359 The client determines which user to attempt to authenticate as by examining the
360 current UID.
361 This can be overridden in a per-user configuration file, see
362 \fBdisorder_config\fR(5).
363 .PP
364 See \fBdisorder_protocol\fR(5) for the rights required to run each command.
365 (For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
366 would not normally have.)
367 .PP
368 This program is not intended to run in a setuid environment.
369 .PP
370 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
371 syntax described in \fBpcrepattern\fR(3).
372 Matching is case-independent.
373 It is strongly recommended that you quote regexps, since they often
374 contain characters treated specially by the shell.
375 For example:
376 .PP
377 .B "disorder dirs /Music ~'^(?!the [^t])t'"
378 .SH TROUBLESHOOTING
379 If you cannot play a track, or it does not appear in the database even after a
380 rescan, check the following things:
381 .TP
382 .B .
383 Are there any error messages in the system log?  The server logs to
384 \fBLOG_DAEMON\fR, which typically ends up in
385 .I /var/log/daemon.log
386 or
387 .IR /var/log/messages ,
388 though this depends on local configuration.
389 .TP
390 .B .
391 Is the track in a known format?  Have a look at
392 .I pkgconfdir/config
393 for the formats recognized by the local installation.
394 The filename matching is case-sensitive.
395 .TP
396 .B .
397 Do permissions on the track allow the server to read it?
398 .TP
399 .B .
400 Do the permissions on the containing directories allow the server to read and
401 execute them?
402 .PP
403 The user the server runs as is determined by the \fBuser\fR directive in the
404 configuration file.
405 The README recommends using \fBjukebox\fR for this purpose but it could
406 be different locally.
407 .SH ENVIRONMENT
408 .TP
409 .B LOGNAME
410 The default username.
411 .TP
412 .B HOME
413 The user's home directory.
414 .TP
415 .B LC_ALL\fR, \fBLANG\fR, etc
416 Current locale.
417 See \fBlocale\fR(7).
418 .SH FILES
419 .TP
420 .I pkgconfdir/config
421 Global configuration file.
422 See \fBdisorder_config\fR(5).
423 .TP
424 .I ~/.disorder/passwd
425 Per-user password file
426 .TP
427 .I pkgstatedir/socket
428 Communication socket for \fBdisorder\fR(1).
429 .SH "SEE ALSO"
430 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
431 \fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8)
432 .PP
433 "\fBpydoc disorder\fR" for the Python API documentation.
434 .\" Local Variables:
435 .\" mode:nroff
436 .\" fill-column:79
437 .\" End: