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