Improve server man page a bit

[disorder] / doc / disorderd.8.in

.\"
.\" Copyright (C) 2004, 2005, 2007, 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
.\" the Free Software Foundation; either version 2 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.
.\"
.\" 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
.\"
.TH disorderd 8
.SH NAME
disorderd \- DisOrder jukebox daemon
.SH SYNOPSIS
.B disorderd
.RI [ OPTIONS ]
.SH DESCRIPTION
.B disorderd
is a daemon which plays audio files and services requests from users
concerning what is to be played.
.SH OPTIONS
.TP
.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
Set the configuration file.
The default is
.IR pkgconfdir/config .
See
.BR disorder_config (5)
for further information.
.TP
.B \-\-pidfile \fIPATH\fR, \fB\-P \fIPATH
Write a pidfile.
.TP
.B \-\-foreground\fR, \fB\-f
Run in the foreground.
(By default,
.B disorderd
detaches from its terminal and runs in the background.)
.TP
.B \-\-syslog\fR, \fB\-s
Log to syslog.
This is the default if DisOrder runs in the background.
.TP
.B \-\-debug\fR, \fB\-d
Enable debugging.
.TP
.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
.B \-\-version\fR, \fB\-V
Display version number.
.SH NOTES
For configuration file documentation, see
.BR disorder_config (5).
.SS "Startup"
The first time a new install of DisOrder is started it will run
.B disorder-rescan
to pick up new tracks.
On subsequent server restarts it will NOT do
this automatically; if you want a rescan at every restart you must
arrange that manually.
.PP
There is however an automatic rescan once every 24 hours.
.PP
A \fBroot\fR login is automatically created on startup if it does not
exist.
If \fBdisorder\fR(1) is run as root on the same machine as the
server it is capable of extracting the password from the database
directly.
.PP
Therefore it is immediately possible to create other users with
.B "disorder adduser"
as root on the server machine.
However it is likely to be preferable to get users to register
themselves via the web interface; see
.B setup-guest
in
.BR disorder (1)
for more details on this.
.SS "Logging"
In its usual configuration, DisOrder logs to daemon.* via \fBsyslog\fR(3).
Exactly where this ends up depends on the contents of
.IR /etc/syslog.conf .
.SS "Locales"
.B disorderd
is locale-aware.
If you do not set the locale correctly then it may not handle
non-ASCII data properly.
.PP
Filenames and the configuration file are assumed to be encoded using the
current locale.
Internally (within the server, in the database and in
communication between client and server) the UTF-8 encoding is used.
.SS Backups
DisOrder uses Berkeley DB but currently discards log files that are no longer
in use.
This means that DB's catastrophic recovery cannot be used (normal
recovery can be used, and indeed the server does this automatically on
startup).
.PP
It is suggested that instead you just back up the output of
.BR disorder\-dump (8),
which saves only the parts of the database that cannot be regenerated
automatically, and thus has relatively modest storage requirements.
.SH SIGNALS
.TP 8
.B SIGHUP
Re-read the configuration file.
.TP
.B SIGTERM
Terminate the daemon gracefully.
.TP
.B SIGINT
Terminate the daemon gracefully.
.PP
It may be more convenient to perform these operations from the client
\fBdisorder\fR(1).
.SH FILES
.SS "Configuration Files"
.TP
.I pkgconfdir/config
Global configuration file.
See \fBdisorder_config\fR(5).
.TP
.I pkgconfdir/config.private
Private configuration (now largely obsolete).
.TP
.I ~/.disorder/passwd
Per-user password file.
.SS "Communication"
.TP
.I pkgstatedir/socket
Communication socket for \fBdisorder\fR(1).
See \fBdisorder_protocol\fR(5) for protocol documentation.
.SS "Internal State"
Don't modify these files, especially not while the server is running.
.TP
.I pkgstatedir/queue
Saved copy of queue.
.TP
.I pkgstatedir/recent
Saved copy of recently played track list.
.TP
.I pkgstatedir/global.db
Global preferences database.
.TP
.I pkgstatedir/noticed.db
Records recently added tracks.
.TP
.I pkgstatedir/prefs.db
Preferences database.
.TP
.I pkgstatedir/schedule.db
Database of scheduled tasks.
.TP
.I pkgstatedir/search.db
Search lookup database.
.TP
.I pkgstatedir/tags.db
Tag lookup database.
.TP
.I pkgstatedir/tracks.db
Tracks database.
.TP
.I pkgstatedir/users.db
User database.
.TP
.I pkgstatedir/DB_CONFIG
Berkeley DB configuration file.
This may be used to override database settings without recompiling
DisOrder.
See the Berkeley DB documention for further details.
.TP
.I pkgstatedir/log.* \fRand \fIpkgstatedir/__db.*
Database internal files.
.TP
.I pkgstatedir/speaker/socket
Socket for communication with \fBdisorder-speaker\fR(8).
.TP
.I pkgstatedir/lock
Lockfile.
This prevents multiple instances of DisOrder running simultaneously.
.SH ENVIRONMENT
.TP
.B LC_ALL\fR, \fBLANG\fR, etc
Current locale.
See \fBlocale\fR(7).
.SH "SEE ALSO"
\fBdisorder\fR(1), \fBdisorder_config\fR(5), \fBdisorder\-dump\fR(8),
\fBdisorder.cgi\fR(8)
.\" Local Variables:
.\" mode:nroff
.\" End: