|
@@ -1,180 +1,142 @@
|
|
|
.\" 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
|
|
|
+.Dd Aug 31, 2010
|
|
|
.Dt mongoose 1
|
|
|
.Sh NAME
|
|
|
.Nm mongoose
|
|
|
.Nd lightweight web server
|
|
|
.Sh SYNOPSIS
|
|
|
.Nm
|
|
|
-.Op Ar options
|
|
|
.Op Ar config_file
|
|
|
.Nm
|
|
|
+.Op Ar OPTIONS
|
|
|
+.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.
|
|
|
+is small, fast and easy to use web server with CGI, SSL, MD5 authorization,
|
|
|
+and basic SSI support.
|
|
|
.Pp
|
|
|
.Nm
|
|
|
does not detach from terminal, and uses current working directory
|
|
|
as the web root, unless
|
|
|
-.Fl root
|
|
|
+.Fl r
|
|
|
option is specified.
|
|
|
-.Pp
|
|
|
-It is possible to specify multiple ports to listen on. For example, to
|
|
|
-make
|
|
|
+It is possible to specify multiple ports to listen on. For example, to make
|
|
|
+mongoose listen on HTTP port 80 and HTTPS port 443, one should start it as:
|
|
|
.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.
|
|
|
+.Fl s Ar cert.pem Fl p Ar 80,443s
|
|
|
.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
|
|
|
+does not expect CGI scripts to be put in a special directory. CGI scripts can
|
|
|
+be anywhere. CGI (and SSI) files are recognized by the file extension.
|
|
|
.Pp
|
|
|
+If no arguments are given,
|
|
|
.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.
|
|
|
+searches for a configuration file called "mongoose.conf" in the same directory
|
|
|
+where mongoose binary is located. Alternatively, a file name could be
|
|
|
+specified in the command line. Format of the configuration file is the same
|
|
|
+as for the command line options except that each option must be specified
|
|
|
+on a separate line, leading dashes for option names must be omitted.
|
|
|
+Lines beginning with '#' and empty lines are 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
|
|
|
+with any text editor. Functionality is 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],...
|
|
|
+.It Fl C Ar cgi_extensions
|
|
|
+Comma-separated list of CGI extensions. All files having these extensions
|
|
|
+are treated as CGI scripts. Default: ".cgi,.pl,.php"
|
|
|
+.It Fl E Ar cgi_environment
|
|
|
+Extra environment variables to be passed 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: ""
|
|
|
+.It Fl G Ar put_delete_passwords_file
|
|
|
+PUT and DELETE passwords file. This must be specified if PUT or
|
|
|
+DELETE methods are used. Default: ""
|
|
|
+.It Fl I Ar cgi_interpreter
|
|
|
+Use
|
|
|
+.Ar cgi_interpreter
|
|
|
+as a CGI interpreter for all CGI scripts regardless script extension.
|
|
|
+Default: "". Mongoose decides which interpreter to use by looking at
|
|
|
+the first line of a CGI script.
|
|
|
+.It Fl P Ar protect_uri
|
|
|
+Comma separated list of URI=PATH pairs, specifying that given URIs
|
|
|
+must be protected with respected password files. Default: ""
|
|
|
+.It Fl R Ar authentication_domain
|
|
|
+Authorization realm. Default: "mydomain.com"
|
|
|
+.It Fl S Ar ssi_extensions
|
|
|
+Comma separated list of SSI extensions. Unknown SSI directives are silently
|
|
|
+ignored. Currently, two SSI directives supported, "include" and "exec".
|
|
|
+Default: "shtml,shtm"
|
|
|
+.It Fl a Ar access_log_file
|
|
|
+Access log file. Default: "", no logging is done.
|
|
|
+.It Fl d Ar enable_directory_listing
|
|
|
+Enable/disable directory listing. Default: "yes"
|
|
|
+.It Fl e Ar error_log_file
|
|
|
+Error log file. Default: "", no errors are logged.
|
|
|
+.It Fl g Ar global_passwords_file
|
|
|
+Location of a global passwords file. If set, per-directory .htpasswd files are
|
|
|
+ignored, and all requests must be authorised against that file. Default: ""
|
|
|
+.It Fl i Ar index_files
|
|
|
+Comma-separated list of files to be treated as directory index files.
|
|
|
+Default: "index.html,index.htm,index.cgi"
|
|
|
+.It Fl l Ar access_control_list
|
|
|
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
|
|
|
+last match wins. Default setting is to allow all. For example, to allow only
|
|
|
+192.168/16 subnet to connect, run "mongoose -0.0.0.0/0,+192.168/16".
|
|
|
+Default: ""
|
|
|
+.It Fl m Ar extra_mime_types
|
|
|
+Extra mime types to recognize, in form
|
|
|
"extension1=type1,extension2=type2,...". Extension must include dot.
|
|
|
-.It Fl ports Ar port_list
|
|
|
+Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: ""
|
|
|
+.It Fl p Ar listening_ports
|
|
|
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,
|
|
|
+must be appeneded, for example, "-p 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.
|
|
|
+prepended to the port number. For example, to bind to a loopback interface
|
|
|
+on port 80 and to all interfaces on HTTPS port 443, use
|
|
|
+"mongoose -p 127.0.0.1:80,443s". Default: "8080"
|
|
|
+.It Fl r Ar document_root
|
|
|
+Location of the WWW root directory. A comma separated list of
|
|
|
+URI_PREFIX=DIRECTORY
|
|
|
+pairs could be appended to it, allowing Mongoose to serve from multiple
|
|
|
+directories. For example, "mongoose -p /var/www,/config=/etc,/garbage=/tmp".
|
|
|
+Default: "."
|
|
|
+.It Fl s Ar ssl_certificate
|
|
|
+Location of SSL certificate file. Default: ""
|
|
|
+.It Fl t Ar num_threads
|
|
|
+Number of worker threads to start. Default: "10"
|
|
|
+.It Fl u Ar run_as_user
|
|
|
+Switch to given user's credentials after startup. Default: ""
|
|
|
.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
|
|
|
+source code is contained in single C file, it is fairly easy to embed it
|
|
|
+and 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
|
|
|
+.It Nm Fl r Ar /var/www,/aa=/tmp,/bb=/etc Fl s Ar /etc/cert.pem Fl p Ar 8080,8043s
|
|
|
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
|
|
|
+.It Nm Fl l 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
|