Mongoose Web Server Binary version: master

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

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

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

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

The configuration file is a sequence of lines. Each line contains a configuration option name and its value. Empty lines and lines beginning with # are ignored. Here is a example of the 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 Binary can be started from the command prompt, and configuration parameters can be specified as command line arguments with - prepended. For example:

mongoose.exe -document_root C:\www

Mongoose Binary 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 Binary does not require CGI scripts to be located in a special directory. CGI scripts can be anywhere. CGI and SSI files are recognised by the file name pattern. Mongoose Binary uses shell-like glob patterns. The pattern match starts at the beginning of the string, so essentially patterns are prefix patterns. The 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 the /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 Binary 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, a minus sign means deny. If a subnet mask is omitted, such as -1.2.3.4, a /32 mask is assumed. 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 access. 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 will deny all acccesses except those from the 192.168/16 subnet. Note, that if the option is set, then all access is forbidden by default. Thus, as outlined in the previous example, the -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 access is allowed.

access_log_file

edit

The path to a file for access logs. Either the full path or relative to the Mongoose Binary executable.

Example: access_log_file c:\logs\web_access_log.txt

Default: not set, no logging is done.

auth_domain

edit

The authorisation realm used in .htpasswd authorisation.

Example: auth_domain mysite.com

Default: mydomain.com

cgi_interpreter

edit

The path to an executable to be used as an interpreter for all CGI scripts regardless of the script extension. If this option is not set (which is the default), Mongoose Binary 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 the first lines of the respective CGI scripts. Note, paths should be either full file paths or file paths relative to the directory where the Mongoose Binary executable is located.

If all CGIs use the same interpreter, for example they are all PHP, then the cgi_interpreter option can be set to the path to the php-cgi.exe executable and the 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. The default pattern allows CGI files to be anywhere. To restrict CGIs to a certain directory, use /path/to/cgi-bin/**.cgi as a pattern. Note, full file path is matched against the pattern, not the URI.

When Mongoose Binary starts the CGI program, it creates a new environment for it (in contrast, usually the child program inherits the environment from the parent). Several environment variables however are inherited from Mongoose Binary'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

The 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. The 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 recognised 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

The path to the global passwords file. It's either the full path or relative to the Mongoose Binary 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 be hidden. Files that match the pattern will not show up in a directory listing and return 404 Not Found if requested. Pattern must be for a file name only, not including a 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. The port could be prepended by a specific IP address to bind to, e.g. listening_port 127.0.0.1:8080. Otherwise Mongoose Binary will bind to all addresses. To enable SSL, build Mongoose Binary with a -DNS_ENABLE_SSL compilation option and specify listening_port as ssl://PORT.

NOTE: if the 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. Switches to a given user's credentials after startup. This option is required when Mongoose Binary 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 a 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 a browser automatically when Mongoose Binary starts.

Example: start_browser no

Default: yes.

url_rewrites

edit

A comma-separated list of URL rewrites in the form of uri_pattern=file_or_directory_path. When Mongoose Binary 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, uri_pattern, as all Mongoose Binary patterns, is a prefix pattern. If uri_pattern is a number, then it is treated as a HTTP error code, and file_or_directory_path should be a URI to redirect to. Mongoose Binary will issue a302 temporary redirect to the specified URI with the following parameters: ?code=HTTP_ERROR_CODE&orig_uri=ORIGINAL_URI&query_string=QUERY_STRING.

If uri_pattern starts with an @ symbol, then Mongoose Binary compares it with the Host header of the request. If they are equal, Mongoose Binary sets the 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.