Shttpd
is an HTTP server that supports most of the reasonable features of contemporary http servers:
- •
- http/1.0 and http/1.1 support
- •
- cgi and scgi support
- •
- directory listings
- •
- index file serving
- •
- redirections based on regular expressions
- •
- virtual hosting
- •
- determining mimetype based on file extension
- •
- "range" requests, for random access to files
- •
- access and error logging
- •
- configuration in attrdb format
- •
- as compliant as possible, where reasonable
- •
- mindful of security
Shttpd
serves files from
webroot.
Options, described below, configure all features except virtual hosting.
For virtual hosting, a configuration file must be used and the command-line options will only apply to the "default" hostname (i.e. all besides those explicitly configured). The configuration file, specified using
-n config
is in
attrdb(6)
format. It is read only at startup and at explicit request.
The attributes are described below, with their corresponding command-line options. An example configuration file:
debug
#nodebug
vhost
#novhost
ctlchan=shttpd
accesslog=/services/logs/shttpdaccess
announce=net!www.example.com!80
mime ext=.text type='text/plain; charset=utf-8'
mime ext=.mov type='video/quicktime'
mime ext=.erl type='text/plain; charset=utf-8'
# port=80 is not necessary, it's the default
host=www.example.com port=80
listings path=''
cachesecs=60
index file=index.html file=index.htm file=index.txt
redir src='^/oldfile$' dst=/newfile
redir src='^/oldpath/(.*)$' dst=/newpath/$1
scgi path=/scgi/test addr=net!localhost!4000
cgi path=/cgi/env methods=GET,HEAD cmd='{load std; echo Status: 200 OK; echo content-type: text/plain; echo; cd /env && for(i in *) { echo $i''=''`{cat $i}}}'
auth path=/secret realm='secret place' user=username pass=password
alias
host=example.com port=80 usehost=www.example.com useport=80
The options and their configuration file equivalents:
- -d
- Print debug messages to standard error and the error log,
/services/logs/shttpderror.
Attributes `debug' and `nodebug' enable and disable debugging. Due to attrdb, `nodebug' always takes precedence regardless of position in file.
- -h
- Serve multiple domains, known as virtual hosting. The `host'-header in the request (for http/1.1-only) selects the targeted host. If enabled, the
host
and TCP
port
in the request are looked up in the configuration, and files are served from
webroot/host!port.
Note that the port is not taken from the `host'-header, but always from the local port of the connection.
If no configuration could be found or when no specific host was requested (e.g. for http/1.0 requests), the default configuration will be used: host `_default' and port 80.
Files in
webroot
are never served directly with
-h
present.
Attributes `vhost' and `novhost' enable and disable virtual hosting. Due to attrdb, `novhost' always takes precedence regardless of position in file.
Virtual hosts can only be specified with the configuration file. A
`host'
entry starts a configuration for a domain, attribute
`port'
is optional and defaults to 80.
The value for
`host'
may be `*'. In this case the entry will serve as default entry, used when no other entry matches an incoming request.
A host configuraty entry can be reused for another host by an entry with attribute `alias' (value ignored). Attributes
`host'
and
`port'
specify the new host,
attributes
`usehost'
and
`useport'
specify which entry to use for requests instead.
`Port' may be omitted, defaulting to `80'. `Usehost' defaults to the value of `port'.
- -L path 0|1
- For
path
and its subdirectories, set whether the request for a directory returns a html-formatted listing of files (when the second parameter is `1'), or a "file not found"-error (when the second parameter is `0').
Listings are only returned when no index file (see
-i)
The per-host configuration attributes are
`listings' and `nolistings' (value ignored). One or more paths can be specified using the attribute `path'.
In determining whether to list directory contents, the most specific match (longest prefix) wins.
- -A path realm user:pass
- Require authorization for
path.
The match on
path
is a prefix-match.
Note that the path does not have to end with a slash.
Only insecure "basic" authorization is currently supported, "digest" is not.
The per-host configuration attribute is
`auth' (value ignored).
`Path'
specifies the path,
`realm'
the descriptive realm,
`user'
the user name and
`pass'
the password.
Paths
may occur multiple times in different `auth'-lines, each valid user/pass combination is allowed access.
- -C cachesecs
- Add header to allow clients to keep the response in their cache for
cachesecs
seconds. This only applies to static content (i.e. files and directory listings) not cgi and scgi handlers.
The per-host configuration attribute is
cachesecs.
- -a address
- Announce to
address
and listen for incoming connection.
The global configuration attribute is
`announce',
the value is the address to listen on.
For a reload of the configuration attributes, the announce-addresses are ignored. To announce to a different set of ports, restart
shttpd.
If no addresses are specified,
shttpd
will listen on
net!*!http.
- -c path command methods
- Handle requests for
path
by executing
command.
The normal CGI/1.1 rules apply for
command.
Path
is prefix-matched and does not have to end with a slash.
Command
is executed using
sh(2).
Methods
is a comma- or space-separated list of methods (case-sensitive) that are allowed on the resource. An empty list allows all methods.
The per-host configuration attribute is
`cgi'
(value ignored).
`Path'
specifies the host,
`cmd'
the command and
`methos' the methods.
- -f ctlchan
- Create a
sys-file2chan(2)
control file in
/chan
named
ctlchan.
Currently, only the command `reload' is accepted. It reloads the configuration file currently in use.
This is a global configuration file option, the corresponding attribute is
`ctlchan'.
Only a single control file can be registered.
- -i indexfile
- Search for the file named
indexfile
when a directory is requested and return that instead. This is commonly used to serve an
`index.html'.
Multiple file names can be specified, each will be tried in turn until a match is found.
The per-host configuration attribute is
`index' (value ignored).
Multiple attributes
`file'
can be specified, each being handled as
-i
indexfile.
- -l logfile
- Write the access log to
logfile.
For each response, the following is printed (as a list of quoted words, quoted as in
sh(1)):
Connection id, timestamp, remote and local ip and port, method, requested host (from `host'-header), path (with query), http version, response code, message and length, the user-agent that sent the request, the referer and finally the domain name for the ip address.
The global configuration attribute is
`accesslog'. The file is also reopened on a reload of the configuration file.
- -n config
- Use
config
of the configuraton file, which is in
attrdb(6)
format.
There is no default configuration file. The command-line options can be used for simple configurations.
Since command-line options are handled in the order specified and
-n
overrides the current configuration, command-line options specified before
-n
are effectively ignored. Options specified after
-n
are used for the `default' host. Note that a reload also replaces all command-line options.
There is no equivalent for the configuration file. Be sure to use full path names on the command-line if you want reloads to work.
- -r pathre dest
- Redirect requests that match regular expression
pathre
to
dest
with an HTTP ``301 Moved Permanently'' response.
Pathre
can contain groups, specified with ()'s as per
regex(6)
syntax. Occurrences of $0, $1, etc. in
dest
are replaced by the corresponding group in
pathre.
Group `$0' is the entire match and `$1' the first match. Occurrences of `$$' will be replaced by the literal `$'.
For
pathre,
`^' means beginning of path and `$' means end of path.
The per-host configuration attribute is
`redir' (value ignored).
`Src'
is the equivalent of
pathre,
`dst'
the equivalent of
dest.
- -s path addr methods
- Handle requests for
path
by passing the requests to the SCGI handler at
addr.
Path
is prefix-matched and need not end with a slash.
Methods
is a comma- or space-separated list of methods (case-sensitive) that are allowed on the resource. An empty list allows all methods.
The per-host configuration attribute is
`scgi'
(value unused).
`Path'
specifies the path,
`addr'
the address and
`methods' the methods.
- -t extension mimetype
- Registers extension (which is suffix-matched and thus should usually include a dot) as being of
mimetype.
For each response returning a static file, the mimetype to be returned is looked up in the types specified by
-t
and compiled-in types, in that order.
The global configuration attribute is
`mime' (value unused).
`Ext'
specifies the extension,
`type'
the mimetype.
- -z gzippath
- For a requested
path
starting with
gzippath,
return the gzip-compressed version
path.gz
instead.
Path.gz
is only returned if it exists and is smaller than the plain version, and
path
was not modified after
path.gz.
The per-host configuration attribute is `gzip' (value unused), one
or more `path' attributes specify the paths.
There is one last per-host configuration attribute that cannot be specified on the command-line:
`listen' (value unused).
On the same line,
`ip'
should be present and
`port'
may be present (it defaults to the port of the host definition).
If virtual hosts are enabled, the local address is checked for each request. If at least one ip address has been specified and the local address is not present in the addresses list of the per-host configuration for the request, a ``404 Object Not Found'' error is returned.
To prevent files to be served to the public inadvertently, the root directory of the
shttpd
is replaced by
webroot
with
sys-bind(2).
Also, suspicious combinations of headers are typically responded to with an error. This policy may err on the cautious side. For example, some important headers are not allowed to be specified twice.
Note that CGI programs run in the namespace
shttpd
had originally been started with.