mirror of
https://github.com/cesanta/mongoose.git
synced 2024-12-27 23:21:04 +08:00
185 lines
7.1 KiB
Groff
185 lines
7.1 KiB
Groff
.\" Process this file with
|
|
.\" groff -man -Tascii mongoose.1
|
|
.\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $
|
|
.Dd Dec 1, 2008
|
|
.Dt mongoose 1
|
|
.Sh NAME
|
|
.Nm mongoose
|
|
.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.
|
|
.Pp
|
|
.Nm
|
|
does not detach from terminal, and uses current working directory
|
|
as the web root, unless
|
|
.Fl root
|
|
option is specified.
|
|
.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
|
|
.Dq mongoose -ssl_cert cert.pem -ports 80,443s .
|
|
.Pp
|
|
Options may be specified in any order, with one exception: if SSL listening
|
|
port is specified in the -ports option, then -ssl_cert option must be set
|
|
before -ports option.
|
|
.Pp
|
|
Unlike other web servers,
|
|
.Nm
|
|
does not expect CGI scripts to be put in a special directory. CGI scripts may
|
|
be anywhere. CGI files are recognized by the file extension.
|
|
.Pp
|
|
SSI files are also recognized by extension. Unknown SSI directives are silently
|
|
ignored. Currently, two SSI directives supported, "include" and "exec". For the
|
|
"include" directive, included file name can be specified in three different
|
|
ways. Below is the summary of supported SSI directives:
|
|
.Bl -bullet
|
|
.It
|
|
<!--#exec "shell command"--> Execute shell command.
|
|
.It
|
|
<!--#include "path"--> File path must be relative to the current document.
|
|
.It
|
|
<!--#include virtual="path"--> File path must be relative to the document root.
|
|
.It
|
|
<!--#include file="path"--> File path must be the absolute path.
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
can use the configuration file. By default, it is "mongoose.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 leading dashes for option names 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. On each request, full list is traversed, and
|
|
last match wins. Default: not set, allow all.
|
|
.It Fl admin_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 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 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 yes|no
|
|
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 idle_time Ar num_seconds
|
|
Number of seconds worker thread waits for some work before exit. Default: 10
|
|
.It Fl index_files Ar list
|
|
Comma-separated list of files to be treated as directory index files.
|
|
Default: index.html,index.htm,index.cgi
|
|
.It Fl max_threads Ar number
|
|
Maximum number of worker threads to start. Default: 100
|
|
.It Fl mime_types Ar list
|
|
Additional to builtin mime types, in form
|
|
"extension1=type1,extension2=type2,...". Extension must include dot.
|
|
.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, "-ports 80,443s" will open port 80 and port 443,
|
|
and connections on port 443 will be SSL-ed. It is possible to specify an
|
|
IP address to bind to. In this case, an IP address and a colon must be
|
|
prepended to the port number, for example, "-ports 127.0.0.1:8080". Note that
|
|
if SSL listening port is requested, then
|
|
.Fl ssl_cert
|
|
option must specified BEFORE
|
|
.Fl ports
|
|
option. Default: 8080
|
|
.It Fl protect Ar list
|
|
Comma separated list of URI=PATH pairs, specifying that given URIs
|
|
must be 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
|
|
was designed to be embeddable into C/C++ applications. Since the
|
|
source code is contained in single C file, it is fairly easy to embed it,
|
|
and to follow the updates. Please refer to http://code.google.com/p/mongoose
|
|
for details.
|
|
.Pp
|
|
.Sh EXAMPLES
|
|
.Bl -tag -width indent
|
|
.It Nm Fl root Ar /var/www Fl ssl_cert Ar /etc/cert.pem Fl ports Ar 8080,8043s 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 admin_uri Ar /ctl Fl protect Ar /ctl=/tmp/passwords.txt
|
|
Create an administrative URI "/ctl" where
|
|
options may be changed at runtime, and protect that URI with authorization.
|
|
.El
|
|
.Pp
|
|
.Sh COPYRIGHT
|
|
.Nm
|
|
is licensed under the terms of the MIT license.
|
|
.Sh AUTHOR
|
|
.An Sergey Lyubka Aq valenok@gmail.com .
|