httpd - WWW server conforming to HTTP/1.1
Secure Sockets Layer
Additional HTTP/1.1 features
Built-in support for common tasks
httpd [-v] httpd [-c configfile] [-P preprocessor] [-m message] [-N] [-p port] [-u user] [-g group] [-n number] [-d directory] [-a address]
This manual describes the behaviour of xs-httpd/3.7 beta/0.28.
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 temporarily 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 writing 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.
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 doesnt start up a new client process for every connection to the webserver. This has advantages and disadvantages, but in general 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 users 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 users 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 document is an important aspect of this.
But users can also limit access to (part of) their webspace to certain visitors using (built-in) HTTP authentication with freely choosen usernames and passwords. Users can choose for Basic or Digest authentication, 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 completely in the global configuration file.
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 wont 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 compressed 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.
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. However 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).
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 x509 certificate ( cert.pem) and the corresponding private key ( key.pem). If you dont 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 config directory. You can use other filenames for the certificate and private key by setting the parameters SSLCertificate and SSLPrivateKey in the configuration file.
An example SSL-Makefile that can help you generate the certificate, can be found in the httpd source distribution.
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)
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 pageviews 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 filename rewriting rules or proxying to have the server retrieve contents from another backend server.
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.
The global configuration file is httpd.conf: this should be configured by the site administrator before starting the webserver. All available settings 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, character 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 "188.8.131.52/23" will unblock 184.108.40.206 - 220.127.116.11.
.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 users browser. See xsredir(5) for the format of this file. .xsauth If this file exists, all files in that directory and subdirectories 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
.Pl .redir appended to it, then the client will be redirected to the URL 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 (recursively) 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).
The httpd returns status 0 when it starts successfully and the daemon will continue to run in the background. If any fatal error occurs, additional information should be available in the logfile error_log.
httpdc(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/
.Rs Hypertext Transfer Protocol -- HTTP/1.0
.Rs Hypertext Transfer Protocol -- HTTP/1.1
.Rs HTTP Authentication: Basic and Digest Access Authentication
.Rs HTTP Over TLS
.Rs HTTP State Management Mechanism
.Rs The Common Gateway Interface (CGI) Version 1.1
.Rs The Transport Layer Security (TLS) Protocol Version 1.1
.Rs FastCGI Specification Version 1.0
The original author of this WWW server and its accompanying programs is Sven Berkvens, except the imagemapper which was taken from the NCSA distribution and cleaned up. The current maintainer is Johan van Selst.
Please use the general contact address <email@example.com> for queries.
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 environment.
|March 26, 1996||HTTPD (1)||xs-httpd/3.5|