Skip to content

M
mongoose
Commit 9778a4cc authored by Sergey Lyubka's avatar Sergey Lyubka
Browse files
Options

Options doc synced

parent d0e27418
Hide whitespace changes
Inline Side-by-side
Showing with 78 additions and 147 deletions
docs/Options.md
View file @ 9778a4cc
# Mongoose Configuration Options # Mongoose Configuration Options
Every option is followed by it's default value. ### access\_control\_list
If default value is not present, then it is empty. 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.
### cgi_pattern `**.cgi$|**.pl$|**.php$` Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
All files that match `cgi_pattern` are treated as CGI files. Default pattern all accesses. On each request the full list is traversed, and
allows CGI files be anywhere. To restrict CGIs to a certain directory, the last match wins. Examples:
use `/path/to/cgi-bin/**.cgi` as pattern. Note that full file path is
matched against the pattern, not the URI.
### cgi_environment -0.0.0.0/0,+192.168/16 deny all acccesses, only allow 192.168/16 subnet
Extra environment variables to be passed to the CGI script in
addition to standard ones. The list must be comma-separated list
of name=value pairs, like this: `VARIABLE1=VALUE1,VARIABLE2=VALUE2`.
### dav\_auth\_file To learn more about subnet masks, see the
Passwords file for PUT and DELETE requests. Without it, PUT and DELETE requests [Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)
will fail. The format of the passwords file is the same as for `.htpasswd` file
used for Digest authentication. It can be created and managed by means Default: not set, all accesses are allowed.
of `mongoose -A` command.
### 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`
### cgi_interpreter ### cgi_interpreter
Path to an executable to use as CGI interpreter for __all__ CGI scripts Path to an executable to use as CGI interpreter for __all__ CGI scripts
regardless script extension. If this option is not set (which is a default), regardless script extension.
Mongoose looks at first line of a CGI script, for an interpreter. Default: not set, Mongoose looks at
[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\)), [shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\).
for an interpreter.
For example, if both PHP and perl CGIs are used, then 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 `#!/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, respective CGI scripts. Note that paths should be either full file paths,
or file paths relative to the current working directory of mongoose server. or file paths relative to the directory where mongoose server is located.
If mongoose is started by mouse double-click on Windows, current working
directory is a directory where mongoose executable is located.
If all CGIs use the same interpreter, for example they are all PHP, then If all CGIs use the same interpreter, for example they are all PHP, then
`cgi_interpreter` can be set to the path to `php-cgi.exe` executable and `cgi_interpreter` option can be set to the path to `php-cgi.exe` executable and
shebang line in the CGI scripts can be omitted. shebang line in the CGI scripts can be omitted.
Note that PHP scripts must use `php-cgi.exe` executable, not `php.exe`. Note that PHP scripts must use `php-cgi.exe` executable, not `php.exe`.
### protect_uri ### cgi_pattern
Comma separated list of URI=PATH pairs, specifying that given All files that match `cgi_pattern` are treated as CGI files. Default pattern
URIs must be protected with respected password files. Paths must be full allows CGI files be anywhere. To restrict CGIs to a certain directory,
file paths. use `/path/to/cgi-bin/**.cgi` as pattern. Note that full file path is
matched against the pattern, not the URI. Note: if `MONGOOSE_CGI` environment
### authentication_domain `mydomain.com` variable is set, then Mongoose passes it to the CGI script.
Authorization realm used in `.htpasswd` authorization.
### ssi_pattern `**.shtml$|**.shtm$`
All files that match `ssi_pattern` are treated as SSI.
Server Side Includes (SSI) is a simple interpreted server-side scripting
language which is most commonly used to include the contents of a file into
a web page. It can be useful when it is desirable to include a common piece
of code throughout a website, for example, headers and footers.
In order for a webpage to recognize an SSI-enabled HTML file, the filename
should end with a special extension, by default the extension should be
either `.shtml` or `.shtm`.
Unknown SSI directives are silently ignored by mongoose. Currently, two SSI
directives are supported, `<!--#include ...>` and
`<!--#exec "command">`. Note that `<!--#include ...>` directive supports
three path specifications:
<!--#include virtual="path"> Path is relative to web server root
<!--#include abspath="path"> Path is absolute or relative to
web server working dir
<!--#include file="path">, Path is relative to current document
<!--#include "path">
The `include` directive may be used to include the contents of a file or the Default: `**.cgi$|**.pl$|**.php$`
result of running a CGI script. The `exec` directive is used to execute a
command on a server, and show command's output. Example:
<!--#exec "ls -l" --> ### 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.
For more information on Server Side Includes, take a look at the Wikipedia: ### document_root
[Server Side Includes](http://en.wikipedia.org/wiki/Server_Side_Includes) A directory to serve. Default: current working directory.
### access\_log\_file ### enable\_directory\_listing
Path to a file for access logs. Either full path, or relative to current Enable directory listing, either `yes` or `no`. Default: `yes`.
working directory. If absent (default), then accesses are not logged.
### error\_log\_file ### error\_log\_file
Path to a file for error logs. Either full path, or relative to current Path to a file for error logs. Either full path, or relative to the
working directory. If absent (default), then errors are not logged. mongoose executable. Default: not set, no errors are logged.
### enable\_directory\_listing `yes`
Enable directory listing, either `yes` or `no`.
### enable\_keep\_alive `no` ### extra\_mime\_types
Enable connection keep alive, either `yes` or `no`. Extra mime types to recognize, in form `extension1=type1,extension2=type2,...`.
Extension must include dot. Example:
Experimental feature. Allows clients to reuse TCP connection for `mongoose -extra_mime_types .cpp=plain/text,.java=plain/text`. Default: not set.
subsequent HTTP requests, which improves performance.
For this to work when using request handlers it's important to add the correct
Content-Length HTTP header for each request. If this is forgotten the client
will time out.
### global\_auth\_file ### global\_auth\_file
Path to a global passwords file, either full path or relative to the current Path to a global passwords file, either full path or relative to the mongoose
working directory. If set, per-directory `.htpasswd` files are ignored, executable. If set, per-directory `.htpasswd` files are ignored,
and all requests are authorised against that file. and all requests are authorised against that file. Use `mongoose -A` to
manage passwords, or third party utilities like
The file has to include the realm set through `authentication_domain` and the password in digest format: [htpasswd-generator](http://www.askapache.com/online-tools/htpasswd-generator).
Default: not set, per-directory `.htpasswd` files are respected.
user:realm:digest ### hide\_files\_patterns
test:test.com:ce0220efc2dd2fad6185e1f1af5a4327 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.
(e.g. use [this generator](http://www.askapache.com/online-tools/htpasswd-generator)) ### idle\_timeout\_ms
Timeout for idle connections. Default: 30000 (30 seconds)
### index_files `index.html,index.htm,index.cgi,index.shtml,index.php` ### index_files
Comma-separated list of files to be treated as directory index Comma-separated list of files to be treated as directory index
files. files. Default: `index.html,index.htm,index.cgi,index.shtml,index.php`
### 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.
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
the last match wins. Examples:
-0.0.0.0/0,+192.168/16 deny all acccesses, only allow 192.168/16 subnet
To learn more about subnet masks, see the
[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)
### extra\_mime\_types
Extra mime types to recognize, in form `extension1=type1,exten-
sion2=type2,...`. Extension must include dot. Example:
`.cpp=plain/text,.java=plain/text`
### listening_ports `8080`
Comma-separated list of ports to listen on. If the port is SSL, a
letter `s` must be appeneded, for example, `80,443s` will open
port 80 and port 443, and connections on port 443 will be SSL-ed.
For non-SSL ports, it is allowed to append letter `r`, meaning 'redirect'.
Redirect ports will redirect all their traffic to the first configured
SSL port. For example, if `listening_ports` is `80r,443s`, then all
HTTP traffic coming at port 80 will be redirected to HTTPS port 443.
It is possible to specify an IP address to bind to. In this case,
an IP address and a colon must be prepended to the port number.
For example, to bind to a loopback interface on port 80 and to
all interfaces on HTTPS port 443, use `127.0.0.1:80,443s`.
### document_root `.`
A directory to serve. By default, currect directory is served. Current
directory is commonly referenced as dot (`.`).
### ssl_certificate ### ssl_certificate
Path to SSL certificate file. This option is only required when at least one Path to SSL certificate file. The file must be in PEM format,
of the `listening_ports` is SSL. The file must be in PEM format,
and it must have both private key and certificate, see for example and it must have both private key and certificate, see for example
[ssl_cert.pem](https://github.com/cesanta/mongoose/blob/master/build/ssl_cert.pem) [ssl_cert.pem](https://github.com/cesanta/mongoose/blob/master/build/ssl_cert.pem). If this option is set, then Mongoose serves SSL connections on
`listening_port`. Default: not set.
### run\_as\_user ### listening_port
Switch to given user credentials after startup. Usually, this option is Port to listen on. Port could be prepended by the specific IP address to bind
required when mongoose needs to bind on privileged port on UNIX. To do to, e.g. `mongoose -listening_port 127.0.0.1:8080`. Otherwise Mongoose
that, mongoose needs to be started as root. But running as root is a bad idea, will bind to all addresses. Default: 8080.
therefore this option can be used to drop privileges. Example:
mongoose -listening_ports 80 -run_as_user nobody ### 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.
### request\_timeout\_ms `30000` $ sudo mongoose -listening_ports 80 -run_as_user nobody
Timeout for network read and network write operations, in milliseconds.
If client intends to keep long-running connection, either increase this value
or use keep-alive messages.
Default: not set.
### url\_rewrite\_patterns ### url\_rewrite\_patterns
Comma-separated list of URL rewrites in the form of Comma-separated list of URL rewrites in the form of
...@@ -196,11 +134,4 @@ Or, to imitate user home directories support, do: ...@@ -196,11 +134,4 @@ Or, to imitate user home directories support, do:
mongoose -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/ mongoose -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/
### hide\_files\_patterns Default: not set.
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. Example:
mongoose -hide_files_patterns secret.txt|even_more_secret.txt
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment