Options.md 7.06 KB
Newer Older
Sergey Lyubka's avatar
Sergey Lyubka committed
1 2
# Mongoose Configuration Options

Sergey Lyubka's avatar
Sergey Lyubka committed
3 4 5 6 7 8 9
### access\_control\_list
An Access Control List (ACL) allows restrictions to be put on the list of IP
addresses which have access to the web server. In the case of the Mongoose
web server, the ACL is a comma separated list of IP subnets, where each
subnet is prepended by either a `-` or a `+` sign. A plus sign means allow,
where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
this means to deny only that single IP address.
Sergey Lyubka's avatar
Sergey Lyubka committed
10

Sergey Lyubka's avatar
Sergey Lyubka committed
11 12
Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
all accesses. On each request the full list is traversed, and
13 14 15 16 17 18
the 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
by default. Thus in a previous example, `-0.0.0.0` part is not necessary.
For example, `$mongoose access_control_list +10.0.0.0/8`
means disallow all, allow subnet 10/8 only.

To learn more about subnet masks, see the
Sergey Lyubka's avatar
Sergey Lyubka committed
19 20 21 22 23 24 25 26 27 28
[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)

Default: not set, all accesses are allowed.

### access\_log\_file
Path to a file for access logs. Either full path, or relative to the
mongoose executable. Default: not set, no query logging is done.

### auth_domain
Authorization realm used in `.htpasswd` authorization. Default: `mydomain.com`
Sergey Lyubka's avatar
Sergey Lyubka committed
29 30

### cgi_interpreter
Sergey Lyubka's avatar
Sergey Lyubka committed
31 32
Path to an executable to be used use as an interpreter for __all__ CGI scripts
regardless script extension.  Default: not set, Mongoose looks at
Sergey Lyubka's avatar
Sergey Lyubka committed
33
[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\).
Sergey Lyubka's avatar
Sergey Lyubka committed
34 35 36 37

For example, if both PHP and perl CGIs are used, then
`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
respective CGI scripts. Note that paths should be either full file paths,
Sergey Lyubka's avatar
Sergey Lyubka committed
38
or file paths relative to the directory where mongoose executable is located.
Sergey Lyubka's avatar
Sergey Lyubka committed
39 40

If all CGIs use the same interpreter, for example they are all PHP, then
Sergey Lyubka's avatar
Sergey Lyubka committed
41
`cgi_interpreter` option can be set to the path to `php-cgi.exe` executable and
Sergey Lyubka's avatar
Sergey Lyubka committed
42
shebang line in the CGI scripts can be omitted.
Sergey Lyubka's avatar
Sergey Lyubka committed
43
**Note**: PHP scripts must use `php-cgi.exe`, not `php.exe`.
Sergey Lyubka's avatar
Sergey Lyubka committed
44

Sergey Lyubka's avatar
Sergey Lyubka committed
45 46 47
### cgi_pattern
All files that match `cgi_pattern` are treated as CGI files. Default pattern
allows CGI files be anywhere. To restrict CGIs to a certain directory,
Sergey Lyubka's avatar
Sergey Lyubka committed
48
use `/path/to/cgi-bin/**.cgi` as a pattern. Note that **full file path** is
49 50 51 52 53 54 55 56
matched against the pattern, not the URI.

When Mongoose starts CGI program, it creates new environment for it (in
contrast, usually child program inherits the environment from parent). Several
environment variables however are inherited from Mongoose's environment,
they are: `PATH`, `TMP`, `TEMP`, `TMPDIR`, `PERLLIB`, `MONGOOSE_CGI`. On UNIX
it is also `LD_LIBRARY_PATH`. On Windows it is also `COMSPEC`, `SYSTEMROOT`,
`SystemDrive`, `ProgramFiles`, `ProgramFiles(x86)`, `CommonProgramFiles(x86)`.
Sergey Lyubka's avatar
Sergey Lyubka committed
57

Sergey Lyubka's avatar
Sergey Lyubka committed
58
Default: `**.cgi$|**.pl$|**.php$`
Sergey Lyubka's avatar
Sergey Lyubka committed
59

Sergey Lyubka's avatar
Sergey Lyubka committed
60 61 62 63 64
### dav\_auth\_file
Authentication file for WebDAV mutation requests: `PUT`, `DELETE`, `MKCOL`.
The format of that file is the same as for the `.htpasswd` file
used for digest authentication. It can be created and managed by
`mongoose -A` command. Default: not set, WebDAV mutations are disallowed.
Sergey Lyubka's avatar
Sergey Lyubka committed
65

Sergey Lyubka's avatar
Sergey Lyubka committed
66 67
### document_root
A directory to serve. Default: current working directory.
Sergey Lyubka's avatar
Sergey Lyubka committed
68

Sergey Lyubka's avatar
Sergey Lyubka committed
69 70
### enable\_directory\_listing
Enable directory listing, either `yes` or `no`. Default: `yes`.
Sergey Lyubka's avatar
Sergey Lyubka committed
71

Sergey Lyubka's avatar
Sergey Lyubka committed
72 73 74 75 76
### enable\_proxy
Enable proxy functionality, either `yes` or `no`. If set to `yes`, then
browsers can be configured to use Mongoose as a proxy. Default: `no`.


Sergey Lyubka's avatar
Sergey Lyubka committed
77 78 79 80
### extra\_mime\_types
Extra mime types to recognize, in form `extension1=type1,extension2=type2,...`.
Extension must include dot.  Example:
`mongoose -extra_mime_types .cpp=plain/text,.java=plain/text`. Default: not set.
Sergey Lyubka's avatar
Sergey Lyubka committed
81 82 83


### global\_auth\_file
Sergey Lyubka's avatar
Sergey Lyubka committed
84 85 86 87 88 89
Path to a global passwords file, either full path or relative to the mongoose
executable. If set, per-directory `.htpasswd` files are ignored,
and all requests are authorised against that file. Use `mongoose -A` to
manage passwords, or third party utilities like
[htpasswd-generator](http://www.askapache.com/online-tools/htpasswd-generator).
Default: not set, per-directory `.htpasswd` files are respected.
Sergey Lyubka's avatar
Sergey Lyubka committed
90

Sergey Lyubka's avatar
Sergey Lyubka committed
91 92 93 94 95 96
### hide\_files\_patterns
A pattern for the files to hide. Files that match the pattern will not
show up in directory listing and return `404 Not Found` if requested. Pattern
must be for a file name only, not including directory name, e.g.
`mongoose -hide_files_patterns secret.txt|even_more_secret.txt`. Default:
not set.
Sergey Lyubka's avatar
Sergey Lyubka committed
97

Sergey Lyubka's avatar
Sergey Lyubka committed
98
### index_files
Sergey Lyubka's avatar
Sergey Lyubka committed
99
Comma-separated list of files to be treated as directory index
Sergey Lyubka's avatar
Sergey Lyubka committed
100
files. Default: `index.html,index.htm,index.cgi,index.shtml,index.php`
Sergey Lyubka's avatar
Sergey Lyubka committed
101

Sergey Lyubka's avatar
Sergey Lyubka committed
102 103 104
### listening_port
Port to listen on. Port could be prepended by the specific IP address to bind
to, e.g. `mongoose -listening_port 127.0.0.1:8080`. Otherwise Mongoose
105 106 107 108 109 110 111 112
will bind to all addresses. To enable SSL, build Mongoose with
`-DNS_ENABLE_SSL` compilation option, and specify `listening_port` as
`ssl://PORT:SSL_CERTIFICATE.PEM`. Example SSL listener:
`mongoose -listening_port ssl://8043:ssl_cert.pem`. Note that PEM file should
be in PEM format, and must have both certificate and private key in it,
concatenated together. More than one listening port can be specified,
separated by comma,
for example `mongoose -listening_port 8080,8000`. Default: 8080.
Sergey Lyubka's avatar
Sergey Lyubka committed
113

Sergey Lyubka's avatar
Sergey Lyubka committed
114 115 116
### run\_as\_user
Switch to given user credentials after startup. UNIX-only. This option is
required when mongoose needs to bind on privileged port on UNIX, e.g.
Sergey Lyubka's avatar
Sergey Lyubka committed
117

Sergey Lyubka's avatar
Sergey Lyubka committed
118
    $ sudo mongoose -listening_port 80 -run_as_user nobody
Sergey Lyubka's avatar
Sergey Lyubka committed
119

Sergey Lyubka's avatar
Sergey Lyubka committed
120
Default: not set.
Sergey Lyubka's avatar
Sergey Lyubka committed
121

122
### url\_rewrites
Sergey Lyubka's avatar
Sergey Lyubka committed
123 124 125 126
Comma-separated list of URL rewrites in the form of
`uri_pattern=file_or_directory_path`. When Mongoose receives the request,
it constructs the file name to show by combining `document_root` and the URI.
However, if the rewrite option is used and `uri_pattern` matches the
Mark Eichin's avatar
Mark Eichin committed
127
requested URI, then `document_root` is ignored. Instead,
Sergey Lyubka's avatar
Sergey Lyubka committed
128 129
`file_or_directory_path` is used, which should be a full path name or
a path relative to the web server's current working directory. Note that
Mark Eichin's avatar
Mark Eichin committed
130
`uri_pattern`, as all mongoose patterns, is a prefix pattern. If `uri_pattern`
131 132
is a number, then it is treated as HTTP error code, and `file_or_directory_path`
should be an URI to redirect to. Mongoose will issue `302` temporary redirect
Sergey Lyubka's avatar
Sergey Lyubka committed
133 134 135 136 137 138
to the specified URI with following parameters:
`?code=HTTP_ERROR_CODE&orig_uri=ORIGINAL_URI&query_string=QUERY_STRING`.

If `uri_pattern` starts with `@` symbol, then Mongoose compares
it with the `HOST` header of the request. If they are equal, Mongoose sets
document root to `file_or_directory_path`, implementing virtual hosts support.
Sergey Lyubka's avatar
Sergey Lyubka committed
139

Sergey Lyubka's avatar
Sergey Lyubka committed
140
Examples:
Sergey Lyubka's avatar
Sergey Lyubka committed
141

142 143
    # Redirect all accesses to `.doc` files to a special script
    mongoose -url_rewrites **.doc$=/path/to/cgi-bin/handle_doc.cgi
Sergey Lyubka's avatar
Sergey Lyubka committed
144

145 146
    # Implement user home directories support
    mongoose -url_rewrites /~joe/=/home/joe/,/~bill=/home/bill/
Sergey Lyubka's avatar
Sergey Lyubka committed
147

148 149
    # Redirect 404 errors to a specific error page
    mongoose -url_rewrites 404=/cgi-bin/error.cgi
Sergey Lyubka's avatar
Sergey Lyubka committed
150

Sergey Lyubka's avatar
Sergey Lyubka committed
151 152 153
    # Virtual hosts example: serve foo.com domain from different directory
    mongoose -url_rewrites @foo.com=/var/www/foo.com

Sergey Lyubka's avatar
Sergey Lyubka committed
154
Default: not set.