From 782d0cda46b6db38f1f4f59f65d06e820327390b Mon Sep 17 00:00:00 2001
From: Sergey Lyubka <valenok@gmail.com>
Date: Fri, 8 Feb 2013 10:10:02 +0000
Subject: [PATCH] Updated user manual
---
UserManual.md | 361 +++++++++++++++++++++++++++++---------------------
1 file changed, 209 insertions(+), 152 deletions(-)
diff --git a/UserManual.md b/UserManual.md
index f0d435451..39a2c8e03 100644
--- a/UserManual.md
+++ b/UserManual.md
@@ -1,14 +1,15 @@
-
-**NOTE: THIS MANUAL IS WORK IN PROGRESS**
-
-## Overview
+# 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.
+mongoose, or configure it, or install it as Windows service. The easiest way
+to share a folder on Windows is to copy `mongoose.exe` to a folder,
+double-click the exe, and launch a browser at
+[http://localhost:8080](http://localhost:8080). Note that 'localhost' should
+be changed to a machine's name if a folder is accessed from other computer.
On UNIX and Mac, mongoose is a command line utility. Running `mongoose` in
terminal, optionally followed by configuration parameters
@@ -21,12 +22,13 @@ 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.
+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:
- # mongoose.conf file
document_root c:\www
listening_ports 8080,8043s
ssl_certificate c:\mongoose\ssl_cert.pem
@@ -38,164 +40,219 @@ 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.
+configuration file. Configuration options section below provide a good
+overview of Mongoose features.
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](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
----------------
+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:
+
+ **.cgi$ Any string that ends with .cgi
+ /foo Any string that begins with /foo
+ **a$|**b$ Any string that ends with a or b
+
+# Configuration Options
+
+Below is a list of configuration options Mongoose understands. Every option
+is followed by it's default value. If default value is not present, then
+it is empty.
+
+### cgi_pattern `**.cgi$|**.pl$|**.php$`
+All files that match `cgi_pattern` are treated as CGI files. Default pattern
+allows CGI files be anywhere. To restrict CGIs to a certain directory,
+use `/path/to/cgi-bin/**.cgi` as pattern. Note that full file path is
+matched against the pattern, not the URI.
+
+### 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 name=value pairs, like this: `VARIABLE1=VALUE1,VARIABLE2=VALUE2`.
+
+### put\_delete\_passwords_file
+Passwords file for PUT and DELETE requests. Without it, PUT and DELETE requests
+will fail.
+
+### cgi_interpreter
+Path to an executable to use as CGI interpreter for __all__ CGI scripts
+regardless script extension. If this option is not set (which is a default),
+Mongoose looks at first line of a CGI script,
+[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix)), for an interpreter.
+
+For example, if both PHP and perl CGIs are used, then
+`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
+respective CGI scripts. Note that paths should be either full file paths,
+or file paths relative to the current working directory of mongoose server.
+If mongoose is started by mouse double-click on Windows, current working
+directory is a directory where mongoose executable is located.
+
+If all CGIs use the same interpreter, for example they are all PHP, then
+`cgi_interpreter` can be set to the path to `php-cgi.exe` executable and
+shebang line in the CGI scripts can be omitted.
+Note that PHP scripts must use `php-cgi.exe` executable, not `php.exe`.
+
+### protect_uri
+Comma separated list of URI=PATH pairs, specifying that given
+URIs must be protected with respected password files. Paths must be full
+file paths.
+
+### authentication_domain `mydomain.com`
+Authorization realm used in `.htpasswd` authorization.
+
+### ssi_pattern `**.shtml$|**.shtm$`
+All files that match `ssi_pattern` are treated as SSI.
+Unknown SSI directives are silently ignored. Currently, two SSI
+directives are supported, `<!--#include ...>` and
+`<!--#exec command>`. Note that `<!--#include ...>` directive supports
+three path specifications:
+
+ <!--#include virtual="path"> Path is relative to web server root
+ <!--#include file="path"> Path is relative to web server working dir
+ <!--#include "path"> Path is relative to current document
+
+### throttle
+Limit download speed for clients. `throttle` is a comma-separated
+list of key=value pairs, where key could be:
+
+ * limit speed for all connections
+ x.x.x.x/mask limit speed for specified subnet
+ uri_prefix_pattern limit speed for given URIs
+
+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. Examples:
+
+ *=1k,10.0.0.0/8=0 limit all accesses to 1 kilobyte per second,
+ but give connections from 10.0.0.0/8 subnet
+ unlimited speed
+
+ /downloads/=5k limit accesses to all URIs in `/downloads/` to
+ 5 kilobytes per secods. All other accesses are unlimited
+
+### access\_log\_file
+Path to a file for access logs. Either full path, or relative to current
+working directory. If absent (default), then accesses are not logged.
+
+### error\_log\_file
+Path to a file for error logs. Either full path, or relative to current
+working directory. If absent (default), then errors are not logged.
+
+### enable\_directory\_listing `yes`
+Enable directory listing, either `yes` or `no`.
+
+### global\_passwords\_file
+Path to a global passwords file, either full path or relative to the current
+working directory. If set, per-directory `.htpasswd` files are ignored,
+and all requests are authorised against that file.
+
+### index_files `index.html,index.htm,index.cgi,index.shtml,index.php`
+Comma-separated list of files to be treated as directory index
+files.
+
+### access\_control\_list
+Access Control List (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 a 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 accesses. Examples:
+
+ -0.0.0.0/0,+192.168/16 deny all acccesses, only allow 192.168/16 subnet
+
+### extra\_mime\_types
+Extra mime types to recognize, in form `extension1=type1,exten-
+sion2=type2,...`. Extension must include dot. Example:
+`.cpp=plain/text,.java=plain/text`
+
+### listening_ports `8080`
+Comma-separated list of ports to listen on. If the port is SSL, a
+letter `s` must be appeneded, for example, `80,443s` will open
+port 80 and port 443, and connections on port 443 will be SSL-ed.
+For non-SSL ports, it is allowed to append letter `r`, meaning 'redirect'.
+Redirect ports will redirect all their traffic to the first configured
+SSL port. For example, if `listening_ports` is `80r,443s`, then all
+HTTP traffic coming at port 80 will be redirected to HTTPS port 443.
+
+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 `127.0.0.1:80,443s`.
+
+### document_root `.`
+A directory to serve. By default, currect directory is served. Current
+directory is commonly referenced as dot (`.`).
+
+### ssl_certificate
+Path to SSL certificate file. This option is only required when at least one
+of the `listening_ports` is SSL.
+
+### num_threads `50`
+Number of worker threads. Mongoose handles each incoming connection in a
+separate thread. Therefore, the value of this option is effectively a number
+of concurrent HTTP connections Mongoose can handle.
+
+### run\_as\_user
+Switch to given user credentials after startup. Usually, this option is
+required when mongoose needs to bind on privileged port on UNIX. To do
+that, mongoose needs to be started as root. But running as root is a bad idea,
+therefore this option can be used to drop privileges. Example:
+
+ mongoose -listening_ports 80 -run_as_user nobody
+
+### url\_rewrite\_patterns
+Comma-separated list of URL rewrites in the form of
+`uri_pattern=file_or_directory_path`. When Mongoose receives the request,
+it constructs the file name to show 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. Insted,
+`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 that
+`uri_pattern`, as all mongoose patterns, is a prefix pattern.
+
+This makes it possible to serve many directories outside from `document_root`,
+redirect all requests to scripts, and do other tricky things. For example,
+to redirect all accesses to `.doc` files to a special script, do:
+
+ mongoose -url_rewrite_patterns **.doc$=/path/to/cgi-bin/handle_doc.cgi
+
+Or, to imitate user home directories support, do:
+
+ mongoose -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/
+
+### hide\_files\_patterns
+A pattern for the files to hide. Files that match the pattern will not
+show up in directory listing and return `404 Not Found` if requested. Pattern
+must be for a file name only, not including directory name.
+
+# 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`
+ full path to the PHP interpreter, e.g.:
+ `mongoose -cgi_interpreter /full/path/to/php-cgi`
-## Embedding
+# 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.
+[hello.c](https://github.com/valenok/mongoose/blob/master/examples/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
@@ -205,7 +262,7 @@ directly into the executable. If such data needs to be encrypted, then
encrypted database or encryption dongles would be a better choice.
-## Other Resources
+# 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"
--
GitLab