173 lines
6.3 KiB
Groff
173 lines
6.3 KiB
Groff
.\" Process this file with
|
|
.\" groff -man -Tascii shttpd.1
|
|
.\" $Id: shttpd.1,v 1.9 2008/02/13 21:57:27 drozd Exp $
|
|
.Dd Feb 12, 2008
|
|
.Dt SHTTPD 1
|
|
.Sh NAME
|
|
.Nm shttpd
|
|
.Nd lightweight web server
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Ar options
|
|
.Op Ar config_file
|
|
.Nm
|
|
.Fl A Ar htpasswd_file domain_name user_name password
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is small, fast and easy to use web server with CGI, SSL, Digest Authorization
|
|
support. It can be run as stand-alone server, be managed by
|
|
.Xr inetd 8
|
|
, or be embedded into existing C/C++ application.
|
|
.Pp
|
|
.Nm
|
|
does not detach from terminal, and makes current working directory
|
|
be the web root, unless
|
|
.Fl root
|
|
option is specified.
|
|
.Pp
|
|
Unlike other web servers,
|
|
.Nm
|
|
does not expect CGI scirpts to be put in a special directory. They may be
|
|
anywhere. CGI files are recognized by the file extension.
|
|
.Pp
|
|
SSI files are also recognized by extension. Currently, the only SSI directives
|
|
supported are `<!--#include "url-encoded-path" -->'
|
|
and `<!--#exec "program" -->'. The `url-encoded-path' can be relative to
|
|
.Nm
|
|
working directory, or absolute system path. In the embedded mode, more
|
|
directives are available: #call, #if/#elif/#endif/#else/#endif.
|
|
Unsupported SSI directives are silently ignored.
|
|
.Pp
|
|
It is possible to specify multiple ports to listen on. For example, to
|
|
make
|
|
.Nm
|
|
listen on HTTP port 80 and HTTPS port 443, one should start it as
|
|
.Sq shttpd -ssl_cert cert.pem -ports 80,443s
|
|
.Pp
|
|
.Nm
|
|
can use the configuration file. By default, it is "shttpd.conf", and if it
|
|
is present in the same directory where
|
|
.Nm
|
|
lives, the command line options are read from it. Alternatively, the
|
|
configuration file may be specified as a last argument. The format of the
|
|
configuration file is exactly the same as for the command line options, the
|
|
only difference is that the command line options must be specified on
|
|
separate lines, and dashes for options must be omitted.
|
|
Lines beginning with '#' are regarded as comments and ignored.
|
|
.Pp
|
|
.Sh OPTIONS
|
|
.Bl -tag -width indent
|
|
.It Fl A Ar htpasswd_file domain_name user_name password
|
|
Add/edit user's password in the passwords file. Deleting users can be done
|
|
with any text editor. Functionality similar to Apache's
|
|
.Ic htdigest
|
|
utility.
|
|
.It Fl access_log Ar file
|
|
Access log file. Default: not set, no logging is done.
|
|
.It Fl acl Ar (+|-)x.x.x.x[/x],...
|
|
Specify access control list (ACL). ACL is a comma separated list
|
|
of IP subnets, each subnet is prepended by '-' or '+' sign. Plus means allow,
|
|
minus means deny. If subnet mask is
|
|
omitted, like "-1.2.3.4", then it means single IP address. Mask may vary
|
|
from 0 to 32 inclusive. Default: not set, allow all.
|
|
.It Fl aliases Ar list
|
|
This options gives an ability to serve the directories outside web root
|
|
by sort of symbolic linking to certain URI. The
|
|
.Ar list
|
|
must be comma-separated list of URI=PATH pairs, like this:
|
|
"/etc/=/my_etc,/tmp=/my_tmp". Default: not set.
|
|
.It Fl auth_PUT Ar file
|
|
PUT and DELETE passwords file. This must be specified if PUT or
|
|
DELETE methods are used. Default: not set.
|
|
.It Fl auth_gpass Ar file
|
|
Location of global passwords file. When set, per-directory .htpasswd files are
|
|
ignored, and all accessed must be authorised against global passwords file.
|
|
Default: not set.
|
|
.It Fl auth_realm Ar domain_name
|
|
Authorization realm. Default: "mydomain.com".
|
|
.It Fl cfg_uri Ar uri
|
|
If set,
|
|
.Nm
|
|
creates special administrative URI where options may be changed at runtime.
|
|
This URI probably wants to be password-protected, look at
|
|
.Fl protect
|
|
option, and in the EXAMPLES section on how to do it. Default: not set.
|
|
.It Fl cgi_env Ar list
|
|
Pass environment variables to the CGI script in addition to standard ones.
|
|
The list must be comma-separated list of X=Y pairs, like this:
|
|
"VARIABLE1=VALUE1,VARIABLE2=VALUE2". Default: not set.
|
|
.It Fl cgi_ext Ar list
|
|
Comma-separated list of CGI extensions. All files having these extensions
|
|
are treated as CGI scripts. Default: "cgi,pl,php"
|
|
.It Fl cgi_interp Ar file
|
|
Force
|
|
.Ar file
|
|
to be a CGI interpreter for all CGI scripts. By default this option is not
|
|
set, and
|
|
.Nm
|
|
decides which interpreter to use by looking at the first line of CGI script.
|
|
.It Fl dir_list Ar 0|1
|
|
Enable/disable directory listing. Default: "1" (enabled).
|
|
.It Fl error_log Ar file
|
|
Error log file. Default: not set, no errors are logged.
|
|
.It Fl inetd Ar 0|1
|
|
Enable/disable inetd mode. Default: "0" (disabled).
|
|
.It Fl mime_types Ar list
|
|
Additional to builtin mime types, in form "EXTENSION1=TYPE1,EXTENSION2=TYPE2".
|
|
.It Fl ports Ar port_list
|
|
Comma-separated list of ports to listen on. If the port is SSL, a letter 's'
|
|
must be appeneded, for example, "80,443s" will open port 80 and port 443,
|
|
and connections on port 443 will be SSL-ed. Default: 80
|
|
.It Fl protect Ar list
|
|
Comma separated list of URI=PATH pairs, specifying that given URIs
|
|
must the protected with respected password files. Default: not set.
|
|
.It Fl root Ar directory
|
|
Location of the WWW root directory. Default: working directory from which
|
|
.Nm
|
|
has been started.
|
|
.It Fl ssi_ext Ar list
|
|
Comma separated list of SSI extensions. Default: "shtml,shtm".
|
|
.It Fl ssl_cert Ar pem_file
|
|
Location of SSL certificate file. Default: not set.
|
|
.It Fl uid Ar login
|
|
Switch to given user after startup. Default: not set.
|
|
.El
|
|
.Pp
|
|
.Sh EMBEDDING
|
|
.Nm
|
|
can be built as a library to embed web server functionality
|
|
into C/C++ application. The API functions are declared in a header
|
|
file
|
|
.Pa shttpd.h .
|
|
Please refer to the source package for a header file and the examples.
|
|
.Pp
|
|
.Sh EXAMPLES
|
|
.Bl -tag -width indent
|
|
.It Nm Fl root Ar /var/www Fl ports Ar 8080,8043s Fl ssl_cert Ar /etc/cert.pem Fl aliases Ar /aa=/tmp,/bb=/etc
|
|
Start listening on port 8080 for HTTP, and 8043 for HTTPS connections.
|
|
Use /etc/cert.pem as SSL certificate file. Web root is /var/www. In addition,
|
|
map directory /tmp to URI /aa, directory /etc to URI /bb.
|
|
.It Nm Fl acl Ar -0.0.0.0/0,+10.0.0.0/8,+1.2.3.4
|
|
Deny connections from everywhere, allow only IP address 1.2.3.4 and
|
|
all IP addresses from 10.0.0.0/8 subnet to connect.
|
|
.It Nm Fl ports Ar 8080 Fl cfg_uri Ar /ctl Fl protect Ar /ctl=/tmp/passwords.txt
|
|
Start listening on port 8080, create an administrative URI "/ctl" where
|
|
options may be changed at runtime, and protect that URI with authorization.
|
|
.It http stream tcp nowait nobody /bin/shttpd shttpd -inetd 1 -root /var/www
|
|
This line in
|
|
.Pa /etc/inetd.conf
|
|
makes
|
|
.Nm
|
|
run by
|
|
.Xr inetd 8
|
|
daemon.
|
|
.El
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr inetd 8 .
|
|
.Sh COPYRIGHT
|
|
.Nm
|
|
is licensed under the terms of beerware license.
|
|
.Sh AUTHOR
|
|
.An Sergey Lyubka Aq valenok@gmail.com .
|