1 | .\" Process this file with |
---|
2 | .\" groff -man -Tascii mongoose.1 |
---|
3 | .\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $ |
---|
4 | .Dd Aug 31, 2010 |
---|
5 | .Dt mongoose 1 |
---|
6 | .Sh NAME |
---|
7 | .Nm mongoose |
---|
8 | .Nd lightweight web server |
---|
9 | .Sh SYNOPSIS |
---|
10 | .Nm |
---|
11 | .Op Ar config_file |
---|
12 | .Op Ar OPTIONS |
---|
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, MD5 authorization, |
---|
18 | and basic SSI support. |
---|
19 | .Pp |
---|
20 | .Nm |
---|
21 | does not detach from terminal, and uses current working directory |
---|
22 | as the web root, unless |
---|
23 | .Fl r |
---|
24 | option is specified. |
---|
25 | It is possible to specify multiple ports to listen on. For example, to make |
---|
26 | mongoose listen on HTTP port 80 and HTTPS port 443, one should start it as: |
---|
27 | .Nm |
---|
28 | .Fl s Ar cert.pem Fl p Ar 80,443s |
---|
29 | .Pp |
---|
30 | Unlike other web servers, |
---|
31 | .Nm |
---|
32 | does not require CGI scripts be put in a special directory. CGI scripts can |
---|
33 | be anywhere. CGI (and SSI) files are recognized by the file name pattern. |
---|
34 | .Nm |
---|
35 | uses shell-like glob patterns with the following syntax: |
---|
36 | .Bl -tag -compact -width indent |
---|
37 | .It ** |
---|
38 | Matches everything |
---|
39 | .It * |
---|
40 | Matches everything but slash character, '/' |
---|
41 | .It ? |
---|
42 | Matches any character |
---|
43 | .It $ |
---|
44 | Matches the end of the string |
---|
45 | .It | |
---|
46 | Matches if pattern on the left side or the right side matches. Pattern on the |
---|
47 | left side is matched first |
---|
48 | .El |
---|
49 | All other characters in the pattern match themselves. |
---|
50 | .Pp |
---|
51 | If no arguments are given, |
---|
52 | .Nm |
---|
53 | searches for a configuration file called "mongoose.conf" in the same directory |
---|
54 | where mongoose binary is located. Alternatively, a file name could be |
---|
55 | specified in the command line. Format of the configuration file is the same |
---|
56 | as for the command line options except that each option must be specified |
---|
57 | on a separate line, leading dashes for option names must be omitted. |
---|
58 | Lines beginning with '#' and empty lines are ignored. |
---|
59 | .Pp |
---|
60 | .Sh OPTIONS |
---|
61 | .Bl -tag -width indent |
---|
62 | .It Fl A Ar htpasswd_file domain_name user_name password |
---|
63 | Add/edit user's password in the passwords file. Deleting users can be done |
---|
64 | with any text editor. Functionality is similar to Apache's |
---|
65 | .Ic htdigest |
---|
66 | utility. |
---|
67 | .It Fl C Ar cgi_pattern |
---|
68 | All files that fully match cgi_pattern are treated as CGI. |
---|
69 | Default pattern allows CGI files be |
---|
70 | anywhere. To restrict CGIs to certain directory, use e.g. "-C /cgi-bin/**.cgi". |
---|
71 | Default: "**.cgi$|**.pl$|**.php$" |
---|
72 | .It Fl E Ar cgi_environment |
---|
73 | Extra environment variables to be passed to the CGI script in addition to |
---|
74 | standard ones. The list must be comma-separated list of X=Y pairs, like this: |
---|
75 | "VARIABLE1=VALUE1,VARIABLE2=VALUE2". Default: "" |
---|
76 | .It Fl G Ar put_delete_passwords_file |
---|
77 | PUT and DELETE passwords file. This must be specified if PUT or |
---|
78 | DELETE methods are used. Default: "" |
---|
79 | .It Fl I Ar cgi_interpreter |
---|
80 | Use |
---|
81 | .Ar cgi_interpreter |
---|
82 | as a CGI interpreter for all CGI scripts regardless script extension. |
---|
83 | Mongoose decides which interpreter to use by looking at |
---|
84 | the first line of a CGI script. Default: "". |
---|
85 | .It Fl M Ar max_request_size |
---|
86 | Maximum HTTP request size in bytes. Default: "16384" |
---|
87 | .It Fl P Ar protect_uri |
---|
88 | Comma separated list of URI=PATH pairs, specifying that given URIs |
---|
89 | must be protected with respected password files. Default: "" |
---|
90 | .It Fl R Ar authentication_domain |
---|
91 | Authorization realm. Default: "mydomain.com" |
---|
92 | .It Fl S Ar ssi_pattern |
---|
93 | All files that fully match ssi_pattern are treated as SSI. |
---|
94 | Unknown SSI directives are silently ignored. Currently, two SSI directives |
---|
95 | are supported, "include" and "exec". Default: "**.shtml$|**.shtm$" |
---|
96 | .It Fl a Ar access_log_file |
---|
97 | Access log file. Default: "", no logging is done. |
---|
98 | .It Fl d Ar enable_directory_listing |
---|
99 | Enable/disable directory listing. Default: "yes" |
---|
100 | .It Fl e Ar error_log_file |
---|
101 | Error log file. Default: "", no errors are logged. |
---|
102 | .It Fl g Ar global_passwords_file |
---|
103 | Location of a global passwords file. If set, per-directory .htpasswd files are |
---|
104 | ignored, and all requests must be authorised against that file. Default: "" |
---|
105 | .It Fl i Ar index_files |
---|
106 | Comma-separated list of files to be treated as directory index files. |
---|
107 | Default: "index.html,index.htm,index.cgi" |
---|
108 | .It Fl l Ar access_control_list |
---|
109 | Specify access control list (ACL). ACL is a comma separated list |
---|
110 | of IP subnets, each subnet is prepended by '-' or '+' sign. Plus means allow, |
---|
111 | minus means deny. If subnet mask is |
---|
112 | omitted, like "-1.2.3.4", then it means single IP address. Mask may vary |
---|
113 | from 0 to 32 inclusive. On each request, full list is traversed, and |
---|
114 | last match wins. Default setting is to allow all. For example, to allow only |
---|
115 | 192.168/16 subnet to connect, run "mongoose -0.0.0.0/0,+192.168/16". |
---|
116 | Default: "" |
---|
117 | .It Fl m Ar extra_mime_types |
---|
118 | Extra mime types to recognize, in form |
---|
119 | "extension1=type1,extension2=type2,...". Extension must include dot. |
---|
120 | Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: "" |
---|
121 | .It Fl p Ar listening_ports |
---|
122 | Comma-separated list of ports to listen on. If the port is SSL, a letter 's' |
---|
123 | must be appeneded, for example, "-p 80,443s" will open port 80 and port 443, |
---|
124 | and connections on port 443 will be SSL-ed. It is possible to specify an |
---|
125 | IP address to bind to. In this case, an IP address and a colon must be |
---|
126 | prepended to the port number. For example, to bind to a loopback interface |
---|
127 | on port 80 and to all interfaces on HTTPS port 443, use |
---|
128 | "mongoose -p 127.0.0.1:80,443s". Default: "8080" |
---|
129 | .It Fl r Ar document_root |
---|
130 | Location of the WWW root directory. Default: "." |
---|
131 | .It Fl s Ar ssl_certificate |
---|
132 | Location of SSL certificate file. Default: "" |
---|
133 | .It Fl t Ar num_threads |
---|
134 | Number of worker threads to start. Default: "10" |
---|
135 | .It Fl u Ar run_as_user |
---|
136 | Switch to given user's credentials after startup. Default: "" |
---|
137 | .It Fl w Ar url_rewrite_patterns |
---|
138 | Comma-separated list of URL rewrites in the form of |
---|
139 | "pattern=substitution,..." If the "pattern" matches some prefix |
---|
140 | of the requested URL, then matched prefix gets substituted with "substitution". |
---|
141 | For example, "-w /config=/etc,**.doc|**.rtf=/path/to/cgi-bin/handle_doc.cgi" |
---|
142 | will serve all URLs that start with "/config" from the "/etc" directory, and |
---|
143 | call handle_doc.cgi script for .doc and .rtf file requests. If some pattern |
---|
144 | matches, no further matching/substitution is performed |
---|
145 | (first matching pattern wins). Use full paths in substitutions. Default: "" |
---|
146 | .It Fl x Ar thread_stack_size |
---|
147 | Use the given amount of stack for each thread. Default: "" |
---|
148 | .It Fl y Ar thread_priority |
---|
149 | Use the given priority for all posix threads. If this option is used without the |
---|
150 | thread_policy option, the systems default scheduling policy will be used for the |
---|
151 | threads instead of inheriting the policy of the creating thread. Default: "" |
---|
152 | .It Fl z Ar thread_policy |
---|
153 | Select the posix scheduling policy for the threads. Possible Values are 's' for |
---|
154 | sporadic (not on all systems available), 'r' for round robin, 'f' for fifo or |
---|
155 | 'o' for other scheduling strategie. If this option is used without the |
---|
156 | thread_priority option, the systems default priority will be used for the |
---|
157 | threads instead of inheriting the priority of the creating thread. Default: "" |
---|
158 | .El |
---|
159 | .Pp |
---|
160 | .Sh EMBEDDING |
---|
161 | .Nm |
---|
162 | was designed to be embeddable into C/C++ applications. Since the |
---|
163 | source code is contained in single C file, it is fairly easy to embed it |
---|
164 | and follow the updates. Please refer to http://code.google.com/p/mongoose |
---|
165 | for details. |
---|
166 | .Pp |
---|
167 | .Sh EXAMPLES |
---|
168 | .Bl -tag -width indent |
---|
169 | .It Nm Fl r Ar /var/www Fl s Ar /etc/cert.pem Fl p Ar 8080,8043s |
---|
170 | Start serving files from /var/www. Listen on port 8080 for HTTP, and 8043 |
---|
171 | for HTTPS connections. Use /etc/cert.pem as SSL certificate file. |
---|
172 | .It Nm Fl l Ar -0.0.0.0/0,+10.0.0.0/8,+1.2.3.4 |
---|
173 | Deny connections from everywhere, allow only IP address 1.2.3.4 and |
---|
174 | all IP addresses from 10.0.0.0/8 subnet to connect. |
---|
175 | .It Nm Fl w Ar **=/usr/bin/script.cgi |
---|
176 | Invoke /usr/bin/script.cgi for every incoming request, regardless of the URL. |
---|
177 | .El |
---|
178 | .Pp |
---|
179 | .Sh COPYRIGHT |
---|
180 | .Nm |
---|
181 | is licensed under the terms of the MIT license. |
---|
182 | .Sh AUTHOR |
---|
183 | .An Sergey Lyubka Aq valenok@gmail.com . |
---|