9.4 KiB
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 <htpasswd_file> <realm> <user> <passwd>
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 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-cgion 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 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 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 | odp)
- Linux Journal article by Michel J.Hammel, 2010-04-01, called Mongoose: an Embeddable Web Server in C