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