**NOTE: THIS MANUAL IS WORK IN PROGRESS** ## Overview Mongoose is small and easy to use web server. It is self-contained, and does not require any external software to run. On Windows, mongoose iconifies itself to the system tray icon when started. Right-click on the icon pops up a menu, where it is possible to stop mongoose, or configure it, or install it as Windows service. On UNIX and Mac, mongoose is a command line utility. Running `mongoose` in terminal, optionally followed by configuration parameters (`mongoose [OPTIONS]`) or configuration file name (`mongoose [config_file_name]`) starts the web server. Mongoose does not detach from terminal. Pressing `Ctrl-C` keys would stop the server. When started, mongoose first searches for the configuration file. If configuration file is specified explicitly in the command line, i.e. `mongoose path_to_config_file`, then specified configuration file is used. Otherwise, mongoose would search for file `mongoose.conf` in the same directory where binary is located, and use it. Configuration file is a sequence of lines, each line containing command line argument name and it's value. Empty lines, and lines beginning with `#`, are ignored. Here is the example of `mongoose.conf` file: # mongoose.conf file document_root c:\www listening_ports 8080,8043s ssl_certificate c:\mongoose\ssl_cert.pem When configuration file is processed, mongoose process command line arguments, if they are specified. Command line arguments therefore can override configuration file settings. Command line arguments must start with `-`. For example, if `mongoose.conf` has line `document_root /var/www`, and mongoose has been started as `mongoose -document_root /etc`, then `/etc` directory will be served as document root, because command line options take priority over configuration file. Mongoose can also be used to modify `.htpasswd` passwords file: mongoose -A ## Usage Examples - How to share a Windows folder: copy mongoose executable to a folder and double-click the executable. The folder should be accessible via [http://localhost:8080](http://localhost:8080) in any browser. - How to start mongoose at UNIX startup time in daemon mode, serving directory `/var/www`: put this line in the system startup script: `/path/to/mongoose -listening_ports 80 -document_root /var/www &` - How to serve user home directories using URL rewrite: `mongoose -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/` ## Configuration Options ``` -C cgi_pattern All files that fully match cgi_pattern are treated as CGI. Default pattern allows CGI files be anywhere. To restrict CGIs to certain directory, use e.g. "-C /cgi-bin/**.cgi". Default: "**.cgi$|**.pl$|**.php$" -E cgi_environment Extra environment variables to be passed to the CGI script in addition to standard ones. The list must be comma-separated list of X=Y pairs, like this: "VARIABLE1=VALUE1,VARIABLE2=VALUE2". Default: "" -G put_delete_passwords_file PUT and DELETE passwords file. This must be specified if PUT or DELETE methods are used. Default: "" -I cgi_interpreter Use cgi_interpreter as a CGI interpreter for all CGI scripts regardless script extension. Mongoose decides which interpreter to use by looking at the first line of a CGI script. Default: "". -P protect_uri Comma separated list of URI=PATH pairs, specifying that given URIs must be protected with respected password files. Default: "" -R authentication_domain Authorization realm. Default: "mydomain.com" -S ssi_pattern All files that fully match ssi_pattern are treated as SSI. Unknown SSI directives are silently ignored. Currently, two SSI directives are supported, "include" and "exec". Default: "**.shtml$|**.shtm$" -T throttle Limit download speed for clients. throttle is a comma-separated list of key=value pairs, where key could be a '*' character (limit for all connections), a subnet in form x.x.x.x/mask (limit for a given subnet, for example 10.0.0.0/8), or an URI prefix pattern (limit for the set of URIs, for example /foo/**). The value is a floating-point number of bytes per second, optionally followed by a `k' or `m' character, meaning kilobytes and megabytes respectively. A limit of 0 means unlimited rate. The last matching rule wins. For example, "*=1k,10.0.0.0/8" means limit everybody to 1 kilobyte per second, but give people from 10/8 subnet unlimited speed. Default: "" -a access_log_file Access log file. Default: "", no logging is done. -d enable_directory_listing Enable/disable directory listing. Default: "yes" -e error_log_file Error log file. Default: "", no errors are logged. -g global_passwords_file Location of a global passwords file. If set, per-directory .htpasswd files are ignored, and all requests must be authorised against that file. Default: "" -i index_files Comma-separated list of files to be treated as directory index files. Default: "index.html,index.htm,index.cgi" -l access_control_list Specify access control list (ACL). ACL is a comma separated list of IP subnets, each subnet is prepended by '-' or '+' sign. Plus means allow, minus means deny. If subnet mask is omitted, like "-1.2.3.4", then it means single IP address. Mask may vary from 0 to 32 inclusive. On each request, full list is traversed, and last match wins. Default setting is to allow all. For example, to allow only 192.168/16 subnet to connect, run "mongoose -0.0.0.0/0,+192.168/16". Default: "" -m extra_mime_types Extra mime types to recognize, in form "extension1=type1,exten- sion2=type2,...". Extension must include dot. Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: "" -p listening_ports Comma-separated list of ports to listen on. If the port is SSL, a letter 's' must be appeneded, for example, "-p 80,443s" will open port 80 and port 443, and connections on port 443 will be SSL-ed. 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 "mongoose -p 127.0.0.1:80,443s". Default: "8080" -r document_root Location of the WWW root directory. Default: "." -s ssl_certificate Location of SSL certificate file. Default: "" -t num_threads Number of worker threads to start. Default: "10" -u run_as_user Switch to given user's credentials after startup. Default: "" -w url_rewrite_patterns Comma-separated list of URL rewrites in the form of "pattern=sub- stitution,..." If the "pattern" matches some prefix of the requested URL, then matched prefix gets substituted with "substi- tution". For example, "-w /con- fig=/etc,**.doc|**.rtf=/path/to/cgi-bin/handle_doc.cgi" will serve all URLs that start with "/config" from the "/etc" direc- tory, and call handle_doc.cgi script for .doc and .rtf file requests. If some pattern matches, no further matching/substitu- tion is performed (first matching pattern wins). Use full paths in substitutions. Default: "" -x hide_files_patterns A prefix pattern for the files to hide. Files that match the pat- tern will not show up in directory listing and return 404 Not Found if requested. Default: "" ``` ## Common Problems --------------- - PHP doesn't work - getting empty page, or 'File not found' error. The reason for that is wrong paths to the interpreter. Remember that with PHP, correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX). Solution: specify full path to the PHP interpreter, e.g. `mongoose -cgi_interpreter /full/path/to/php-cgi` ## Embedding Embedding Mongoose is easy. Somewhere in the application code, `mg_start()` function must be called. That starts the web server in a separate thread. When it is not needed anymore, `mg_stop()` must be called. Application code can pass configuration options to `mg_start()`, and also specify callback functions that Mongoose should call at certain events. [hello.c](http://a.c) provides a minimalistic example. Common pattern is to implement `begin_request` callback, and serve static files from memory, and/or construct dynamic replies on the fly. Here is my [embed.c](https://gist.github.com/valenok/4714740) gist that shows how to easily any data can be embedded directly into the executable. If such data needs to be encrypted, then encrypted database or encryption dongles would be a better choice. ## Other Resources - Presentation made by Arnout Vandecappelle at FOSDEM 2011 on 2011-02-06 in Brussels, Belgium, called "Creating secure web based user interfaces for Embedded Devices" ([pdf](http://mind.be/content/110206_Web-ui.pdf) | [odp](http://mind.be/content/110206_Web-ui.odp)) - Linux Journal article by Michel J.Hammel, 2010-04-01, called [Mongoose: an Embeddable Web Server in C](http://www.linuxjournal.com/article/10680)