MONGOOSE(1)

📦 version 3.1, in fedora 43, fedora 44

✨ MONGOOSE 💖

okay bestie, gather round, because we're about to talk about mongoose(1) — the lightweight web server that is literally the moment. small, fast, easy to use, and it does CGI, SSL, MD5 authorization, and basic SSI support. she's giving tiny but mighty. 👑

🌸 SYNOPSIS 🌸

mongoose [config_file] [OPTIONS]
mongoose -A htpasswd_file domain_name user_name password

🦋 DESCRIPTION 🦋

so mongoose is a small, fast, easy-to-use web server with CGI, SSL, MD5 authorization, and basic SSI support. no cap.

here's the tea: mongoose does not detach from terminal — she stays right there with you, main character that she is — and she uses the current working directory as the web root, unless you hit her with the -r option. 💅

you can absolutely specify multiple ports to listen on. for example, to make mongoose listen on HTTP port 80 and HTTPS port 443, you'd start her like this:

mongoose -s cert.pem -p 80,443s

and here's the iconic part: unlike other web servers, mongoose does not require CGI scripts to be put in a special directory. CGI scripts can be anywhere. she's not gonna put your faves in a box. CGI (and SSI) files are recognized by the file name pattern. mongoose uses shell-like glob patterns with this syntax:

  • ** — 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. Pattern on the left side is matched first
  • all other characters in the pattern match themselves.

if no arguments are given, mongoose searches for a configuration file called "mongoose.conf" in the same directory where the mongoose binary is located. alternatively, a file name could be specified in the command line. the 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

✨ OPTIONS ✨

  • -A htpasswd_file domain_name user_name password — add/edit a user's password in the passwords file. deleting users can be done with any text editor (go off, honestly). functionality is similar to Apache's htdigest utility.
  • -C cgi_pattern — all files that fully match cgi_pattern are treated as CGI. the default pattern allows CGI files to be anywhere. to restrict CGIs to a 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 the standard ones. the list must be a 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 of script extension. mongoose decides which interpreter to use by looking at the first line of a CGI script. Default: "".
  • -M max_request_size — maximum HTTP request size in bytes. Default: "16384"
  • -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 (she's not gonna make it weird). currently, two SSI directives are supported: "include" and "exec". Default: "**.shtml$|**.shtm$"
  • -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 a '-' or '+' sign. plus means allow, minus means deny. if the 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, the full list is traversed, and last match wins. the default setting is to allow all. for example, to allow only the 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,extension2=type2,...". extension must include the 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 appended, 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 the SSL certificate file. Default: ""
  • -t num_threads — number of worker threads to start. Default: "10"
  • -u run_as_user — switch to the given user's credentials after startup. Default: ""
  • -w 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 the matched prefix gets substituted with "substitution". for example, "-w /config=/etc,**.doc|**.rtf=/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). Default: ""

🧚 EMBEDDING 🧚

mongoose was designed to be embeddable into C/C++ applications. since the source code is contained in a 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. 🫶

🌈 EXAMPLES 🌈

  • mongoose -r /var/www -s /etc/cert.pem -p 8080,8043s start serving files from /var/www. listen on port 8080 for HTTP, and 8043 for HTTPS connections. use /etc/cert.pem as the SSL certificate file.
  • mongoose -l -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 the 10.0.0.0/8 subnet to connect.
  • mongoose -w **=/my/script.cgi invoke /my/script.cgi for every incoming request, regardless of the URL. obsessed. 💖

mongoose is licensed under the terms of the MIT license.

🎀 AUTHOR 🎀

Sergey Lyubka <valenok@gmail.com>.

okay bestie that's the whole page, no gatekeeping 💅 this was the mongoose(1) manual, dated Aug 31, 2010 — go forth and serve some files, you've got this fr fr 🌸🦋✨

📦 where this page comes from