.\" Process this file with .\" groff -man -Tascii mongoose.1 .\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $ .Dd Dec 1, 2008 .Dt mongoose 1 .Sh NAME .Nm mongoose .Nd lightweight web server .Sh SYNOPSIS .Nm .Op Ar options .Op Ar config_file .Nm .Fl A Ar htpasswd_file domain_name user_name password .Sh DESCRIPTION .Nm is small, fast and easy to use web server with CGI, SSL, Digest Authorization support. .Pp .Nm does not detach from terminal, and uses current working directory as the web root, unless .Fl root option is specified. .Pp It is possible to specify multiple ports to listen on. For example, to make .Nm listen on HTTP port 80 and HTTPS port 443, one should start it as .Dq mongoose -ssl_cert cert.pem -ports 80,443s . .Pp Options may be specified in any order, with one exception: if SSL listening port is specified in the -ports option, then -ssl_cert option must be set before -ports option. .Pp Unlike other web servers, .Nm does not expect CGI scripts to be put in a special directory. CGI scripts may be anywhere. CGI files are recognized by the file extension. .Pp SSI files are also recognized by extension. Unknown SSI directives are silently ignored. Currently, two SSI directives supported, "include" and "exec". For the "include" directive, included file name can be specified in three different ways. Below is the summary of supported SSI directives: .Bl -bullet .It Execute shell command. .It File path must be relative to the current document. .It File path must be relative to the document root. .It File path must be the absolute path. .El .Pp .Nm can use the configuration file. By default, it is "mongoose.conf", and if it is present in the same directory where .Nm lives, the command line options are read from it. Alternatively, the configuration file may be specified as a last argument. The format of the configuration file is exactly the same as for the command line options, the only difference is that the command line options must be specified on separate lines, and leading dashes for option names must be omitted. Lines beginning with '#' are regarded as comments and ignored. .Pp .Sh OPTIONS .Bl -tag -width indent .It Fl A Ar htpasswd_file domain_name user_name password Add/edit user's password in the passwords file. Deleting users can be done with any text editor. Functionality similar to Apache's .Ic htdigest utility. .It Fl access_log Ar file Access log file. Default: not set, no logging is done. .It Fl acl Ar (+|-)x.x.x.x[/x],... 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: not set, allow all. .It Fl admin_uri Ar uri If set, .Nm creates special administrative URI where options may be changed at runtime. This URI probably wants to be password-protected, look at .Fl protect option, and in the EXAMPLES section on how to do it. Default: not set. .It Fl aliases Ar list This options gives an ability to serve the directories outside web root by sort of symbolic linking to certain URI. The .Ar list must be comma-separated list of URI=PATH pairs, like this: "/etc/=/my_etc,/tmp=/my_tmp". Default: not set. .It Fl auth_PUT Ar file PUT and DELETE passwords file. This must be specified if PUT or DELETE methods are used. Default: not set. .It Fl auth_gpass Ar file Location of global passwords file. When set, per-directory .htpasswd files are ignored, and all accessed must be authorised against global passwords file. Default: not set. .It Fl auth_realm Ar domain_name Authorization realm. Default: "mydomain.com". .It Fl cgi_env Ar list Pass environment variables 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: not set. .It Fl cgi_ext Ar list Comma-separated list of CGI extensions. All files having these extensions are treated as CGI scripts. Default: "cgi,pl,php" .It Fl cgi_interp Ar file Force .Ar file to be a CGI interpreter for all CGI scripts. By default this option is not set, and .Nm decides which interpreter to use by looking at the first line of CGI script. .It Fl dir_list Ar yes|no Enable/disable directory listing. Default: "1" (enabled). .It Fl error_log Ar file Error log file. Default: not set, no errors are logged. .It Fl idle_time Ar num_seconds Number of seconds worker thread waits for some work before exit. Default: 10 .It Fl index_files Ar list Comma-separated list of files to be treated as directory index files. Default: index.html,index.htm,index.cgi .It Fl max_threads Ar number Maximum number of worker threads to start. Default: 100 .It Fl mime_types Ar list Additional to builtin mime types, in form "extension1=type1,extension2=type2,...". Extension must include dot. .It Fl ports Ar port_list Comma-separated list of ports to listen on. If the port is SSL, a letter 's' must be appeneded, for example, "-ports 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, "-ports 127.0.0.1:8080". Note that if SSL listening port is requested, then .Fl ssl_cert option must specified BEFORE .Fl ports option. Default: 8080 .It Fl protect Ar list Comma separated list of URI=PATH pairs, specifying that given URIs must be protected with respected password files. Default: not set. .It Fl root Ar directory Location of the WWW root directory. Default: working directory from which .Nm has been started. .It Fl ssi_ext Ar list Comma separated list of SSI extensions. Default: "shtml,shtm". .It Fl ssl_cert Ar pem_file Location of SSL certificate file. Default: not set. .It Fl uid Ar login Switch to given user after startup. Default: not set. .El .Pp .Sh EMBEDDING .Nm was designed to be embeddable into C/C++ applications. Since the source code is contained in single C file, it is fairly easy to embed it, and to follow the updates. Please refer to http://code.google.com/p/mongoose for details. .Pp .Sh EXAMPLES .Bl -tag -width indent .It Nm Fl root Ar /var/www Fl ssl_cert Ar /etc/cert.pem Fl ports Ar 8080,8043s Fl aliases Ar /aa=/tmp,/bb=/etc Start listening on port 8080 for HTTP, and 8043 for HTTPS connections. Use /etc/cert.pem as SSL certificate file. Web root is /var/www. In addition, map directory /tmp to URI /aa, directory /etc to URI /bb. .It Nm Fl acl Ar -0.0.0.0/0,+10.0.0.0/8,+1.2.3.4 Deny connections from everywhere, allow only IP address 1.2.3.4 and all IP addresses from 10.0.0.0/8 subnet to connect. .It Nm Fl admin_uri Ar /ctl Fl protect Ar /ctl=/tmp/passwords.txt Create an administrative URI "/ctl" where options may be changed at runtime, and protect that URI with authorization. .El .Pp .Sh COPYRIGHT .Nm is licensed under the terms of the MIT license. .Sh AUTHOR .An Sergey Lyubka Aq valenok@gmail.com .