mongoose/docs/Usage.md

Mongoose User Guide

Mongoose is small and easy to use web server built on top of mongoose library. It 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 launch a browser at http://localhost:8080 Note that 'localhost' should be changed to a machine's name if a folder is accessed from other computer.

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

On UNIX, 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 -document_root /var/www  # Running mongoose with cmdline options
$ mongoose /etc/my_config.txt       # Running mongoose with config file
$ mongoose                          # Running with no parameters. This will
                                    # serve current directory on port 8080

Mongoose does not detach from terminal. Pressing Ctrl-C keys stops the server.

When started, mongoose first searches for the configuration file. If configuration file is specified explicitly in the command line, 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 can be absent.

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:

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

Command line arguments are highest priority and can override configuration file settings. 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 used as document root.

Note that configuration options on the command line must start with -, and their names are the same as in the config file. Exampli gratia, the following two setups are equivalent:

$ mongoose -listening_port 1234 -document_root /var/www

$ cat > mongoose.conf
listening_ports 1234
document_root /var/www
^D
$ mongoose

Mongoose can also be used to modify .htpasswd passwords file:

$ mongoose -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 slash 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:

# Pattern   Meaning
**.cgi$     Any string that ends with .cgi
/foo        Any string that begins with /foo
**a$|**b$   Any string that ends with a or b

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

$ mongoose -cgi_pattern /cgi-bin/*.cgi # Emulate /cgi-bin/ restriction