From 782d0cda46b6db38f1f4f59f65d06e820327390b Mon Sep 17 00:00:00 2001 From: Sergey Lyubka Date: Fri, 8 Feb 2013 10:10:02 +0000 Subject: [PATCH] Updated user manual --- UserManual.md | 307 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 182 insertions(+), 125 deletions(-) diff --git a/UserManual.md b/UserManual.md index f0d43545..39a2c8e0 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 -## Usage Examples +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: -- 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. + ** 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. -- 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 &` +All other characters in the pattern match themselves. Examples: -- How to serve user home directories using URL rewrite: - `mongoose -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/` + **.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 -``` - -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$" +# Configuration Options - -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: "" +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. - -G put_delete_passwords_file - PUT and DELETE passwords file. This must be specified if PUT or - DELETE methods are used. Default: "" +### 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. - -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: - "". +### 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`. - -P protect_uri - Comma separated list of URI=PATH pairs, specifying that given - URIs must be protected with respected password files. Default: "" +### put\_delete\_passwords_file +Passwords file for PUT and DELETE requests. Without it, PUT and DELETE requests +will fail. - -R authentication_domain - Authorization realm. Default: "mydomain.com" +### 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. - -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$" +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. - -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: "" +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`. - -a access_log_file - Access log file. Default: "", no logging is done. +### 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. - -d enable_directory_listing - Enable/disable directory listing. Default: "yes" +### authentication_domain `mydomain.com` +Authorization realm used in `.htpasswd` authorization. - -e error_log_file - Error log file. Default: "", no errors are logged. +### 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, `