1# Mongoose Configuration Options
2
3### access\_control\_list
4An Access Control List (ACL) allows restrictions to be put on the list of IP
5addresses which have access to the web server. In the case of the Mongoose
6web server, the ACL is a comma separated list of IP subnets, where each
7subnet is prepended by either a `-` or a `+` sign. A plus sign means allow,
8where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
9this means to deny only that single IP address.
10
11Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
12all accesses. On each request the full list is traversed, and
13the last match wins. Example: `$ mongoose -access_control_list -0.0.0.0/0,+192.168/16` to deny all acccesses except those from `192.168/16` subnet. Note that if the option is set, then all accesses are forbidden
14by default. Thus in a previous example, `-0.0.0.0` part is not necessary.
15For example, `$mongoose access_control_list +10.0.0.0/8`
16means disallow all, allow subnet 10/8 only.
17
18To learn more about subnet masks, see the
19[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)
20
21Default: not set, all accesses are allowed.
22
23### access\_log\_file
24Path to a file for access logs. Either full path, or relative to the
25mongoose executable. Default: not set, no query logging is done.
26
27### auth_domain
28Authorization realm used in `.htpasswd` authorization. Default: `mydomain.com`
29
30### cgi_interpreter
31Path to an executable to be used use as an interpreter for __all__ CGI scripts
32regardless script extension.  Default: not set, Mongoose looks at
33[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\).
34
35For example, if both PHP and perl CGIs are used, then
36`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
37respective CGI scripts. Note that paths should be either full file paths,
38or file paths relative to the directory where mongoose executable is located.
39
40If all CGIs use the same interpreter, for example they are all PHP, then
41`cgi_interpreter` option can be set to the path to `php-cgi.exe` executable and
42shebang line in the CGI scripts can be omitted.
43**Note**: PHP scripts must use `php-cgi.exe`, not `php.exe`.
44
45### cgi_pattern
46All files that match `cgi_pattern` are treated as CGI files. Default pattern
47allows CGI files be anywhere. To restrict CGIs to a certain directory,
48use `/path/to/cgi-bin/**.cgi` as a pattern. Note that **full file path** is
49matched against the pattern, not the URI.
50
51When Mongoose starts CGI program, it creates new environment for it (in
52contrast, usually child program inherits the environment from parent). Several
53environment variables however are inherited from Mongoose's environment,
54they are: `PATH`, `TMP`, `TEMP`, `TMPDIR`, `PERLLIB`, `MONGOOSE_CGI`. On UNIX
55it is also `LD_LIBRARY_PATH`. On Windows it is also `COMSPEC`, `SYSTEMROOT`,
56`SystemDrive`, `ProgramFiles`, `ProgramFiles(x86)`, `CommonProgramFiles(x86)`.
57
58Default: `**.cgi$|**.pl$|**.php$`
59
60### dav\_auth\_file
61Authentication file for WebDAV mutation requests: `PUT`, `DELETE`, `MKCOL`.
62The format of that file is the same as for the `.htpasswd` file
63used for digest authentication. It can be created and managed by
64`mongoose -A` command. Default: not set, WebDAV mutations are disallowed.
65
66### document_root
67A directory to serve. Default: current working directory.
68
69### enable\_directory\_listing
70Enable directory listing, either `yes` or `no`. Default: `yes`.
71
72### enable\_proxy
73Enable proxy functionality, either `yes` or `no`. If set to `yes`, then
74browsers can be configured to use Mongoose as a proxy. Default: `no`.
75
76
77### extra\_mime\_types
78Extra mime types to recognize, in form `extension1=type1,extension2=type2,...`.
79Extension must include dot.  Example:
80`mongoose -extra_mime_types .cpp=plain/text,.java=plain/text`. Default: not set.
81
82
83### global\_auth\_file
84Path to a global passwords file, either full path or relative to the mongoose
85executable. If set, per-directory `.htpasswd` files are ignored,
86and all requests are authorised against that file. Use `mongoose -A` to
87manage passwords, or third party utilities like
88[htpasswd-generator](http://www.askapache.com/online-tools/htpasswd-generator).
89Default: not set, per-directory `.htpasswd` files are respected.
90
91### hide\_files\_patterns
92A pattern for the files to hide. Files that match the pattern will not
93show up in directory listing and return `404 Not Found` if requested. Pattern
94must be for a file name only, not including directory name, e.g.
95`mongoose -hide_files_patterns secret.txt|even_more_secret.txt`. Default:
96not set.
97
98### index_files
99Comma-separated list of files to be treated as directory index
100files. Default: `index.html,index.htm,index.cgi,index.shtml,index.php`
101
102### listening_port
103Port to listen on. Port could be prepended by the specific IP address to bind
104to, e.g. `mongoose -listening_port 127.0.0.1:8080`. Otherwise Mongoose
105will bind to all addresses. To enable SSL, build Mongoose with
106`-DNS_ENABLE_SSL` compilation option, and specify `listening_port` as
107`ssl://PORT:SSL_CERTIFICATE.PEM`. Example SSL listener:
108`mongoose -listening_port ssl://8043:ssl_cert.pem`. Note that PEM file should
109be in PEM format, and must have both certificate and private key in it,
110concatenated together. More than one listening port can be specified,
111separated by comma,
112for example `mongoose -listening_port 8080,8000`. Default: 8080.
113
114### run\_as\_user
115Switch to given user credentials after startup. UNIX-only. This option is
116required when mongoose needs to bind on privileged port on UNIX, e.g.
117
118    $ sudo mongoose -listening_port 80 -run_as_user nobody
119
120Default: not set.
121
122### url\_rewrites
123Comma-separated list of URL rewrites in the form of
124`uri_pattern=file_or_directory_path`. When Mongoose receives the request,
125it constructs the file name to show by combining `document_root` and the URI.
126However, if the rewrite option is used and `uri_pattern` matches the
127requested URI, then `document_root` is ignored. Instead,
128`file_or_directory_path` is used, which should be a full path name or
129a path relative to the web server's current working directory. Note that
130`uri_pattern`, as all mongoose patterns, is a prefix pattern. If `uri_pattern`
131is a number, then it is treated as HTTP error code, and `file_or_directory_path`
132should be an URI to redirect to. Mongoose will issue `302` temporary redirect
133to the specified URI with following parameters:
134`?code=HTTP_ERROR_CODE&orig_uri=ORIGINAL_URI&query_string=QUERY_STRING`.
135
136If `uri_pattern` starts with `@` symbol, then Mongoose compares
137it with the `HOST` header of the request. If they are equal, Mongoose sets
138document root to `file_or_directory_path`, implementing virtual hosts support.
139
140Examples:
141
142    # Redirect all accesses to `.doc` files to a special script
143    mongoose -url_rewrites **.doc$=/path/to/cgi-bin/handle_doc.cgi
144
145    # Implement user home directories support
146    mongoose -url_rewrites /~joe/=/home/joe/,/~bill=/home/bill/
147
148    # Redirect 404 errors to a specific error page
149    mongoose -url_rewrites 404=/cgi-bin/error.cgi
150
151    # Virtual hosts example: serve foo.com domain from different directory
152    mongoose -url_rewrites @foo.com=/var/www/foo.com
153
154Default: not set.
155