1# Mongoose User Guide
2
3Mongoose is small and easy to use web server built on top of
4mongoose library. It is designed with maximum simplicity in mind. For example,
5to share any directory, just drop mongoose executable in that directory,
6double-click it (on UNIX, run it from shell) and launch a browser at
7[http://localhost:8080](http://localhost:8080) Note that 'localhost' should
8be changed to a machine's name if a folder is accessed from other computer.
9
10On Windows and Mac, Mongoose iconifies itself to the system tray when started.
11Right-click on the icon to pop up a menu, where it is possible to stop
12mongoose, or configure it.
13
14On UNIX, `mongoose` is a command line utility. Running `mongoose` in
15terminal, optionally followed by configuration parameters
16(`mongoose [OPTIONS]`) or configuration file name
17(`mongoose [config_file_name]`) starts the
18web server:
19
20    $ mongoose -document_root /var/www  # Running mongoose with cmdline options
21    $ mongoose /etc/my_config.txt       # Running mongoose with config file
22    $ mongoose                          # Running with no parameters. This will
23                                        # serve current directory on port 8080
24
25Mongoose does not detach from terminal. Pressing `Ctrl-C` keys
26stops the server.
27
28When started, mongoose first searches for the configuration file.
29If configuration file is specified explicitly in the command line, then
30specified configuration file is used.
31Otherwise, mongoose would search for file `mongoose.conf` in the same directory
32where binary is located, and use it. Configuration file can be absent.
33
34Configuration file is a sequence of lines, each line containing
35command line argument name and it's value. Empty lines and lines beginning
36with `#` are ignored. Here is the example of `mongoose.conf` file:
37
38    # This is a comment
39    document_root C:\www
40    listening_port 80
41    ssl_certificate C:\mongoose\ssl_cert.pem
42
43Command line arguments are highest priority and can override
44configuration file settings. For example, if `mongoose.conf` has line
45`document_root /var/www`, and mongoose has been started as
46`mongoose -document_root /etc`, then `/etc` directory will be used as
47document root.
48
49Note that configuration options on the command line must start with `-`,
50and their names are the same as in the config file. Exampli gratia,
51the following two setups are equivalent:
52
53    $ mongoose -listening_port 1234 -document_root /var/www
54
55    $ cat > mongoose.conf
56    listening_ports 1234
57    document_root /var/www
58    ^D
59    $ mongoose
60
61Mongoose can also be used to modify `.htpasswd` passwords file:
62
63    $ mongoose -A .htpasswd mydomain.com user_name user_password
64
65Unlike other web servers, mongoose does not require CGI scripts be located in
66a special directory. CGI scripts can be anywhere. CGI (and SSI) files are
67recognized by the file name pattern. Mongoose uses shell-like glob
68patterns. Pattern match starts at the beginning of the string, so essentially
69patterns are prefix patterns. Syntax is as follows:
70
71     **         Matches everything
72     *          Matches everything but slash character, '/'
73     ?          Matches any character
74     $          Matches the end of the string
75     |          Matches if pattern on the left side or the right side matches.
76
77All other characters in the pattern match themselves. Examples:
78
79    # Pattern   Meaning
80    **.cgi$     Any string that ends with .cgi
81    /foo        Any string that begins with /foo
82    **a$|**b$   Any string that ends with a or b
83
84To restrict CGI files only to `/cgi-bin/` directory, use this setting:
85
86    $ mongoose -cgi_pattern /cgi-bin/*.cgi # Emulate /cgi-bin/ restriction
87