cdServer
 
Home
 
Display database
 
Help
Manual
 
 

cdServer manual

CDSERVER(1)
=============
Dr. Eckhard Licher 
v0.8, Jan15 2006


NAME
----
cdServer - HTTP server designed for serving files off CD-ROMs
with simple API for dynamic content generation


SYNOPSIS
--------
'cdServer.py' [-p number] [-r rootdir] [-s] [-t] [-a host] [-n net]
[-v] [-h] [-m] [-d] [--port=number] [--root=rootdir] [--server-only]
[--threaded-server] [--add-host=host] [--add-network=net] [--verbose]
[--help] [--manual] [--debug]


DESCRIPTION
-----------
'cdServer' is a simple HTTP server designed to serve HTML files off a CD-ROM.
'cdServer' also provides a simple interface for special functions implemented
in external application programs, e.g. search functions.  The current server
implementation only handles GET and HEAD requests.  POST requests are not
implemented.


OPTIONS
-------
'-p number', '--port=number'::
        sets the server's portnumber to number

'-r rootdir', '--root=rootdir'::
        sets the serverroot to directory rootdir

'-s', '--server-only'::
        server-only mode, no browser launched

'-t', '--threaded-server'::
        start separate thread for each request

'-v', '--verbose'::
        display additional messages at startup

'-a, --add-host'::
        add host to list of allowed hosts (ip address or host name)

'-n, --add-network'::
        add network to list of allowed networks;
        network is specified with CIDR notation, e.g. 192.168.0.0/24

'-h', '--help'::
        display help message

'-m', '--manual'::
        display this manual page

'-d', '--debug'::
        switch on debug mode

Options specified at the command line are evaluated from left to right.

When invoked without options, 'cdServer' 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 next port unless option '-p' is specified. If option '-p'
is specified the port auto-search function is turned off.

The serverroot is set to the parent directory of the 'cdServer'
executable unless the serverroot is explicitly specified by means of
option '-r'.  The default serverroot allows the start of the server off
the distribution CD-ROM without prior installation or customization.

Subsequently the default web browser is launched unless option '-s' is
given at the command line.

The verbosity of the server during startup can be increased slightly
with option '-v'.

If option '-t' is given the server starts a separate thread for each
request in order to enable the server to serve a large number of
possibly long-running parallel requests without blocking other clients.

For security reasons only requests originating from the local machine
are being served by default. Other hosts need to be included explicitly
in the access control list by means of option '-a'. Option '-a' may be
used more than once in order to allow access from several hosts.
Additionally, entire networks may be specified using option '-n';
network addresses shall be specified using CIDR format
(e.g. 192.168.0.0/24).

Incorrect invocation of the server as well as option '-h' display a
brief help message.  The full manual page is printed through option
'-m'.  In either case program execution terminates regardless of other
options possibly specified.

Upon startup 'cdServer' tries to import an application (a python module
named cdApp.py). If the import succeeds the application is supposed to
provide a request handler which is used instead of the built-in
SimpleHTTPRequesthandler from the Python standard library. The
application's request handler is in charge of intercepting special URLs
and providing additional functionality.

Option '-d' switches on debug mode.  cdApp is imported without catching
errors during import and variable cdApp.debug is set to True.


RUNTIME PROBLEMS
----------------
'cdServer' tries to do its best when being run in an unfriendly
environment such as Windows or on mis-configured machines and handles
common problems gracefully.

In case the server can not listen on the requested port the browser
is launched using the filesystem and 'cdServer' terminates itself.  On
a sensibly configured machine this should only happen if 'cdServer' is
being run by a regular user and the requested port is below 1024.

The server is started in a separate thread so that a local firewall
which may block intra-machine IP traffic can be detected.  After
successful startup of the server a test request is fired (from the main
thread) at the server.  If the request fails a firewall is blocking the
internal request.  In this case the browser is launched using the
filesystem and 'cdServer' terminates itself.  This is a common problem
on Windows machines where an unnecessary restrictive firewall is
installed.


AVAILABILITY
------------
'cdServer' is available on all platforms that support Python 2.2 or
later.


AUTHOR
------
Dr. Eckhard Licher, Frankfurt am Main, Germany

'cdServer' is available for download at
http://www.licher-ffm.de/cdServer.html


ACKNOWLEDGEMENTS
----------------
The code for access control lists for entire networks (option -n,
introduced in version 0.8) was contributed by Forest Bond
 to moosicWebGUI and copied to 'cdServer'
with his permission.


FILES
-----
cdApp.py


BUGS
----
Please send bug reports to 


COPYRIGHT
---------
Copyright (C) 2004-2006 by Dr. Eckhard Licher, Frankfurt/Main, Germany.

This program is Free Software; you can redistribute it and/or modify
it under the terms of the GNU Library 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 Library General Public License (contained in file bin/COPYING.LIB)
for more details.

You should have received a copy of the GNU Library 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.

 © 2005 by Eckhard Licher, Frankfurt am Main, Germany. cdServer is Free Software. See file COPYING.LIB for details.