Mongoose Binary - User Guide

Mongoose is a small and easy to use web server built on top of the multi-protocol networking library. Mongoose is designed with maximum simplicity in mind. For example, to share any directory, just drop Mongoose executable in that directory, double-click it (on UNIX, run it from shell) and point your browser at http://localhost:8080

NOTE: localhost should be changed to the machine's name if accessed from another computer.

On Windows and Mac, Mongoose adds an icon to they system tray when started. Right-click on the icon to pop up a menu, where it is possible to stop Mongoose, or configure it.

When started, Mongoose first searches for a configuration file called mongoose.conf in the same directory where the binary is located. Configuration file can be absent, in this case default configuration options are used.

Configuration file is a sequence of lines, each line containing configuration option name and it's value. Empty lines and lines beginning with # are ignored. Here is the example of mongoose.conf file:

# This is a comment
document_root C:\www
listening_port 80,ssl://443
ssl_certificate C:\mongoose\ssl_cert.pem

NOTE: Mongoose can be started from the command prompt, and configuration parameters can be specified as a command line arguments with - prepended. For example:

mongoose.exe -document_root C:\www

Mongoose supports digest authentication, and it can be used to add users to the .htpasswd file:

mongoose.exe -A .htpasswd user_name user_password

Unlike other web servers, Mongoose does not require CGI scripts be located in a special directory. CGI scripts can be anywhere. CGI and SSI files are recognized by the file name pattern. Mongoose uses shell-like glob patterns. Pattern match starts at the beginning of the string, so essentially patterns are prefix patterns. Syntax is as follows:

  • **: Matches everything
  • *: Matches everything but / character
  • ?: Matches any character
  • $: Matches the end of the string
  • |: Matches if pattern on the left side or the right side matches.

All other characters in the pattern match themselves. Examples:

  • **.cgi$: Any string that ends with .cgi
  • /foo: Any string that begins with /foo
  • **a$|b: Any string that ends with a or begins with b

To restrict CGI files only to /cgi-bin/ directory, use this setting:

cgi_pattern /cgi-bin/



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 prefix specifications, where each prefix is prepended by either a - or a + sign. A plus sign means allow, and a minus sign means deny. If a subnet mask is omitted, such as -, a /32 mask is assumed and that 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. Example: $ mongoose -access_control_list -,+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, - part is not necessary. For example, access_control_list + means disallow all, allow subnet 10/8 only.

To learn more about subnet masks, see

Example: access_control_list -,+192.168/16

Default: not set, all accesses are allowed.



Path to a file for access logs. Either full path, or relative to the Mongoose executable.

Example: access_log_file c:\logs\web_access_log.txt

Default: not set, no logging is done.



Authorization realm used in .htpasswd authorization.

Example: auth_domain




Path to an executable to be used use as an interpreter for all CGI scripts regardless script extension. If this option is not set (which is the default), Mongoose honours the shebang line - see

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, or file paths relative to the directory where the Mongoose executable is located.

If all CGIs use the same interpreter, for example they are all PHP, then cgi_interpreter option can be set to the path to php-cgi.exe executable and shebang line in the CGI scripts can be omitted.

NOTE: PHP scripts must use php-cgi.exe, not php.exe.

Example: cgi_interpreter C:\ruby\ruby.exe

Default: not set.



All files that match cgi_pattern are treated as CGI scripts. Default pattern allows CGI files be anywhere. To restrict CGIs to a certain directory, use /path/to/cgi-bin/**.cgi as a pattern. Note that full file path is 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).

Example: cgi_pattern **.cgi$

Default: **.cgi$|**.pl$|**.php$



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. If dav_auth_file is set to -, then DAV authentication is disabled.

Example: dav_auth_file c:\dav_auth.txt

Default: not set, WebDAV mutations are disallowed.



A root directory for DAV requests.

Example: dav_root C:\dav_root

Default: not set, meaning that DAV root directory is the same as document_root



A root directory for web requests.

Example: document_root c:\www

Default: current working directory.



Extra HTTP headers to add to the HTTP response. An example above shows how to allow CORS.

NOTE: currently, only one HTTP header can be specified.

Example: extra_headers Access-Control-Allow-Origin:

Default: not set.



Extra mime types to recognize, in the form extension1=type1,extension2=type2,.... Extension must include dot.

Example: extra_mime_types .cpp=plain/text,.java=plain/text

Default: not set.



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

Example: global_auth_file C:\global_passwords.txt

Default: not set, per-directory .htpasswd files are respected.



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: hide_files_patterns secret.txt|.**

Default: not set.



If specified, a hexdump of all incoming and outgoing traffic is written into that file. File "-" means standard error output.

Example: hexdump_file c:\www_traffic.txt

Default: not set.



Comma-separated list of file names to be treated as directory index files.

Example: index_files index.cgi,index.html

Default: index.html,index.htm,index.cgi,index.shtml,index.php



Comma separated list of listening ports. Port could be prepended by the specific IP address to bind to, e.g. listening_port Otherwise Mongoose will bind to all addresses. To enable SSL, build Mongoose with -DNS_ENABLE_SSL compilation option, and specify listening_port as ssl://PORT.

NOTE: if SSL listening port is specified, ssl_certificate option must be set.

Example: listening_port 80,ssl://443

Default: 8080.



UNIX only option. Switch to given user credentials after startup. This option is required when mongoose needs to bind on a privileged port on UNIX and then run as a non-provoleged user.

Example: run_as_user nobody

Default: not set.



File pattern for SSI files.

Example: ssi_pattern **.shtml$|**.shtm$

Default: **.shtml$|**.shtm$



SSL certificate to use for SSL listening ports. Must be in PEM format, and contain both certificate, private key, and optionally a cert chain.

Example: ssl_certificate c:\ssl_cert.pem

Default: not set.



SSL CA certificate file, used to configure client-side authentication (two-way SSL).

Example: ssl_ca_certificate c:\ssl_ca_cert.pem

Default: not set.



Whether to start browser automatically when Mongoose starts.

Example: start_browser no

Default: yes.



Comma-separated list of URL rewrites in the form of uri_pattern=file_or_directory_path. When Mongoose receives a request, it constructs the file name to serve by combining document_root and the URI. However, if the rewrite option is used and uri_pattern matches the requested URI, then document_root is ignored. Instead, 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 uri_pattern, as all mongoose patterns, is a prefix pattern. If uri_pattern 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 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.


# Redirect all accesses to `.doc` files to a special script
url_rewrites **.doc$=/path/to/cgi-bin/handle_doc.cgi

# Implement user home directories support
url_rewrites /~joe/=/home/joe/,/~bill=/home/bill/

# Redirect 404 errors to a specific error page
url_rewrites 404=/cgi-bin/error.cgi

# Virtual hosts example: serve domain from different directory

# Redirect HTTP traffic to HTTPS port
url_rewrites %80=

Default: not set.