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 mydomain.com 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/

access_control_list

edit

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 -1.2.3.4, 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 -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, access_control_list +10.0.0.0/8 means disallow all, allow subnet 10/8 only.

To learn more about subnet masks, see http://en.wikipedia.org/wiki/Subnetwork

Example: access_control_list -0.0.0.0/0,+192.168/16

Default: not set, all accesses are allowed.

access_log_file

edit

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.

auth_domain

edit

Authorization realm used in .htpasswd authorization.

Example: auth_domain mysite.com

Default: mydomain.com

cgi_interpreter

edit

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 http://en.wikipedia.org/wiki/Shebang_(Unix).

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.

cgi_pattern

edit

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$

dav_auth_file

edit

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.

dav_root

edit

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

document_root

edit

A root directory for web requests.

Example: document_root c:\www

Default: current working directory.

extra_headers

edit

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: myotherdomain.com

Default: not set.

extra_mime_types

edit

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.

global_auth_file

edit

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 http://www.askapache.com/online-tools/htpasswd-generator.

Example: global_auth_file C:\global_passwords.txt

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

hide_files_patterns

edit

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.

hexdump_file

edit

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.

index_files

edit

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

listening_port

edit

Comma separated list of listening ports. Port could be prepended by the specific IP address to bind to, e.g. listening_port 127.0.0.1:8080. 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.

run_as_user

edit

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.

ssi_pattern

edit

File pattern for SSI files.

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

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

ssl_certificate

edit

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

edit

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.

start_browser

edit

Whether to start browser automatically when Mongoose starts.

Example: start_browser no

Default: yes.

url_rewrites

edit

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.

Example:

# 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 foo.com domain from different directory
url_rewrites @foo.com=/var/www/foo.com

# Redirect HTTP traffic to HTTPS port
url_rewrites %80=https://mysite.com

Default: not set.