moosicwebgui.1

.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "MOOSICWEBGUI" "1" "03 Dezember 2005" "" ""

.SH NAME
moosicWebGUI \- web GUI for controlling the moosicd daemon
.SH SYNOPSIS
.PP
\fBmoosicWebGUI.py\fR [-p number] [-s] [-i] [-j name] [-a host]
[-n net] [-h] [-m] [-d] [-c configdir] [-t template]
[--port=number] [--server-only] [--ignore-exit]
[--jukebox-dir=name] [--add-host=host] [--add-network=net]
[--help] [--manual] [--debug] [--config=configdir]
[--template=template]
.SH "DESCRIPTION"
.PP
\fBmoosicWebGUI\fR is a web GUI based on a simple HTTP server with
special built-in commands for controlling the moosicd daemon.
The HTTP server implementation only handles GET and HEAD
requests. POST requests are not implemented.
.SH "OPTIONS"
.TP
\fB-p number, --port=number\fR
set the server's portnumber to number
.TP
\fB-s, --server-only\fR
server-only mode, no browser is launched
.TP
\fB-i, --ignore-exit\fR
ignore exit request via HTTP request
.TP
\fB-j, --jukebox-dir\fR
select directory containing music files
.TP
\fB-a, --add-host\fR
add host to list of allowed hosts (ip address or host name)
.TP
\fB-n, --add-network\fR
add network to list of allowed networks;
network is specified with CIDR notation, e.g. 192.168.0.0/24
.TP
\fB-h, --help\fR
display help message and exit
.TP
\fB-m, --manual\fR
display this manual page and exit
.TP
\fB-d, --debug\fR
include debug information in HTML pages
.TP
\fB-c configdir, --config=configdir\fR
take moosic configuration from configdir
.TP
\fB-t template, --template=template\fR
use specified template file
.PP
Options specified at the command line are evaluated from left
to right.
.PP
When invoked without options, \fBmoosicWebGUI\fR serves HTTP
requests through port 8000.  In case port 8000 is already in
use the server searches for an unused port by subsequently
incrementing the port number and trying to bind to the port
unless option \fB-p\fR is specified. If option \fB-p\fR is specified
the port auto-search function is turned off.
.PP
Unless option \fB-s\fR is specified \fBmoosicWebGUI\fR tries to
launch the system's web browser with the initial URL pointing
to the internal web server.
.PP
\fBmoosicWebGUI\fR can be terminated with a HTTP request to \fB/exit\fR\&.
This exit request can be disabled with option \fB-i\fR\&.
.PP
The directory containing music files is assumed to be $HOME.
In case $HOME is not set /tmp is assumed to be the jukebox
directory. It may be explicitly specified by option \fB-j\fR\&.
.PP
For security reasons only requests originating from the local
machine are being served by default. Other hosts need to be
included explicitly to the access control list by means of
option \fB-a\fR\&. Option \fB-a\fR may be used more than once in order
to allow access from several hosts.  Additionally, entire
networks may be specified using option \fB-n\fR; network addresses
shall be specified using CIDR format (e.g. 192.168.0.0/24).
.PP
Incorrect invocation of the program as well as option \fB-h\fR
display a brief help message. The full manual page, i.e. this
document, is printed through option \fB-m\fR\&. In either case
program execution terminates regardless of other options
possibly specified.
.PP
If option \fB-d\fR is specified some debug information and a link
to the wdg's html validator is included in the generated HTML
pages. To validate pages package wdg-html-validator needs to
be installed.
.PP
The moosic configuration is read from the default directory
($HOME/.moosic/ or /tmp/.moosic/) unless option \fB-c\fR is
specified.
.PP
An alternate template may be specified by means of option \fB-t\fR\&.
.SH "FILES"
.TP
\fBtemplate.html\fR
Page template file used for content generation.
.TP
\fBCOPYING\fR
License text (GPL version 2).
.SH "ENVIRONMENT"
.TP
\fBHOME\fR
The user's home directory is taken as the default jukebox
directory. Overridden by the -j option.
.SH "DIAGNOSTICS"
.PP
The following diagnostics may be issued on stderr:
.TP
\fBDNS lookup for host <host> failed.\fR
The host's IP address could not be resolved -- check spelling.
.TP
\fB<network> is not a valid network specification.\fR
The network specification is not valid -- it shall be in CIDR
format, e.g. 192.168.0.0/24.
.TP
\fBThe moosicd server doesn't seem to be running, and it could not ...\fR
For some reason it was not possible to start the moosicd server.
.TP
\fBAn attempt was made to start the moosic server, but ...\fR
An attempt was made to start the moosic server, but for some strange
reason it was not possible to start the moosicd server.
.TP
\fBMoosic api version <version> is not supported (must be 1.7 or later).\fR
Use a moosic version >= 1.5.
.TP
\fBCan not connect to port <port>\fR
The webserver could not connect to port <port> -- use a free port
higher than port number 1024.
.TP
\fBCan not start new server, giving up. Sorry.\fR
The webserver terminated due to a weird error and could not
be restarted.
.SH "AVAILABILITY"
.PP
\fBmoosicWebGUI\fR is available on all platforms supporting Python 2.2
or later.
.SH "CAVEATS"
.PP
This is alpha software, so beware.
.PP
The jukebox directory may any directory other than \fB/\fR\&. This should
be considered to be a feature :-)
.SH "BUGS"
.PP
Please send bug reports to the author.
.SH "AUTHOR"
.PP
2005 Eckhard Licher, Frankfurt, Germany. <develf at online dot de>
.SH "ACKNOWLEDGEMENTS"
.PP
The code for the initiation of the connection to moosicd and the
easter egg was adapted from the moosic client written by Daniel
Pearson <daniel at nanoo dot org>\&.
.PP
Options -n, -c and -t: the code for access control list for entire
networks, scanning of moosic config file for supported file types
and the use of alternate template file (introduced in version 0.8.1)
was contributed by Forest Bond <forest at alittletooquiet dot net>\&.
.SH "SEE ALSO"
.PP
moosic(1), moosicd(1), validate(1)