HTTPD(1) BSD General Commands Manual HTTPD(1)NAMEhttpd — WWW server conforming to HTTP/1.1
SYNOPSIShttpd [-v]
httpd [-c configfile] [-P preprocessor] [-m message] [-N] [-p port]
[-u user] [-g group] [-n number] [-d directory] [-a address]
DESCRIPTION
This manual describes the behaviour of xs-httpd/3.7 beta/0.35.
Note that the server must run as root in order to use a port number below
or equal to 1024 (the default is 80). Also, to have users' CGI binaries
executed under their own user ID, the webserver should be started with
root privileges.
The server has a number of command line options. These are listed below,
starting with the options that do not have an equivalent configuration
file setting:
-c configfile
Uses the specified configuration file instead of the default.
The default location can be displayed using the -v option.
-P preprocessor
Run the preprocessor command to parse the global configuration
file, for example ‘m4’ or ‘cpp’. A fixed preprocessor program
can also be set at compile time.
-m service-message
If you give this option to the server, it will not function as it
normally would. Instead of supplying documents, all it will do is
display the service-message. This is very useful to at least
give users an idea of what you are doing when the server is tem‐
porarily out of order. Remember that if you are supplying an
entire sentence, then you have to enclose that sentence in quotes
(").
-N This option disables reading of the configuration file and writ‐
ing of logfiles and pidfile. This can be useful for testing, non-
superuser execution or in combination with the -m option.
-v Shows the server version number and certain compile options.
This does not launch a daemon but exits immediately.
Additional options may be specified on the command line or in the
httpd.conf configuration file. Please use the more flexible configuration
file for all standard settings, see httpd.conf(5) for details.
-p portnumber
Listen for incoming HTTP requests on port portnumber instead of
the default (the factory default is 80).
-u username
Runs the server under username' s user id instead of the default
(the factory default is nobody). This option is only available
when running as root and the selected user should be unprivileged
(it can not be root).
-g groupname
Runs the server under groupname 's group id instead of the
default nogroup.
-n number
Uses number as the number of servers to start (the factory
default is 20).
-d rootdir
Uses rootdir as the base directory for other directories like the
logs directory, the htdocs directory and the cgi-bin directory.
The factory default rootdir is @rootdir@/.
-a address
Uses address as the internet address to listen on. This name may
be used in redirects, so the fully qualified domain name for this
address should be used.
Server design
XS-httpd has some important features that distinguishes it from other
well-known webservers. The following list highlights the main concepts:
‐ Small and fast
The webserver was designed to be small and fast. Although it should
be fully standards-compliant, it does lack some of the more elaborate
features that other servers offer.
An important design choice is to run with pre-forked processes: which
means it doesn't start up a new client process for every connection
to the webserver. This has advantages and disadvantages, but in gen‐
eral leads to a faster response and less overhead.
‐ Multi-user environment
The server can be used on a multi-user system where every user has
their own website(s). The webpages will be retrieved under the user's
uid, so there is no need to make documents with sensitive data (such
as database passwords) readable to other users on the same server.
CGI scripts, server-side include controls (SSI) and server-side
interpreters (PHP, Python) will run with full user privileges as
well. This gives the users a lot of flexibility to organise their
own webspace and also limits the effect of problems with a user's
scripts to their own environment. See httpd_cgi(7) and httpd_ssi(7)
for detailed descriptions.
‐ Full user control
It should be possible for skilled users to exercise a great deal of
control over their own webspace. The ability to run CGI binaries in
any language or choose local interpreters and mime-types for any doc‐
ument is an important aspect of this.
But users can also limit access to (part of) their webspace to cer‐
tain visitors using (built-in) HTTP authentication with freely chosen
usernames and passwords. Users can choose for Basic or Digest authen‐
tication, or even configure access using SSL client-certificates, or
blocking/allowing certain IP ranges.
Of course the amount of control a user actually has can be limited by
the webserver administrator. It is for instance possible to set
resource limits on user scripts, or even disable the feature com‐
pletely in the global configuration file.
Automatic decompression
One of the nice features of the WWW server is automatic decompression.
This feature is dealt with in the file called compress.methods.
This file lists the possible compression types that are understood by the
WWW server. It works very simply: if somebody asks for (for example)
index.html, and this file does not exist, but index.html.gz does exist,
then index.html will be `generated' out of index.html.gz using the method
specified with .gz. Note that this process does not actually create
index.html in that same directory. It creates a file in the temporary
directory, which is removed immediately after usage.
In the case that the browsers accepts certain document encodings (gzip is
quite common) and the document is stored on disk in an acceptable format,
then the server won't even bother to decompress the document himself, but
will send it to the client compressed as it is, so that the browser will
extract it itself before presenting the document to the user.
If somebody asks directly for index.html.gz, he will get it in the com‐
pressed format. This way, nice things like the following can be done:
Get <A HREF="xshttpd.tar">the uncompressed tar</A>,
or get the <A HREF="xshttpd.tar.gz">the compressed tar</A>.
The user only has to have the compressed version, because if somebody
asks for the uncompressed version, the server will uncompress it on the
fly for that user.
Note that only one compression type per file is possible. Of course, you
can make frontends for types that require multiple filters. In that case,
it can be helpful to know that the list is traversed from top to bottom.
Authentication
This server supports the basic and digest HTTP authentication protocols.
This means that users can protect their pages with a username/password
combination. Other servers can do this as well, but they lack one thing:
the "protected" files often have to be world-readable. Because our server
retrieves pages under users' own uid, this problem is avoided.
Basic authentication does not provide (password) encryption. If you are
worried about other parties intercepting your communications, you should
configure SSL (as explained below). More information about setting up
authentication passwords can be found in the manual pages of xspasswd(1)
and xsauth(5).
Authentication can also be handled using SSL client certificates. How‐
ever this requires the user to deal with SSL_* environment variables in
an CGI environment. See the description of the available CGI variables in
httpd_cgi(7).
Secure Sockets Layer
The webserver supports secure https connections as well as normal http.
However if you want to do both, you will need to run separate instances,
one with UseSSL (or the command line option -s) set and one without.
To use SSL you will need an X.509 certificate (cert.pem) and the corre‐
sponding private key (key.pem). If you don't have certificates -or a
certificate authority to give these to you- then you can create the
required files yourself using openssl(1).
The two *.pem files are usually stored in the httpd configuration direc‐
tory. You can use other filenames for the certificate and private key by
setting the parameters SSLCertificate and SSLPrivateKey in the configura‐
tion file.
An example SSL-Makefile that can help you generate the certificate, can
be found in the httpd source distribution.
Additional HTTP/1.1 features
Several new features were derived from the RFC 2616 standard:
· Persistent connections (multiple get/post requests per connection)
· Additional http methods (OPTIONS, PUT, DELETE and TRACE)
· Chunked transfers (both for input and output)
· Content trailers (additional headers following end of data)
· Conditional requests (If-*, Accept-*)
· Content entity tags (ETag) and digests (MD5 checksum)
Built-in support for common tasks
XS-httpd configuration files, server-side includes and several additional
programs make certain tedious tasks a lot simpler for the common user.
Examples are:
· Page counters served using server-side includes: daily or total page
views can be included in text or in graphical fonts.
· Easy configuration of headers that describe the content: the mime-
type, character set and language of documents can be set per file,
file extension or directory tree by the user.
· Allow user-settable redirects (HTTP 301, 302 code), server-side file‐
name rewriting rules or proxying to have the server retrieve contents
from another backend server.
ENVIRONMENT
All environment variables which were set when the program was started
will be ignored. These are not available to CGI scripts or other child
processes. See httpd_cgi(7) for the variables that will be available
within the httpd environment.
FILES
The global configuration file is httpd.conf: this should be configured by
the site administrator before starting the webserver. All available set‐
tings are explained in httpd.conf(5).
There are several files that this WWW server considers special when they
appear in the HTML documents directories. These files start with a dot
(hidden) and contain special instructions for the webserver that apply to
a sigle file or all files in a directory (and underlying subdirectories).
.xsconf
This file provides a generic interface to set a lot of the
options mentioned below, specifically for a certain file or group
of files. It allows you to set file-specific mime type, charac‐
ter set, passwords and other access restrictions. See xsconf(5)
for full details.
.noxs If this file exists in a certain directory, that entire directory
is considered closed. If somebody attempts to retrieve a file
from that directory, he will get a ‘Permission denied’ notice.
This is useful for users and system administrators: users can use
it when they are updating the directory and system administrators
can use it to easily shut down a group of pages. This applies to
subdirectories as well.
It is possible to allow access to this directory for a limited
number of hosts. You can list the IP-addresses to which access
should be granted in this file (one address per line). This works
for IPv4 as well as IPv6 addresses. Or you can use CIDR notation
to allow an entire subnet. So including "131.155.140.0/23" will
unblock 131.155.140.0 - 131.155.141.255.
.redir If this file is present in a certain directory, and a file is
requested from that directory, then a redirection message will be
sent to the remote user's browser. See xsredir(5) for the format
of this file.
.xsauth
If this file exists, all files in that directory and subdirecto‐
ries are protected by usercode/password combinations. See
xsauth(5) for more details about this.
Use of the following files is deprecated. They can still be used, but
support may be dropped in the future. The same (or better) functionality
is offered by the xsconf(5) local configuration feature.
*.redir
If a (regular) file is requested and a file exists with the same
name but with that is mentioned in this *.redir file.
*.Redir
The same as ‘*.redir’, however instead of a temporary redirection
(302) a permanent redirection (301) will be sent.
.charset
If this file is present in a certain directory, then all files
requested from that directory will get an extra HTTP header which
indicates the character set used, as specified by the contents of
the .charset file. Useful settings are e.g. UTF-8, ISO-8859-1,
KOI8-R.
*.charset
Sets the character set for a specific file (see *.redir).
.mimetypes
This file lets a user override the contents of the global
mime.types file. The syntax of this file is exactly the same as
that for the global configuration file, but it applies (recur‐
sively) to the local subdirectories.
.xsscripts
This file lets a user override the contents of the global
script.methods fP file. The syntax of this file is exactly the
same as that for the global configuration file and it applies
(recursively) to the local subdirectories. See xsscripts(5) for
more information.
.xsuid If this file exists in a certain directory, all files in that
directory will be retrieved as (by default) nobody/nogroup
instead of under your own UID. This can be useful if you want a
file permission of say 600 to mean: do not allow retrieval (by
default, the file is retrieved under your own UID, so the daemon
could have still read those files).
DIAGNOSTICS
The httpd returns status 0 when it starts successfully and the daemon
will continue to run in the background. If any fatal error occurs, addi‐
tional information should be available in the logfile error_log.
SEE ALSOhttpdc(1), xspasswd(1), xsindex(1), readxs(1), clearxs(1), imagemap(1),
gfxcount(1), xschpass(1), httpd.conf(5), xsauth(5), xsconf(5),
xsredir(5), xsscripts(5), httpd_cgi(7), httpd_ssi(7)
The project homepage: http://www.stack.nl/xs-httpd/
STANDARDS
Hypertext Transfer Protocol -- HTTP/1.0, RFC 1945, May 1996.
Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616, June 1999.
HTTP Authentication: Basic and Digest Access Authentication, RFC 2617,
June 1999.
HTTP State Management Mechanism, RFC 2965, October 2000.
The Common Gateway Interface (CGI) Version 1.1, RFC 3875, October 2004.
The Transport Layer Security (TLS) Protocol Version 1.1, RFC 4346, April
2006.
FastCGI Specification Version 1.0,
http://www.fastcgi.com/devkit/doc/fcgi-spec.html, April 1996.
AUTHORS
The original author of this WWW server and its accompanying programs is
Sven Berkvens, except the imagemapper which was taken from the NCSA dis‐
tribution and cleaned up. The current maintainer is Johan van Selst.
Please use the general contact address ⟨xs-httpd@stack.nl⟩ for queries.
BUGS
Support for the alternative document processing methods using internal
Perl, Python, Ruby or FastCGI hooks is still highly experimental and not
very useful. These features should not be used in a production environ‐
ment.
xs-httpd/3.5 March 26, 1996 xs-httpd/3.5
