src/mongoose/mongoose.1 - external/p3/regal - Git at Google

 .\" Process this file with
 .\" groff -man -Tascii mongoose.1
 .\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $
 .Dd Sep 23, 2012
 .Dt mongoose 1
 .Sh NAME
 .Nm mongoose
 .Nd lightweight web server
 .Sh SYNOPSIS
 .Nm
 .Op Ar config_file
 .Op Ar OPTIONS
 .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, MD5 authorization,
 and basic SSI support.
 .Pp
 .Nm
 does not detach from terminal, and uses current working directory
 as the web root, unless
 .Fl r
 option is specified.
 It is possible to specify multiple ports to listen on. For example, to make
 mongoose listen on HTTP port 80 and HTTPS port 443, one should start it as:
 .Nm
 .Fl s Ar cert.pem Fl p Ar 80,443s
 .Pp
 Unlike other web servers,
 .Nm
 does not require CGI scripts be put in a special directory. CGI scripts can
 be anywhere. CGI (and SSI) files are recognized by the file name pattern.
 .Nm
 uses shell-like glob patterns with the following syntax:
 .Bl -tag -compact -width indent
 .It **
 Matches everything
 .It *
 Matches everything but slash character, '/'
 .It ?
 Matches any character
 .It $
 Matches the end of the string
 .It |
 Matches if pattern on the left side or the right side matches. Pattern on the
 left side is matched first
 .El
 All other characters in the pattern match themselves.
 .Pp
 If no arguments are given,
 .Nm
 searches for a configuration file called "mongoose.conf" in the same directory
 where mongoose binary is located. Alternatively, a file name could be
 specified in the command line. Format of the configuration file is the same
 as for the command line options except that each option must be specified
 on a separate line, leading dashes for option names must be omitted.
 Lines beginning with '#' and empty lines are 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 is similar to Apache's
 .Ic htdigest
 utility.
 .It Fl C Ar 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$"
 .It Fl E Ar 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: ""
 .It Fl G Ar put_delete_passwords_file
 PUT and DELETE passwords file. This must be specified if PUT or
 DELETE methods are used. Default: ""
 .It Fl I Ar cgi_interpreter
 Use
 .Ar 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: "".
 .It Fl P Ar protect_uri
 Comma separated list of URI=PATH pairs, specifying that given URIs
 must be protected with respected password files. Default: ""
 .It Fl R Ar authentication_domain
 Authorization realm. Default: "mydomain.com"
 .It Fl S Ar 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$"
 .It Fl T Ar throttle
 Limit download speed for clients.
 .Ar 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: ""
 .It Fl a Ar access_log_file
 Access log file. Default: "", no logging is done.
 .It Fl d Ar enable_directory_listing
 Enable/disable directory listing. Default: "yes"
 .It Fl e Ar error_log_file
 Error log file. Default: "", no errors are logged.
 .It Fl g Ar 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: ""
 .It Fl i Ar index_files
 Comma-separated list of files to be treated as directory index files.
 Default: "index.html,index.htm,index.cgi"
 .It Fl l Ar 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: ""
 .It Fl m Ar extra_mime_types
 Extra mime types to recognize, in form
 "extension1=type1,extension2=type2,...". Extension must include dot.
 Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: ""
 .It Fl p Ar 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"
 .It Fl r Ar document_root
 Location of the WWW root directory. Default: "."
 .It Fl s Ar ssl_certificate
 Location of SSL certificate file. Default: ""
 .It Fl t Ar num_threads
 Number of worker threads to start. Default: "10"
 .It Fl u Ar run_as_user
 Switch to given user's credentials after startup. Default: ""
 .It Fl w Ar url_rewrite_patterns
 Comma-separated list of URL rewrites in the form of
 "pattern=substitution,..." If the "pattern" matches some prefix
 of the requested URL, then matched prefix gets substituted with "substitution".
 For example, "-w /config=/etc,**.doc|**.rtf=/path/to/cgi-bin/handle_doc.cgi"
 will serve all URLs that start with "/config" from the "/etc" directory, and
 call handle_doc.cgi script for .doc and .rtf file requests. If some pattern
 matches, no further matching/substitution is performed
 (first matching pattern wins). Use full paths in substitutions. Default: ""
 .It Fl x Ar hide_files_patterns
 A prefix 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. Default: ""
 .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 follow the updates. Please refer to http://code.google.com/p/mongoose
 for details.
 .Pp
 .Sh EXAMPLES
 .Bl -tag -width indent
 .It Nm Fl r Ar /var/www Fl s Ar /etc/cert.pem Fl p Ar 8080,8043s
 Start serving files from /var/www. Listen on port 8080 for HTTP, and 8043
 for HTTPS connections.  Use /etc/cert.pem as SSL certificate file.
 .It Nm Fl l 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 w Ar **=/usr/bin/script.cgi
 Invoke /usr/bin/script.cgi for every incoming request, regardless of the URL.
 .El
 .Pp
 .Sh COPYRIGHT
 .Nm
 is licensed under the terms of the MIT license.
 .Sh AUTHOR
 .An Sergey Lyubka Aq valenok@gmail.com .
	.\" Process this file with
	.\" groff -man -Tascii mongoose.1
	.\" $Id: mongoose.1,v 1.12 2008/11/29 15:32:42 drozd Exp $
	.Dd Sep 23, 2012
	.Dt mongoose 1
	.Sh NAME
	.Nm mongoose
	.Nd lightweight web server
	.Sh SYNOPSIS
	.Nm
	.Op Ar config_file
	.Op Ar OPTIONS
	.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, MD5 authorization,
	and basic SSI support.
	.Pp
	.Nm
	does not detach from terminal, and uses current working directory
	as the web root, unless
	.Fl r
	option is specified.
	It is possible to specify multiple ports to listen on. For example, to make
	mongoose listen on HTTP port 80 and HTTPS port 443, one should start it as:
	.Nm
	.Fl s Ar cert.pem Fl p Ar 80,443s
	.Pp
	Unlike other web servers,
	.Nm
	does not require CGI scripts be put in a special directory. CGI scripts can
	be anywhere. CGI (and SSI) files are recognized by the file name pattern.
	.Nm
	uses shell-like glob patterns with the following syntax:
	.Bl -tag -compact -width indent
	.It **
	Matches everything
	.It *
	Matches everything but slash character, '/'
	.It ?
	Matches any character
	.It $
	Matches the end of the string
	.It \|
	Matches if pattern on the left side or the right side matches. Pattern on the
	left side is matched first
	.El
	All other characters in the pattern match themselves.
	.Pp
	If no arguments are given,
	.Nm
	searches for a configuration file called "mongoose.conf" in the same directory
	where mongoose binary is located. Alternatively, a file name could be
	specified in the command line. Format of the configuration file is the same
	as for the command line options except that each option must be specified
	on a separate line, leading dashes for option names must be omitted.
	Lines beginning with '#' and empty lines are 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 is similar to Apache's
	.Ic htdigest
	utility.
	.It Fl C Ar 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$"
	.It Fl E Ar 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: ""
	.It Fl G Ar put_delete_passwords_file
	PUT and DELETE passwords file. This must be specified if PUT or
	DELETE methods are used. Default: ""
	.It Fl I Ar cgi_interpreter
	Use
	.Ar 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: "".
	.It Fl P Ar protect_uri
	Comma separated list of URI=PATH pairs, specifying that given URIs
	must be protected with respected password files. Default: ""
	.It Fl R Ar authentication_domain
	Authorization realm. Default: "mydomain.com"
	.It Fl S Ar 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$"
	.It Fl T Ar throttle
	Limit download speed for clients.
	.Ar 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: ""
	.It Fl a Ar access_log_file
	Access log file. Default: "", no logging is done.
	.It Fl d Ar enable_directory_listing
	Enable/disable directory listing. Default: "yes"
	.It Fl e Ar error_log_file
	Error log file. Default: "", no errors are logged.
	.It Fl g Ar 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: ""
	.It Fl i Ar index_files
	Comma-separated list of files to be treated as directory index files.
	Default: "index.html,index.htm,index.cgi"
	.It Fl l Ar 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: ""
	.It Fl m Ar extra_mime_types
	Extra mime types to recognize, in form
	"extension1=type1,extension2=type2,...". Extension must include dot.
	Example: "mongoose -m .cpp=plain/text,.java=plain/text". Default: ""
	.It Fl p Ar 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"
	.It Fl r Ar document_root
	Location of the WWW root directory. Default: "."
	.It Fl s Ar ssl_certificate
	Location of SSL certificate file. Default: ""
	.It Fl t Ar num_threads
	Number of worker threads to start. Default: "10"
	.It Fl u Ar run_as_user
	Switch to given user's credentials after startup. Default: ""
	.It Fl w Ar url_rewrite_patterns
	Comma-separated list of URL rewrites in the form of
	"pattern=substitution,..." If the "pattern" matches some prefix
	of the requested URL, then matched prefix gets substituted with "substitution".
	For example, "-w /config=/etc,.doc\|.rtf=/path/to/cgi-bin/handle_doc.cgi"
	will serve all URLs that start with "/config" from the "/etc" directory, and
	call handle_doc.cgi script for .doc and .rtf file requests. If some pattern
	matches, no further matching/substitution is performed
	(first matching pattern wins). Use full paths in substitutions. Default: ""
	.It Fl x Ar hide_files_patterns
	A prefix 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. Default: ""
	.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 follow the updates. Please refer to http://code.google.com/p/mongoose
	for details.
	.Pp
	.Sh EXAMPLES
	.Bl -tag -width indent
	.It Nm Fl r Ar /var/www Fl s Ar /etc/cert.pem Fl p Ar 8080,8043s
	Start serving files from /var/www. Listen on port 8080 for HTTP, and 8043
	for HTTPS connections. Use /etc/cert.pem as SSL certificate file.
	.It Nm Fl l 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 w Ar **=/usr/bin/script.cgi
	Invoke /usr/bin/script.cgi for every incoming request, regardless of the URL.
	.El
	.Pp
	.Sh COPYRIGHT
	.Nm
	is licensed under the terms of the MIT license.
	.Sh AUTHOR
	.An Sergey Lyubka Aq valenok@gmail.com .