[2cbf1af] | 1 | .\" Process this file with |
---|
| 2 | .\" groff -man -Tascii mongoose.1 |
---|
| 3 | .\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $ |
---|
| 4 | .Dd Aug 31, 2010 |
---|
| 5 | .Dt mongoose 1 |
---|
| 6 | .Sh NAME |
---|
| 7 | .Nm mongoose |
---|
| 8 | .Nd lightweight web server |
---|
| 9 | .Sh SYNOPSIS |
---|
| 10 | .Nm |
---|
| 11 | .Op Ar config_file |
---|
| 12 | .Op Ar OPTIONS |
---|
| 13 | .Nm |
---|
| 14 | .Fl A Ar htpasswd_file domain_name user_name password |
---|
| 15 | .Sh DESCRIPTION |
---|
| 16 | .Nm |
---|
| 17 | is small, fast and easy to use web server with CGI, SSL, MD5 authorization, |
---|
| 18 | and basic SSI support. |
---|
| 19 | .Pp |
---|
| 20 | .Nm |
---|
| 21 | does not detach from terminal, and uses current working directory |
---|
| 22 | as the web root, unless |
---|
| 23 | .Fl r |
---|
| 24 | option is specified. |
---|
| 25 | It is possible to specify multiple ports to listen on. For example, to make |
---|
| 26 | mongoose listen on HTTP port 80 and HTTPS port 443, one should start it as: |
---|
| 27 | .Nm |
---|
| 28 | .Fl s Ar cert.pem Fl p Ar 80,443s |
---|
| 29 | .Pp |
---|
| 30 | Unlike other web servers, |
---|
| 31 | .Nm |
---|
| 32 | does not require CGI scripts be put in a special directory. CGI scripts can |
---|
| 33 | be anywhere. CGI (and SSI) files are recognized by the file name pattern. |
---|
| 34 | .Nm |
---|
| 35 | uses shell-like glob patterns with the following syntax: |
---|
| 36 | .Bl -tag -compact -width indent |
---|
| 37 | .It ** |
---|
| 38 | Matches everything |
---|
| 39 | .It * |
---|
| 40 | Matches everything but slash character, '/' |
---|
| 41 | .It ? |
---|
| 42 | Matches any character |
---|
| 43 | .It $ |
---|
| 44 | Matches the end of the string |
---|
| 45 | .It | |
---|
| 46 | Matches if pattern on the left side or the right side matches. Pattern on the |
---|
| 47 | left side is matched first |
---|
| 48 | .El |
---|
| 49 | All other characters in the pattern match themselves. |
---|
| 50 | .Pp |
---|
| 51 | If no arguments are given, |
---|
| 52 | .Nm |
---|
| 53 | searches for a configuration file called "mongoose.conf" in the same directory |
---|
| 54 | where mongoose binary is located. Alternatively, a file name could be |
---|
| 55 | specified in the command line. Format of the configuration file is the same |
---|
| 56 | as for the command line options except that each option must be specified |
---|
| 57 | on a separate line, leading dashes for option names must be omitted. |
---|
| 58 | Lines beginning with '#' and empty lines are ignored. |
---|
| 59 | .Pp |
---|
| 60 | .Sh OPTIONS |
---|
| 61 | .Bl -tag -width indent |
---|
| 62 | .It Fl A Ar htpasswd_file domain_name user_name password |
---|
| 63 | Add/edit user's password in the passwords file. Deleting users can be done |
---|
| 64 | with any text editor. Functionality is similar to Apache's |
---|
| 65 | .Ic htdigest |
---|
| 66 | utility. |
---|
| 67 | .It Fl C Ar cgi_pattern |
---|
| 68 | All files that fully match cgi_pattern are treated as CGI. |
---|
| 69 | Default pattern allows CGI files be |
---|
| 70 | anywhere. To restrict CGIs to certain directory, use e.g. "-C /cgi-bin/**.cgi". |
---|
| 71 | Default: "**.cgi$|**.pl$|**.php$" |
---|
| 72 | .It Fl E Ar cgi_environment |
---|
| 73 | Extra environment variables to be passed to the CGI script in addition to |
---|
| 74 | standard ones. The list must be comma-separated list of X=Y pairs, like this: |
---|
| 75 | "VARIABLE1=VALUE1,VARIABLE2=VALUE2". Default: "" |
---|
| 76 | .It Fl G Ar put_delete_passwords_file |
---|
| 77 | PUT and DELETE passwords file. This must be specified if PUT or |
---|
| 78 | DELETE methods are used. Default: "" |
---|
| 79 | .It Fl I Ar cgi_interpreter |
---|
| 80 | Use |
---|
| 81 | .Ar cgi_interpreter |
---|
| 82 | as a CGI interpreter for all CGI scripts regardless script extension. |
---|
| 83 | Mongoose decides which interpreter to use by looking at |
---|
| 84 | the first line of a CGI script. Default: "". |
---|
| 85 | .It Fl M Ar max_request_size |
---|
| 86 | Maximum HTTP request size in bytes. Default: "16384" |
---|
| 87 | .It Fl P Ar protect_uri |
---|
| 88 | Comma separated list of URI=PATH pairs, specifying that given URIs |
---|
| 89 | must be protected with respected password files. Default: "" |
---|
| 90 | .It Fl R Ar authentication_domain |
---|
| 91 | Authorization realm. Default: "mydomain.com" |
---|
| 92 | .It Fl S Ar ssi_pattern |
---|
| 93 | All files that fully match ssi_pattern are treated as SSI. |
---|
| 94 | Unknown SSI directives are silently ignored. Currently, two SSI directives |
---|
| 95 | are supported, "include" and "exec". Default: "**.shtml$|**.shtm$" |
---|
| 96 | .It Fl a Ar access_log_file |
---|
| 97 | Access log file. Default: "", no logging is done. |
---|
| 98 | .It Fl d Ar enable_directory_listing |
---|
| 99 | Enable/disable directory listing. Default: "yes" |
---|
| 100 | .It Fl e Ar error_log_file |
---|
| 101 | Error log file. Default: "", no errors are logged. |
---|
| 102 | .It Fl g Ar global_passwords_file |
---|
| 103 | Location of a global passwords file. If set, per-directory .htpasswd files are |
---|
| 104 | ignored, and all requests must be authorised against that file. Default: "" |
---|
| 105 | .It Fl i Ar index_files |
---|
| 106 | Comma-separated list of files to be treated as directory index files. |
---|
| 107 | Default: "index.html,index.htm,index.cgi" |
---|
| 108 | .It Fl l Ar access_control_list |
---|
| 109 | Specify access control list (ACL). ACL is a comma separated list |
---|
| 110 | of IP subnets, each subnet is prepended by '-' or '+' sign. Plus means allow, |
---|
| 111 | minus means deny. If subnet mask is |
---|
| 112 | omitted, like "-1.2.3.4", then it means single IP address. Mask may vary |
---|
| 113 | from 0 to 32 inclusive. On each request, full list is traversed, and |
---|
| 114 | last match wins. Default setting is to allow all. For example, to allow only |
---|
| 115 | 192.168/16 subnet to connect, run "mongoose -0.0.0.0/0,+192.168/16". |
---|
| 116 | Default: "" |
---|
| 117 | .It Fl m Ar extra_mime_types |
---|
| 118 | Extra mime types to recognize, in form |
---|
| 119 | "extension1=type1,extension2=type2,...". Extension must include dot. |
---|
| 120 | Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: "" |
---|
| 121 | .It Fl p Ar listening_ports |
---|
| 122 | Comma-separated list of ports to listen on. If the port is SSL, a letter 's' |
---|
| 123 | must be appeneded, for example, "-p 80,443s" will open port 80 and port 443, |
---|
| 124 | and connections on port 443 will be SSL-ed. It is possible to specify an |
---|
| 125 | IP address to bind to. In this case, an IP address and a colon must be |
---|
| 126 | prepended to the port number. For example, to bind to a loopback interface |
---|
| 127 | on port 80 and to all interfaces on HTTPS port 443, use |
---|
| 128 | "mongoose -p 127.0.0.1:80,443s". Default: "8080" |
---|
| 129 | .It Fl r Ar document_root |
---|
| 130 | Location of the WWW root directory. Default: "." |
---|
| 131 | .It Fl s Ar ssl_certificate |
---|
| 132 | Location of SSL certificate file. Default: "" |
---|
| 133 | .It Fl t Ar num_threads |
---|
| 134 | Number of worker threads to start. Default: "10" |
---|
| 135 | .It Fl u Ar run_as_user |
---|
| 136 | Switch to given user's credentials after startup. Default: "" |
---|
| 137 | .It Fl w Ar url_rewrite_patterns |
---|
| 138 | Comma-separated list of URL rewrites in the form of |
---|
| 139 | "pattern=substitution,..." If the "pattern" matches some prefix |
---|
| 140 | of the requested URL, then matched prefix gets substituted with "substitution". |
---|
| 141 | For example, "-w /config=/etc,**.doc|**.rtf=/path/to/cgi-bin/handle_doc.cgi" |
---|
| 142 | will serve all URLs that start with "/config" from the "/etc" directory, and |
---|
| 143 | call handle_doc.cgi script for .doc and .rtf file requests. If some pattern |
---|
| 144 | matches, no further matching/substitution is performed |
---|
| 145 | (first matching pattern wins). Use full paths in substitutions. Default: "" |
---|
| 146 | .It Fl x Ar thread_stack_size |
---|
| 147 | Use the given amount of stack for each thread. Default: "" |
---|
| 148 | .It Fl y Ar thread_priority |
---|
| 149 | Use the given priority for all posix threads. If this option is used without the |
---|
| 150 | thread_policy option, the systems default scheduling policy will be used for the |
---|
| 151 | threads instead of inheriting the policy of the creating thread. Default: "" |
---|
| 152 | .It Fl z Ar thread_policy |
---|
| 153 | Select the posix scheduling policy for the threads. Possible Values are 's' for |
---|
| 154 | sporadic (not on all systems available), 'r' for round robin, 'f' for fifo or |
---|
| 155 | 'o' for other scheduling strategie. If this option is used without the |
---|
| 156 | thread_priority option, the systems default priority will be used for the |
---|
| 157 | threads instead of inheriting the priority of the creating thread. Default: "" |
---|
| 158 | .El |
---|
| 159 | .Pp |
---|
| 160 | .Sh EMBEDDING |
---|
| 161 | .Nm |
---|
| 162 | was designed to be embeddable into C/C++ applications. Since the |
---|
| 163 | source code is contained in single C file, it is fairly easy to embed it |
---|
| 164 | and follow the updates. Please refer to http://code.google.com/p/mongoose |
---|
| 165 | for details. |
---|
| 166 | .Pp |
---|
| 167 | .Sh EXAMPLES |
---|
| 168 | .Bl -tag -width indent |
---|
| 169 | .It Nm Fl r Ar /var/www Fl s Ar /etc/cert.pem Fl p Ar 8080,8043s |
---|
| 170 | Start serving files from /var/www. Listen on port 8080 for HTTP, and 8043 |
---|
| 171 | for HTTPS connections. Use /etc/cert.pem as SSL certificate file. |
---|
| 172 | .It Nm Fl l Ar -0.0.0.0/0,+10.0.0.0/8,+1.2.3.4 |
---|
| 173 | Deny connections from everywhere, allow only IP address 1.2.3.4 and |
---|
| 174 | all IP addresses from 10.0.0.0/8 subnet to connect. |
---|
| 175 | .It Nm Fl w Ar **=/usr/bin/script.cgi |
---|
| 176 | Invoke /usr/bin/script.cgi for every incoming request, regardless of the URL. |
---|
| 177 | .El |
---|
| 178 | .Pp |
---|
| 179 | .Sh COPYRIGHT |
---|
| 180 | .Nm |
---|
| 181 | is licensed under the terms of the MIT license. |
---|
| 182 | .Sh AUTHOR |
---|
| 183 | .An Sergey Lyubka Aq valenok@gmail.com . |
---|