source: rtems/cpukit/mghttpd/mongoose.1 @ b45feba

4.104.115
Last change on this file since b45feba was b45feba, checked in by Ralf Corsepius <ralf.corsepius@…>, on Nov 17, 2009 at 4:53:48 PM

2009-11-17 Ralf Corsépius <ralf.corsepius@…>

  • Property mode set to 100644
File size: 6.9 KB
Line 
1.\" Process this file with
2.\" groff -man -Tascii mongoose.1
3.\" $Id$
4.Dd Dec 1, 2008
5.Dt mongoose 1
6.Sh NAME
7.Nm mongoose
8.Nd lightweight web server
9.Sh SYNOPSIS
10.Nm
11.Op Ar options
12.Op Ar config_file
13.Nm
14.Fl A Ar htpasswd_file domain_name user_name password
15.Sh DESCRIPTION
16.Nm
17is small, fast and easy to use web server with CGI, SSL, Digest Authorization
18support.
19.Pp
20.Nm
21does not detach from terminal, and uses current working directory
22as the web root, unless
23.Fl root
24option is specified.
25.Pp
26It is possible to specify multiple ports to listen on. For example, to
27make
28.Nm
29listen on HTTP port 80 and HTTPS port 443, one should start it as
30.Dq mongoose -ssl_cert cert.pem -ports 80,443s .
31.Pp
32Options may be specified in any order, with one exception: if SSL listening
33port is specified in the -ports option, then -ssl_cert option must be set
34before -ports option.
35.Pp
36Unlike other web servers,
37.Nm
38does not expect CGI scripts to be put in a special directory. CGI scripts may
39be anywhere. CGI files are recognized by the file extension.
40.Pp
41SSI files are also recognized by extension. Unknown SSI directives are silently
42ignored. Currently, two SSI directives supported, "include" and "exec". For the
43"include" directive, included file name can be specified in three different
44ways. Below is the summary of supported SSI directives:
45.Bl -bullet
46.It
47<!--#exec "shell command"--> Execute shell command.
48.It
49<!--#include "path"--> File path must be relative to the current document.
50.It
51<!--#include virtual="path"--> File path must be relative to the document root.
52.It
53<!--#include file="path"--> File path must be the absolute path.
54.El
55.Pp
56.Nm
57can use the configuration file. By default, it is "mongoose.conf", and if it
58is present in the same directory where
59.Nm
60lives, the command line options are read from it. Alternatively, the
61configuration file may be specified as a last argument. The format of the
62configuration file is exactly the same as for the command line options, the
63only difference is that the command line options must be specified on
64separate lines, and leading dashes for option names must be omitted.
65Lines beginning with '#' are regarded as comments and ignored.
66.Pp
67.Sh OPTIONS
68.Bl -tag -width indent
69.It Fl A Ar htpasswd_file domain_name user_name password
70Add/edit user's password in the passwords file. Deleting users can be done
71with any text editor. Functionality similar to Apache's
72.Ic htdigest
73utility.
74.It Fl access_log Ar file
75Access log file. Default: not set, no logging is done.
76.It Fl acl Ar (+|-)x.x.x.x[/x],...
77Specify access control list (ACL). ACL is a comma separated list
78of IP subnets, each subnet is prepended by '-' or '+' sign. Plus means allow,
79minus means deny. If subnet mask is
80omitted, like "-1.2.3.4", then it means single IP address. Mask may vary
81from 0 to 32 inclusive. On each request, full list is traversed, and
82last match wins. Default: not set, allow all.
83.It Fl admin_uri Ar uri
84If set,
85.Nm
86creates special administrative URI where options may be changed at runtime.
87This URI probably wants to be password-protected, look at
88.Fl protect
89option, and in the EXAMPLES section on how to do it. Default: not set.
90.It Fl aliases Ar list
91This options gives an ability to serve the directories outside web root
92by sort of symbolic linking to certain URI. The
93.Ar list
94must be comma-separated list of URI=PATH pairs, like this:
95"/etc/=/my_etc,/tmp=/my_tmp". Default: not set.
96.It Fl auth_PUT Ar file
97PUT and DELETE passwords file. This must be specified if PUT or
98DELETE methods are used. Default: not set.
99.It Fl auth_gpass Ar file
100Location of global passwords file. When set, per-directory .htpasswd files are
101ignored, and all accessed must be authorised against global passwords file.
102Default: not set.
103.It Fl auth_realm Ar domain_name
104Authorization realm. Default: "mydomain.com".
105.It Fl cgi_env Ar list
106Pass environment variables to the CGI script in addition to standard ones.
107The list must be comma-separated list of X=Y pairs, like this:
108"VARIABLE1=VALUE1,VARIABLE2=VALUE2".  Default: not set.
109.It Fl cgi_ext Ar list
110Comma-separated list of CGI extensions.  All files having these extensions
111are treated as CGI scripts. Default: "cgi,pl,php"
112.It Fl cgi_interp Ar file
113Force
114.Ar file
115to be a CGI interpreter for all CGI scripts. By default this option is not
116set, and
117.Nm
118decides which interpreter to use by looking at the first line of CGI script.
119.It Fl dir_list Ar yes|no
120Enable/disable directory listing. Default: "1" (enabled).
121.It Fl error_log Ar file
122Error log file. Default: not set, no errors are logged.
123.It Fl idle_time Ar num_seconds
124Number of seconds worker thread waits for some work before exit. Default: 10
125.It Fl max_threads Ar number
126Maximum number of worker threads to start. Default: 100
127.It Fl mime_types Ar list
128Additional to builtin mime types, in form
129"extension1=type1,extension2=type2,...". Extension must include dot.
130.It Fl ports Ar port_list
131Comma-separated list of ports to listen on. If the port is SSL, a letter 's'
132must be appeneded, for example, "-ports 80,443s" will open port 80 and port 443,
133and connections on port 443 will be SSL-ed. It is possible to specify an
134IP address to bind to. In this case, an IP address and a colon must be
135prepended to the port number, for example, "-ports 127.0.0.1:8080". Note that
136if SSL listening port is requested, then
137.Fl ssl_cert
138option must specified BEFORE
139.Fl ports
140option. Default: 8080
141.It Fl protect Ar list
142Comma separated list of URI=PATH pairs, specifying that given URIs
143must the protected with respected password files. Default: not set.
144.It Fl root Ar directory
145Location of the WWW root directory. Default: working directory from which
146.Nm
147has been started.
148.It Fl ssi_ext Ar list
149Comma separated list of SSI extensions. Default: "shtml,shtm".
150.It Fl ssl_cert Ar pem_file
151Location of SSL certificate file. Default: not set.
152.It Fl uid Ar login
153Switch to given user after startup. Default: not set.
154.El
155.Pp
156.Sh EMBEDDING
157.Nm
158was designed to be embeddable into C/C++ applications. Since the
159source code is contained in single C file, it is fairly easy to embed it,
160and to follow the updates. Please refer to http://code.google.com/p/mongoose
161for details.
162.Pp
163.Sh EXAMPLES
164.Bl -tag -width indent
165.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
166Start listening on port 8080 for HTTP, and 8043 for HTTPS connections.
167Use /etc/cert.pem as SSL certificate file. Web root is /var/www. In addition,
168map directory /tmp to URI /aa, directory /etc to URI /bb.
169.It Nm Fl acl Ar -0.0.0.0/0,+10.0.0.0/8,+1.2.3.4
170Deny connections from everywhere, allow only IP address 1.2.3.4 and
171all IP addresses from 10.0.0.0/8 subnet to connect.
172.It Nm Fl admin_uri Ar /ctl Fl protect Ar /ctl=/tmp/passwords.txt
173Create an administrative URI "/ctl" where
174options may be changed at runtime, and protect that URI with authorization.
175.El
176.Pp
177.Sh COPYRIGHT
178.Nm
179is licensed under the terms of the MIT license.
180.Sh AUTHOR
181.An Sergey Lyubka Aq valenok@gmail.com .
Note: See TracBrowser for help on using the repository browser.