diff options
Diffstat (limited to 'cpukit/mghttpd/mongoose.1')
| -rw-r--r-- | cpukit/mghttpd/mongoose.1 | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/cpukit/mghttpd/mongoose.1 b/cpukit/mghttpd/mongoose.1 new file mode 100644 index 0000000000..e62227a4b4 --- /dev/null +++ b/cpukit/mghttpd/mongoose.1 @@ -0,0 +1,181 @@ +.\" Process this file with +.\" groff -man -Tascii mongoose.1 +.\" $Id$ +.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 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 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 +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 . |