diff --git a/README.md b/README.md index 4324bf82..1b03fd9a 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,34 @@ -# Project Mission +# Mongoose Web Server -Project mission is to provide easy to use, powerful, embeddable web server. +Mongoose easy to use, powerful, embeddable web server. Quick links: + * [Downloads](http://cesanta.com/#downloads) + * [Documentation](http://cesanta.com/#docs,Usage.md) + * [Mailing list](http://groups.google.com/group/mongoose-users) -# Downloads & Docs - -Sources, binaries and bundles are available for download at -[http://cesanta.com/#downloads](http://cesanta.com/#downloads). -User documentation is available at -[http://cesanta.com/#docs](http://cesanta.com/#docs,Usage.md). - -# Overview - -Mongoose keeps the balance between functionality and -simplicity by carefully selected list of features: +# Features - Works on Windows, Mac, UNIX/Linux, iPhone, Android, and many other platforms -- CGI, SSL, Digest auth, Websocket, WEbDAV -- Resumed download, URL rewrite, file blacklist, IP-based ACL, Windows service -- Scripting and database support (Lua Server Pages + Sqlite, see [page.lp](https://github.com/cesanta/mongoose/blob/master/build/test/page.lp) ), +- CGI, SSL, Digest auth, Websocket, WEbDAV, Resumed download, URL rewrite, file blacklist, IP-based ACL, Windows service +- Scripting and database support ([Lua](http://lua.org) + +[Sqlite](http://sqlite.org), see +[page.lp](https://github.com/cesanta/mongoose/blob/master/build/test/page.lp) ), which provides ready to go, powerful web development platform in one single-click executable with no dependencies - Simple and clean [embedding API](https://github.com/cesanta/mongoose/blob/master/mongoose.h). The source is in single [mongoose.c](https://github.com/cesanta/mongoose/blob/master/mongoose.c) file - to make embedding easy. + to make embedding easy - Extremely lightweight, has a core of under 40kB and tiny runtime footprint - Asyncronouns, non-blocking core supporting single- or multi-threaded usage - On the market since 2004, stable, mature and tested, - has man-years invested in continuous improvement and refinement - -Note that Windows and MacOS binaries have following 3rd party software -compiled in: - WolfSSL lightweight SSL library, - SQLite embedded database, - Lua embedded scripting engine. - -Questions can be asked at -[mongoose-users@googlegroups.com](http://groups.google.com/group/mongoose-users) -mailing list. + has several man-years invested in continuous improvement and refinement +- Professional support and consultancy available from +[Cesanta Software](http://cesanta.com), developer of Mongoose # Acknowledgements -Author is grateful to the following people who made their contribution: +Mongoose made better thanks to the contribution of following people: Arnout Vandecappelle, Benoît Amiaux, Boris Pek, Cody Hanson, Colin Leitner, Daniel Oaks, Eric Bakan, Erik Oomen, Filipp Kovalev, Ger Hobbelt, diff --git a/docs/Usage.md b/docs/Usage.md index f0cc9162..c9df71ea 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,64 +1,66 @@ -# Mongoose Usage Guide +# Mongoose User Guide -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. 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 +Mongoose is small and easy to use web server built on top of +mongoose library. It is designed with maximum simplicity in mind. For example, +to share any directory, just drop mongoose executable file in that directory, +double-click it (on UNIX, run it from shell) 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 +On Windows and Mac, Mongoose iconifies itself to the system tray when started. +Right-click on the icon pops up a menu, where it is possible to stop +mongoose, or configure it. + +On UNIX, `mongoose` is a command line utility. Running `mongoose` in terminal, optionally followed by configuration parameters (`mongoose [OPTIONS]`) or configuration file name (`mongoose [config_file_name]`) starts the -web server. Mongoose does not detach from terminal. Pressing `Ctrl-C` keys -would stop the server. +web server: + + $ mongoose -document_root /var/www # Running mongoose with cmdline options + $ mongoose /etc/my_config.txt # Running mongoose with config file + $ mongoose # Running with no parameters. This will + # serve current directory on port 8080 + +Mongoose does not detach from terminal. Pressing `Ctrl-C` keys +stops the server. 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. +If configuration file is specified explicitly in the command line, 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. 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: +command line argument name and it's value. Empty lines and lines beginning +with `#` are ignored. Here is the example of `mongoose.conf` file: - document_root c:\www - listening_ports 8080,8043s - ssl_certificate c:\mongoose\ssl_cert.pem + # This is a comment + document_root C:\www + listening_port 80 + ssl_certificate C:\mongoose\ssl_cert.pem -When configuration file is processed, mongoose process command line arguments, -if they are specified. Command line arguments therefore can override -configuration file settings. Command line arguments must start with `-`. -For example, if `mongoose.conf` has line +Command line arguments are highest priority and can override +configuration file settings. 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 options section below provide a good -overview of Mongoose features. +`mongoose -document_root /etc`, then `/etc` directory will be used as +document root. Note that configuration options on the command line must start with `-`, -but their names are the same as in the config file. All option names are -listed in the next section. Thus, the following two setups are equivalent: +and their names are the same as in the config file. Exampli gratia, +the following two setups are equivalent: - # Using command line arguments - $ mongoose -listening_ports 1234 -document_root /var/www + $ mongoose -listening_port 1234 -document_root /var/www - # Using config file - $ cat mongoose.conf + $ cat > mongoose.conf listening_ports 1234 document_root /var/www + ^D $ mongoose Mongoose can also be used to modify `.htpasswd` passwords file: - mongoose -A + $ mongoose -A .htpasswd mydomain.com user_name user_password 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 @@ -78,4 +80,6 @@ All other characters in the pattern match themselves. Examples: /foo Any string that begins with /foo **a$|**b$ Any string that ends with a or b +To restrict CGI files only to `/cgi-bin/` directory, use this setting: + $ mongoose -cgi_pattern /cgi-bin/*.cgi # Emulate /cgi-bin/ restriction