mirror of
https://github.com/cesanta/mongoose.git
synced 2024-11-28 21:59:02 +08:00
Fossa merge.
PUBLISHED_FROM=12ccba10358075024a1195cd0b0c1ea132aae6a3
This commit is contained in:
Sergey Lyubka
parent
75aadb3e79
commit
b99dc95b1d
249
docs/API.md
249
docs/API.md
@ -1,249 +0,0 @@
|
||||
# Mongoose API Reference
|
||||
|
||||
struct mg_server *mg_create_server(void *server_param, mg_handler_t handler);
|
||||
|
||||
Creates web server instance. Returns opaque instance pointer, or NULL if
|
||||
there is not enough memory. `server_param`: Could be any pointer, or NULL.
|
||||
This pointer will be passed
|
||||
to the callback functions as `struct mg_connection::server_param` field.
|
||||
A common use case is to pass `this` pointer of the C++ wrapper class
|
||||
as `user_param`, to let the callback get the pointer to the C++ object.
|
||||
|
||||
Note that this function doesn't make the
|
||||
server instance to serve. Serving is done by `mg_poll_server()` function.
|
||||
Mongoose has single-threaded, event-driven, asynchronous, non-blocking core.
|
||||
When server instance is created, it contains an information about
|
||||
the configuration and the state of each connection.
|
||||
Server instance is capable on listening on only one port. After creation,
|
||||
`struct mg_server` has a list
|
||||
of active connections and configuration parameters.
|
||||
|
||||
Side-effect: on UNIX, `mg_create_server()` ignores SIGPIPE signals. If custom
|
||||
processing is required SIGPIPE, signal handler must be set up after
|
||||
calling `mg_create_server()`.
|
||||
|
||||
Important: Mongoose does not install `SIGCHLD` handler. If CGI is used,
|
||||
`SIGCHLD` handler must be set up to reap CGI zombie processes.
|
||||
|
||||
|
||||
void mg_destroy_server(struct mg_server **server);
|
||||
|
||||
Deallocates web server instance, closes all pending connections, and makes
|
||||
server pointer a NULL pointer.
|
||||
|
||||
const char mg_set_option(struct mg_server *server, const char *name,
|
||||
const char *value);
|
||||
|
||||
Sets a particular server option. Note that at least one option,
|
||||
`listening_port`, must be specified. To serve static files, `document_root`
|
||||
must be specified too. If `document_root` option is left unset, Mongoose
|
||||
will not access filesystem at all. `mg_set_option()` returns NULL if option was
|
||||
set successfully, otherwise it returns human-readable error string. It is
|
||||
allowed to call `mg_set_option()` by the same thread that does
|
||||
`mg_poll_server()` (Mongoose thread) and change server configuration while it
|
||||
is serving, in between `mg_poll_server()` calls.
|
||||
|
||||
int mg_poll_server(struct mg_server *server, int milliseconds);
|
||||
|
||||
Performs one iteration of IO loop by iterating over all
|
||||
active connections, performing `select()` syscall on all sockets with a timeout
|
||||
of `milliseconds`. When `select()` returns, Mongoose
|
||||
does an IO for each socket that has data to be sent or received. Application
|
||||
code must call `mg_poll_server()` in a loop. It is an error to have more then
|
||||
one thread calling `mg_poll_server()`, `mg_set_option()` or any other function
|
||||
that take `struct mg_server *` parameter. Mongoose does not
|
||||
mutex-protect `struct mg_server *`, therefore only single thread
|
||||
(Mongoose thread) should make Mongoose calls.
|
||||
|
||||
`mg_poll_server()` calls user-specified event handler when certain events
|
||||
occur. Sequence of events for the accepted connection is this:
|
||||
|
||||
* `MG_AUTH` - Mongoose asks whether this connection is authorized. If event
|
||||
handler returns `MG_FALSE`, then Mongoose does not serve the request but
|
||||
sends authorization request to the client. If `MG_TRUE` is returned,
|
||||
then Mongoose continues on with the request.
|
||||
* `MG_REQUEST` - Mongoose asks event handler to serve the request. If
|
||||
event handler serves the request by sending a reply,
|
||||
it should return `MG_TRUE`. Otherwise,
|
||||
it should return `MG_FALSE` which tells Mongoose that request is not
|
||||
served and Mongoose should serve it. For example, event handler might
|
||||
choose to serve only RESTful API requests with URIs that start with
|
||||
certain prefix, and let Mongoose serve all static files.
|
||||
If event handler decides to serve the request, but doesn't have
|
||||
all the data at the moment, it should return `MG_MORE`. That tells
|
||||
Mongoose to keep the connection open after callback returns.
|
||||
|
||||
`mg_connection::connection_param` pointer is a placeholder to keep
|
||||
user-specific data. For example, handler could decide to open a DB
|
||||
connection and store DB connection handle in `connection_param`.
|
||||
* `MG_POLL` is sent to every connection on every iteration of
|
||||
`mg_poll_server()`. Event handler should return `MG_FALSE` to ignore
|
||||
this event. If event handler returns `MG_TRUE`, then Mongoose assumes
|
||||
that event handler has finished sending data, and Mongoose will
|
||||
close the connection.
|
||||
* `MG_HTTP_ERROR` sent when Mongoose is about to send HTTP error back
|
||||
to the client. Event handler can choose to send a reply itself, in which
|
||||
case event handler must return `MG_TRUE`. Otherwise, event handler must
|
||||
return `MG_FALSE`.
|
||||
* `MG_CLOSE` is sent when the connection is closed. This event is used
|
||||
to cleanup per-connection state stored in `connection_param`
|
||||
if it was allocated. Event handler return value is ignored.
|
||||
|
||||
Sequence of events for the client connection is this:
|
||||
|
||||
* `MG_CONNECT` sent when Mongoose has connected to the remote host.
|
||||
This event is sent to the connection initiated by `mg_connect()` call.
|
||||
Connection status is held in `mg_connection::status_code`: if zero,
|
||||
then connection was successful, otherwise connection was not established.
|
||||
User should send a request upon successful connection.
|
||||
Event handler should return `MG_TRUE` if connection was successful and
|
||||
HTTP request has been sent. Otherwise, it should send `MG_FALSE`.
|
||||
* `MG_REPLY` is sent when response has been received from the remote host.
|
||||
If event handler sends another request, then it should return `MG_TRUE`.
|
||||
Otherwise it should return `MG_FALSE` and Mongoose will close the connection.
|
||||
* `MG_CLOSE` same as for the accepted connection.
|
||||
|
||||
|
||||
When mongoose buffers in HTTP request and successfully parses it, it sends
|
||||
`MG_REQUEST` event for GET requests immediately. For POST requests,
|
||||
Mongoose delays the call until the whole POST request is buffered in memory.
|
||||
POST data is available to the callback as `struct mg_connection::content`,
|
||||
and POST data length is in `struct mg_connection::content_len`.
|
||||
|
||||
Note that websocket connections are treated the same way. Mongoose buffers
|
||||
websocket frame in memory, and calls event handler when frame is fully
|
||||
buffered. Frame data is available `struct mg_connection::content`, and
|
||||
data length is in `struct mg_connection::content_len`, i.e. very similar to
|
||||
the POST request. `struct mg_connection::is_websocket` flag indicates
|
||||
whether the request is websocket or not. Also, for websocket requests,
|
||||
there is `struct mg_connection::wsbits` field which contains first byte
|
||||
of the websocket frame which URI handler can examine. Note that to
|
||||
reply to the websocket client, `mg_websocket_write()` should be used.
|
||||
To reply to the plain HTTP client, `mg_write_data()` should be used.
|
||||
|
||||
Return value: number of active connections.
|
||||
|
||||
|
||||
const char **mg_get_valid_option_names(void);
|
||||
|
||||
Returns a NULL-terminated array of option names and their default values.
|
||||
There are two entries per option in an array: an option name followed by a
|
||||
default value. A default value could be NULL. A NULL name indicates an end
|
||||
of the array.
|
||||
|
||||
const char *mg_get_option(const struct mg_server *server, const char *name);
|
||||
|
||||
Returns the value of particular configuration parameter. If
|
||||
given parameter name is not valid, NULL is returned. For valid names, return
|
||||
value is guaranteed to be non-NULL. If parameter is not set, zero-length string
|
||||
is returned.
|
||||
|
||||
void mg_wakeup_server_ex(struct mg_server *, mg_handler_t func,
|
||||
const char *fmt, ...);
|
||||
|
||||
Sends string message to a server. Function `func` is called for every active
|
||||
connection. String message is passed in `struct mg_connection::callback_param`.
|
||||
This function is designed to push data to the connected clients, and
|
||||
can be called from any thread. There is a limitation on the length of
|
||||
the message, currently at 8 kilobytes.
|
||||
|
||||
void mg_send_status(struct mg_connection *, int status_code);
|
||||
void mg_send_header(struct mg_connection *, const char *name,
|
||||
const char *value);
|
||||
void mg_send_data(struct mg_connection *, const void *data, int data_len);
|
||||
void mg_printf_data(struct mg_connection *, const char *format, ...);
|
||||
|
||||
These functions are used to construct a response to the client. HTTP response
|
||||
consists of three parts: a status line, zero or more HTTP headers,
|
||||
a response body. Mongoose provides functions for all three parts:
|
||||
* `mg_send_status()` is used to create status line. This function can be
|
||||
called zero or once. If `mg_send_status()` is not called, then Mongoose
|
||||
will send status 200 (success) implicitly.
|
||||
* `mg_send_header()` adds HTTP header to the response. This function could
|
||||
be called zero or more times.
|
||||
* `mg_send_data()` and `mg_printf_data()` are used to send data to the
|
||||
client. Note that Mongoose adds `Transfer-Encoding: chunked` header
|
||||
implicitly, and sends data in chunks. Therefore, it is not necessary to
|
||||
set `Content-Length` header. Note that `mg_send_data()` and
|
||||
`mg_printf_data()` do not send data immediately. Instead, they spool
|
||||
data in memory, and Mongoose sends that data later after URI handler
|
||||
returns. If data to be sent is huge, an URI handler might
|
||||
send data in pieces by saving state in
|
||||
`struct mg_connection::connection_param` variable and returning `0`. Then
|
||||
Mongoose will call a handler repeatedly after each socket write.
|
||||
|
||||
<!-- -->
|
||||
|
||||
void mg_send_file(struct mg_connection *, const char *path);
|
||||
|
||||
Tells Mongoose to serve given file. Mongoose handles file according to
|
||||
it's extensions, i.e. Mongoose will invoke CGI script if `path` has CGI
|
||||
extension, it'll render SSI file if `path` has SSI extension, etc. If `path`
|
||||
points to a directory, Mongoose will show directory listing. If this function
|
||||
is used, no calls to `mg_send*` or `mg_printf*` functions must be made, and
|
||||
event handler must return `MG_MORE`.
|
||||
|
||||
size_t mg_websocket_write(struct mg_connection* conn, int opcode,
|
||||
const char *data, size_t data_len);
|
||||
size_t mg_websocket_printf(struct mg_connection* conn, int opcode,
|
||||
const char *fmt, ...);
|
||||
|
||||
|
||||
Similar to `mg_write()` and `mg_printf()`, but wraps the data into a
|
||||
websocket frame with a given websocket `opcode`.
|
||||
|
||||
const char *mg_get_header(const struct mg_connection *, const char *name);
|
||||
|
||||
Get the value of particular HTTP header. This is a helper function.
|
||||
It traverses http_headers array, and if the header is present in the array,
|
||||
returns its value. If it is not present, NULL is returned.
|
||||
|
||||
|
||||
int mg_get_var(const struct mg_connection *conn, const char *var_name,
|
||||
char *buf, size_t buf_len);
|
||||
|
||||
Gets HTTP form variable. Both POST buffer and query string are inspected.
|
||||
Form variable is url-decoded and written to the buffer. On success, this
|
||||
function returns the length of decoded variable. On error, -1 is returned if
|
||||
variable not found, and -2 is returned if destination buffer is too small
|
||||
to hold the variable. Destination buffer is guaranteed to be
|
||||
'\0' - terminated if it is not NULL or zero length.
|
||||
|
||||
int mg_parse_header(const char *hdr, const char *var_name, char *buf,
|
||||
size_t buf_size);
|
||||
|
||||
This function parses HTTP header and fetches given variable's value in a buffer.
|
||||
A header should be like `x=123, y=345, z="other value"`. This function is
|
||||
designed to parse Cookie headers, Authorization headers, and similar. Returns
|
||||
the length of the fetched value, or 0 if variable not found.
|
||||
|
||||
int mg_modify_passwords_file(const char *passwords_file_name,
|
||||
const char *domain,
|
||||
const char *user,
|
||||
const char *password);
|
||||
|
||||
Add, edit or delete the entry in the passwords file.
|
||||
This function allows an application to manipulate .htpasswd files on the
|
||||
fly by adding, deleting and changing user records. This is one of the
|
||||
several ways of implementing authentication on the server side.
|
||||
If password is not NULL, entry is added (or modified if already exists).
|
||||
If password is NULL, entry is deleted.
|
||||
Return: 1 on success, 0 on error.
|
||||
|
||||
|
||||
int mg_parse_multipart(const char *buf, int buf_len,
|
||||
char *var_name, int var_name_len,
|
||||
char *file_name, int file_name_len,
|
||||
const char **data, int *data_len);
|
||||
|
||||
Parses a buffer that contains multipart form data. Stores chunk name
|
||||
in a `var_name` buffer. If chunk is an uploaded file, then `file_name`
|
||||
will have a file name. `data` and `data_len` will point to the chunk data.
|
||||
Returns number of bytes to skip to the next chunk.
|
||||
|
||||
struct mg_connection *mg_connect(struct mg_server *server,
|
||||
const char *host, int port, int use_ssl);
|
||||
|
||||
Create connection to the remote host. Returns `NULL` on error, non-null
|
||||
if the connection has been scheduled for connection. Upon a connection,
|
||||
Mongoose will send `MG_CONNECT` event to the event handler.
|
||||
@ -1,27 +0,0 @@
|
||||
# Mongoose Build on Android
|
||||
|
||||
This is a small guide to help you run mongoose on Android. Currently it is
|
||||
tested on the HTC Wildfire. If you have managed to run it on other devices
|
||||
as well, please comment or drop an email in the mailing list.
|
||||
Note : You dont need root access to run mongoose on Android.
|
||||
|
||||
- Clone Mongoose Git repo
|
||||
- Download the Android NDK from [http://developer.android.com/tools/sdk/ndk/index.html](http://developer.android.com/tools/sdk/ndk/index.html)
|
||||
- Run `/path-to-ndk/ndk-build -C /path/to/mongoose`
|
||||
That should generate mongoose/lib/armeabi/mongoose
|
||||
- Using the adb tool (you need to have Android SDK installed for that),
|
||||
push the generated mongoose binary to `/data/local` folder on device.
|
||||
- From adb shell, navigate to `/data/local` and execute `./mongoose`.
|
||||
- To test if the server is running fine, visit your web-browser and
|
||||
navigate to `http://127.0.0.1:8080` You should see the `Index of /` page.
|
||||
|
||||
|
||||
|
||||
|
||||
Notes:
|
||||
|
||||
- `jni` stands for Java Native Interface. Read up on Android NDK if you want
|
||||
to know how to interact with the native C functions of mongoose in Android
|
||||
Java applications.
|
||||
- TODO: A Java application that interacts with the native binary or a
|
||||
shared library.
|
||||
@ -1,34 +0,0 @@
|
||||
How To Create Basic Website With Mongoose
|
||||
===========================================
|
||||
|
||||
## 1. Create a directory which will contain your website files. For example, on drive `C:\`, create a directory called `my_website`:
|
||||
|
||||
|
||||
|
||||
## 2. Inside `my_website` directory, create a new file called "index". This will be the default web page shown when the website is visited.
|
||||
|
||||
|
||||
|
||||
## 3. Open index file with your favorite editor (for example, Notepad) and enter some HTML code:
|
||||
|
||||
|
||||
|
||||
## 4. Save this file as `index.html`:
|
||||
|
||||
|
||||
|
||||
|
||||
## 5. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside `my_website` directory:
|
||||
|
||||
|
||||
|
||||
## 6. Double-click mongoose executable. An icon will appear on a system tray in the bottom right corner of the desktop:
|
||||
|
||||
|
||||
|
||||
## 7. Click on the mongoose icon and choose "Go to my address" menu:
|
||||
|
||||
|
||||
## 8. A browser will popup displaying `index.html` file. Now, you can expand your website by adding more content.
|
||||
|
||||
|
||||
173
docs/Embed.md
173
docs/Embed.md
@ -1,173 +0,0 @@
|
||||
# Mongoose Embedding Guide
|
||||
|
||||
Embedding Mongoose is done in two steps:
|
||||
|
||||
1. Copy
|
||||
[mongoose.c](https://raw.github.com/cesanta/mongoose/master/mongoose.c) and
|
||||
[mongoose.h](https://raw.github.com/cesanta/mongoose/master/mongoose.h)
|
||||
to your application's source tree and include them in the build.
|
||||
2. Somewhere in the application code, call `mg_create_server()` to create
|
||||
a server, configure it with `mg_set_option()` and loop with
|
||||
`mg_poll_server()` until done. Call `mg_destroy_server()` to cleanup.
|
||||
|
||||
Here's a minimal application `app.c` that embeds mongoose:
|
||||
|
||||
#include "mongoose.h"
|
||||
|
||||
int main(void) {
|
||||
struct mg_server *server = mg_create_server(NULL, NULL);
|
||||
mg_set_option(server, "document_root", "."); // Serve current directory
|
||||
mg_set_option(server, "listening_port", "8080"); // Open port 8080
|
||||
|
||||
for (;;) {
|
||||
mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
|
||||
}
|
||||
mg_destroy_server(&server);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
To compile it, put `mongoose.c`, `mongoose.h` and `app.c` into one
|
||||
folder, start terminal on UNIX or Visual Studio command line prompt on Windows,
|
||||
and run the following command:
|
||||
|
||||
cc app.c mongoose.c -pthread -o app # on Unix
|
||||
cl.exe app.c mongoose.c /TC /MD # on Windows
|
||||
|
||||
When run, this simple application opens port 8080 and serves static files,
|
||||
CGI files and lists directory content in the current working directory.
|
||||
|
||||
It is possible to generate HTML page content. Mongoose can call user-defined
|
||||
function when certain events occur.
|
||||
That function is called _an event handler_, and it is the second parameter
|
||||
to `mg_create_server()` function. Here is the example event handler function:
|
||||
|
||||
int event_handler(struct mg_connection *conn, enum mg_event ev) {
|
||||
switch (ev) {
|
||||
case MG_AUTH: return MG_TRUE;
|
||||
default: return MG_FALSE;
|
||||
}
|
||||
}
|
||||
|
||||
Event handler is called by Mongoose with `struct mg_connection *`
|
||||
pointer and an event number. `struct mg_connection *conn`
|
||||
has all information about the request: HTTP headers, POST or websocket
|
||||
data buffer, etcetera. `enum mg_event ev` tells which exactly event is sent.
|
||||
For each event, an event handler returns a value which tells Mongoose how
|
||||
to behave.
|
||||
|
||||
The sequence of events for every connection is this:
|
||||
|
||||
* `MG_AUTH` - Mongoose asks whether this connection is authorized. If event
|
||||
handler returns `MG_FALSE`, then Mongoose does not serve the request but
|
||||
sends authorization request to the client. If `MG_TRUE` is returned,
|
||||
then Mongoose continues on with the request.
|
||||
* `MG_REQUEST` - Mongoose asks event handler to serve the request. If
|
||||
event handler serves the request by sending a reply,
|
||||
it should return `MG_TRUE`. Otherwise,
|
||||
it should return `MG_FALSE` which tells Mongoose that request is not
|
||||
served and Mongoose should serve it. For example, event handler might
|
||||
choose to serve only RESTful API requests with URIs that start with
|
||||
certain prefix, and let Mongoose serve all static files.
|
||||
If event handler decides to serve the request, but doesn't have
|
||||
all the data at the moment, it should return `MG_MORE`. That tells
|
||||
Mongoose to keep the connection open after callback returns.
|
||||
|
||||
`mg_connection::connection_param` pointer is a placeholder to keep
|
||||
user-specific data. For example, handler could decide to open a DB
|
||||
connection and store DB connection handle in `connection_param`.
|
||||
* `MG_POLL` is sent to every connection on every iteration of
|
||||
`mg_poll_server()`. Event handler should return `MG_FALSE` to ignore
|
||||
this event. If event handler returns `MG_TRUE`, then Mongoose assumes
|
||||
that event handler has finished sending data, and Mongoose will
|
||||
close the connection.
|
||||
* `MG_HTTP_ERROR` sent when Mongoose is about to send HTTP error back
|
||||
to the client. Event handler can choose to send a reply itself, in which
|
||||
case event handler must return `MG_TRUE`. Otherwise, event handler must
|
||||
return `MG_FALSE`
|
||||
* `MG_CLOSE` is sent when the connection is closed. This event is used
|
||||
to cleanup per-connection state stored in `connection_param`
|
||||
if it was allocated.
|
||||
|
||||
Let's extend our minimal application example and
|
||||
create an URI that will be served by user's C code. The app will handle
|
||||
`/hello` URI by showing a hello message. So, when app is run,
|
||||
http://127.0.0.1:8080/hello will say hello, and here's the code:
|
||||
|
||||
#include <string.h>
|
||||
#include "mongoose.h"
|
||||
|
||||
static int event_handler(struct mg_connection *conn, enum mg_event ev) {
|
||||
if (ev == MG_AUTH) {
|
||||
return MG_TRUE; // Authorize all requests
|
||||
} else if (ev == MG_REQUEST && !strcmp(conn->uri, "/hello")) {
|
||||
mg_printf_data(conn, "%s", "Hello world");
|
||||
return MG_TRUE; // Mark as processed
|
||||
} else {
|
||||
return MG_FALSE; // Rest of the events are not processed
|
||||
}
|
||||
}
|
||||
|
||||
int main(void) {
|
||||
struct mg_server *server = mg_create_server(NULL, event_handler);
|
||||
mg_set_option(server, "document_root", ".");
|
||||
mg_set_option(server, "listening_port", "8080");
|
||||
|
||||
for (;;) {
|
||||
mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
|
||||
}
|
||||
mg_destroy_server(&server);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
## Example code
|
||||
|
||||
Mongoose source code contains number of examples, located in the
|
||||
[examples](https://github.com/cesanta/mongoose/blob/master/examples/) directory.
|
||||
To build any example, go to the respective directory and run `make`.
|
||||
|
||||
## Compilation flags
|
||||
|
||||
Below is the list of compilation flags that enable or disable certain
|
||||
features. By default, some features are enabled, and could be disabled
|
||||
by setting appropriate `NO_*` flag. Features that are disabled by default
|
||||
could be enabled by setting appropriate `USE_*` flag. Bare bones Mongoose
|
||||
is quite small, about 30 kilobytes of compiled x86 code. Each feature adds
|
||||
a couple of kilobytes to the executable size, and also has some runtime penalty.
|
||||
|
||||
Note that some flags start with `NS_` prefix. This is because Mongoose uses
|
||||
[Net Skeleton](http://github.com/cesanta/net_skeleton) as a low-level
|
||||
networking engine. If user code has `#include <net_skeleton.h>`, then
|
||||
all Net Skeleton functions will be available too.
|
||||
|
||||
|
||||
-DMONGOOSE_NO_AUTH Disable MD5 authorization support
|
||||
-DMONGOOSE_NO_CGI Disable CGI support
|
||||
-DMONGOOSE_NO_DAV Disable WebDAV support
|
||||
(PUT, DELETE, MKCOL, PROPFIND methods)
|
||||
-DMONGOOSE_NO_DIRECTORY_LISTING Disable directory listing
|
||||
-DMONGOOSE_NO_FILESYSTEM Disables all file IO, serving from memory only
|
||||
-DMONGOOSE_NO_LOGGING Disable access/error logging
|
||||
-DMONGOOSE_ENABLE_THREADS Enable mg_start_thread() function
|
||||
-DMONGOOSE_NO_WEBSOCKET Disable WebSocket support
|
||||
-DMONGOOSE_NO_USER No concept of a user on used platform.
|
||||
(Platform does not provide getpwnam, setgid or setuid)
|
||||
|
||||
-DMONGOOSE_USE_IDLE_TIMEOUT_SECONDS=X Idle connection timeout, default is 30
|
||||
-DMONGOOSE_USE_LUA Enable Lua scripting
|
||||
-DMONGOOSE_USE_LUA_SQLITE3 Enable sqlite3 binding for Lua
|
||||
-DMONGOOSE_USE_POST_SIZE_LIMIT=X POST requests larger than X will be
|
||||
rejected, not set by default
|
||||
-DMONGOOSE_USE_EXTRA_HTTP_HEADERS=X Append X to the HTTP headers
|
||||
for static files, empty by default
|
||||
|
||||
-DNS_ENABLE_DEBUG Enables debug messages on stdout, very noisy
|
||||
-DNS_ENABLE_SSL Enable SSL
|
||||
-DNS_ENABLE_IPV6 Enable IPv6 support
|
||||
-DNS_ENABLE_HEXDUMP Enables hexdump of sent and received traffic
|
||||
-DNS_STACK_SIZE=X Sets stack size to X for ns_start_thread()
|
||||
-DNS_DISABLE_THREADS Disable threads support
|
||||
-DNS_DISABLE_SOCKETPAIR For systems without loopback interface
|
||||
-DMONGOOSE_SEND_NS_EVENTS Send Net Skeleton events to the event handler
|
||||
in addition to the Mongoose events
|
||||
45
docs/FAQ.md
45
docs/FAQ.md
@ -1,45 +0,0 @@
|
||||
# Mongoose FAQ
|
||||
|
||||
## My Antivirus Software reports Mongoose as a security threat
|
||||
|
||||
Mongoose doesn't contain any malicious logic. Antivirus reports a
|
||||
[false positive](http://en.wikipedia.org/wiki/Type_I_and_type_II_errors#False_positive_error).
|
||||
This is when certain byte sequence in Mongoose accidentally matches
|
||||
virus signature in the Antivirus database.
|
||||
|
||||
## Download page doesn't work
|
||||
|
||||
Please make sure Javascript is enabled in your browser, and that the
|
||||
antivirus software is not blocking the download.
|
||||
|
||||
|
||||
## MacOS message: "Mongoose.app is damaged and can’t be opened. You should move it to the Trash"
|
||||
|
||||
This happens on newer MacOS systems. The reason for the message
|
||||
is the fact Mongoose.app is not digitally signed.
|
||||
Mongoose download procedure changes the app on the fly by injecting
|
||||
user information in the binary, making any prior digital signature void.
|
||||
Open "System Preferences" -> "Security" and set "Allow apps downloaded from"
|
||||
to "Anywhere". Revert the settings once Mongoose is installed.
|
||||
|
||||
## PHP doesn't work: getting empty page, or 'File not found' error
|
||||
|
||||
The reason for that is wrong paths to the interpreter. Remember that with PHP,
|
||||
correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX). Solution: specify
|
||||
full path to the PHP interpreter, e.g.:
|
||||
|
||||
mongoose -cgi_interpreter /full/path/to/php-cgi
|
||||
|
||||
## Mongoose fails to start
|
||||
|
||||
If Mongoose exits immediately when run, this
|
||||
usually indicates a syntax error in the configuration file
|
||||
(named `mongoose.conf` by default) or the command-line arguments.
|
||||
Syntax checking is omitted from Mongoose to keep its size low. However,
|
||||
the Manual should be of help. Note: the syntax changes from time to time,
|
||||
so updating the config file might be necessary after executable update.
|
||||
|
||||
### Embedding with OpenSSL on Windows might fail because of calling convention
|
||||
|
||||
To force Mongoose to use `__stdcall` convention, add `/Gz` compilation
|
||||
flag to the Visual Studio project settings.
|
||||
@ -1,18 +0,0 @@
|
||||
How To Share Files With Mongoose
|
||||
===========================================
|
||||
|
||||
## 1. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside the directory you want to share:
|
||||
|
||||
|
||||
|
||||
## 2. Double-click mongoose executable. A browser will start automatically, an icon will appear on a system tray in the bottom right corner of the desktop:
|
||||
|
||||
|
||||
|
||||
## 3. Click on the mongoose icon
|
||||
|
||||
|
||||
|
||||
## 4. Click on "Go to my address" to launch a browser locally. Or, to access a folder from another machine, launch a browser and type in the URL:
|
||||
|
||||
|
||||
@ -1,44 +0,0 @@
|
||||
# Mongoose Internals
|
||||
|
||||
Mongoose has single-threaded, event-driven, asynchronous, non-blocking core.
|
||||
`mg_create_server()` creates a web server instance. An instance is a container
|
||||
for the config options and list of active connections. To do the actual
|
||||
serving, user must call `mg_poll_server()`, which iterates over all
|
||||
active connections, performing `select()` syscall on all sockets with a
|
||||
timeout of specified number of milliseconds. When `select()` returns, Mongoose
|
||||
does an IO for each socket that has data to be sent or received. Application
|
||||
code must call `mg_poll_server()` in a loop.
|
||||
|
||||
Mongoose server instance is designed to be used by a single thread.
|
||||
It is an error to have more then
|
||||
one thread calling `mg_poll_server()`, `mg_set_option()` or any other function
|
||||
that take `struct mg_server *` parameter. Mongoose does not
|
||||
mutex-protect `struct mg_server *`, therefore the best practice is
|
||||
to call server management functions from the same thread (an IO thread).
|
||||
On a multi-core systems, many server instances can be created, sharing the
|
||||
same listening socket and managed by separate threads (see [multi_threaded.c](https://github.com/cesanta/mongoose/blob/master/examples/multi_threaded.c))
|
||||
example.
|
||||
|
||||
It is an error to pass and store `struct mg_connection *` pointers for
|
||||
later use to send data. The reason is that they can be invalidated by the
|
||||
next `mg_poll_server()` call. For such a task,
|
||||
there is `mg_iterate_over_connections()` API
|
||||
exists, which sends a callback function to the IO thread, then IO thread
|
||||
calls specified function for all active connection.
|
||||
|
||||
When mongoose buffers in HTTP request and successfully parses it, it calls
|
||||
appropriate URI handler immediately for GET requests. For POST requests,
|
||||
Mongoose delays the call until the whole POST request is buffered in memory.
|
||||
POST data is available to the callback as `struct mg_connection::content`,
|
||||
and POST data length is in `struct mg_connection::content_len`.
|
||||
|
||||
Note that websocket connections are treated the same way. Mongoose buffers
|
||||
websocket frame in memory, and calls URI handler when frame is fully
|
||||
buffered. Frame data is available `struct mg_connection::content`, and
|
||||
data length is in `struct mg_connection::content_len`, i.e. very similar to
|
||||
the POST request. `struct mg_connection::is_websocket` flag indicates
|
||||
whether the request is websocket or not. Also, for websocket requests,
|
||||
there is `struct mg_connection::wsbits` field which contains first byte
|
||||
of the websocket frame which URI handler can examine. Note that to
|
||||
reply to the websocket client, `mg_websocket_write()` should be used.
|
||||
To reply to the plain HTTP client, `mg_write()` should be used.
|
||||
154
docs/Options.md
154
docs/Options.md
@ -1,154 +0,0 @@
|
||||
# Mongoose Configuration Options
|
||||
|
||||
### access\_control\_list
|
||||
An Access Control List (ACL) allows restrictions to be put on the list of IP
|
||||
addresses which have access to the web server. In the case of the Mongoose
|
||||
web server, the ACL is a comma separated list of IP subnets, where each
|
||||
subnet is prepended by either a `-` or a `+` sign. A plus sign means allow,
|
||||
where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
|
||||
this means to deny only that single IP address.
|
||||
|
||||
Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
|
||||
all accesses. On each request the full list is traversed, and
|
||||
the last match wins. Example: `$ mongoose -access_control_list -0.0.0.0/0,+192.168/16` to deny all acccesses except those from `192.168/16` subnet. Note that if the option is set, then all accesses are forbidden
|
||||
by default. Thus in a previous example, `-0.0.0.0` part is not necessary.
|
||||
For example, `$mongoose access_control_list +10.0.0.0/8`
|
||||
means disallow all, allow subnet 10/8 only.
|
||||
|
||||
To learn more about subnet masks, see the
|
||||
[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)
|
||||
|
||||
Default: not set, all accesses are allowed.
|
||||
|
||||
### access\_log\_file
|
||||
Path to a file for access logs. Either full path, or relative to the
|
||||
mongoose executable. Default: not set, no query logging is done.
|
||||
|
||||
### auth_domain
|
||||
Authorization realm used in `.htpasswd` authorization. Default: `mydomain.com`
|
||||
|
||||
### cgi_interpreter
|
||||
Path to an executable to be used use as an interpreter for __all__ CGI scripts
|
||||
regardless script extension. Default: not set, Mongoose looks at
|
||||
[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\).
|
||||
|
||||
For example, if both PHP and perl CGIs are used, then
|
||||
`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
|
||||
respective CGI scripts. Note that paths should be either full file paths,
|
||||
or file paths relative to the directory where mongoose executable is located.
|
||||
|
||||
If all CGIs use the same interpreter, for example they are all PHP, then
|
||||
`cgi_interpreter` option can be set to the path to `php-cgi.exe` executable and
|
||||
shebang line in the CGI scripts can be omitted.
|
||||
**Note**: PHP scripts must use `php-cgi.exe`, not `php.exe`.
|
||||
|
||||
### cgi_pattern
|
||||
All files that match `cgi_pattern` are treated as CGI files. Default pattern
|
||||
allows CGI files be anywhere. To restrict CGIs to a certain directory,
|
||||
use `/path/to/cgi-bin/**.cgi` as a pattern. Note that **full file path** is
|
||||
matched against the pattern, not the URI.
|
||||
|
||||
When Mongoose starts CGI program, it creates new environment for it (in
|
||||
contrast, usually child program inherits the environment from parent). Several
|
||||
environment variables however are inherited from Mongoose's environment,
|
||||
they are: `PATH`, `TMP`, `TEMP`, `TMPDIR`, `PERLLIB`, `MONGOOSE_CGI`. On UNIX
|
||||
it is also `LD_LIBRARY_PATH`. On Windows it is also `COMSPEC`, `SYSTEMROOT`,
|
||||
`SystemDrive`, `ProgramFiles`, `ProgramFiles(x86)`, `CommonProgramFiles(x86)`.
|
||||
|
||||
Default: `**.cgi$|**.pl$|**.php$`
|
||||
|
||||
### dav\_auth\_file
|
||||
Authentication file for WebDAV mutation requests: `PUT`, `DELETE`, `MKCOL`.
|
||||
The format of that file is the same as for the `.htpasswd` file
|
||||
used for digest authentication. It can be created and managed by
|
||||
`mongoose -A` command. Default: not set, WebDAV mutations are disallowed.
|
||||
|
||||
### document_root
|
||||
A directory to serve. Default: current working directory.
|
||||
|
||||
### enable\_directory\_listing
|
||||
Enable directory listing, either `yes` or `no`. Default: `yes`.
|
||||
|
||||
### enable\_proxy
|
||||
Enable proxy functionality, either `yes` or `no`. If set to `yes`, then
|
||||
browsers can be configured to use Mongoose as a proxy. Default: `no`.
|
||||
|
||||
|
||||
### extra\_mime\_types
|
||||
Extra mime types to recognize, in form `extension1=type1,extension2=type2,...`.
|
||||
Extension must include dot. Example:
|
||||
`mongoose -extra_mime_types .cpp=plain/text,.java=plain/text`. Default: not set.
|
||||
|
||||
|
||||
### global\_auth\_file
|
||||
Path to a global passwords file, either full path or relative to the mongoose
|
||||
executable. If set, per-directory `.htpasswd` files are ignored,
|
||||
and all requests are authorised against that file. Use `mongoose -A` to
|
||||
manage passwords, or third party utilities like
|
||||
[htpasswd-generator](http://www.askapache.com/online-tools/htpasswd-generator).
|
||||
Default: not set, per-directory `.htpasswd` files are respected.
|
||||
|
||||
### hide\_files\_patterns
|
||||
A 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. Pattern
|
||||
must be for a file name only, not including directory name, e.g.
|
||||
`mongoose -hide_files_patterns secret.txt|even_more_secret.txt`. Default:
|
||||
not set.
|
||||
|
||||
### index_files
|
||||
Comma-separated list of files to be treated as directory index
|
||||
files. Default: `index.html,index.htm,index.cgi,index.shtml,index.php`
|
||||
|
||||
### listening_port
|
||||
Port to listen on. Port could be prepended by the specific IP address to bind
|
||||
to, e.g. `mongoose -listening_port 127.0.0.1:8080`. Otherwise Mongoose
|
||||
will bind to all addresses. To enable SSL, build Mongoose with
|
||||
`-DNS_ENABLE_SSL` compilation option, and specify `listening_port` as
|
||||
`ssl://PORT:SSL_CERTIFICATE.PEM`. Example SSL listener:
|
||||
`mongoose -listening_port ssl://8043:ssl_cert.pem`. Note that PEM file should
|
||||
be in PEM format, and must have both certificate and private key in it,
|
||||
concatenated together. More than one listening port can be specified,
|
||||
separated by comma,
|
||||
for example `mongoose -listening_port 8080,8000`. Default: 8080.
|
||||
|
||||
### run\_as\_user
|
||||
Switch to given user credentials after startup. UNIX-only. This option is
|
||||
required when mongoose needs to bind on privileged port on UNIX, e.g.
|
||||
|
||||
$ sudo mongoose -listening_port 80 -run_as_user nobody
|
||||
|
||||
Default: not set.
|
||||
|
||||
### url\_rewrites
|
||||
Comma-separated list of URL rewrites in the form of
|
||||
`uri_pattern=file_or_directory_path`. When Mongoose receives the request,
|
||||
it constructs the file name to show by combining `document_root` and the URI.
|
||||
However, if the rewrite option is used and `uri_pattern` matches the
|
||||
requested URI, then `document_root` is ignored. Instead,
|
||||
`file_or_directory_path` is used, which should be a full path name or
|
||||
a path relative to the web server's current working directory. Note that
|
||||
`uri_pattern`, as all mongoose patterns, is a prefix pattern. If `uri_pattern`
|
||||
is a number, then it is treated as HTTP error code, and `file_or_directory_path`
|
||||
should be an URI to redirect to. Mongoose will issue `302` temporary redirect
|
||||
to the specified URI with following parameters:
|
||||
`?code=HTTP_ERROR_CODE&orig_uri=ORIGINAL_URI&query_string=QUERY_STRING`.
|
||||
|
||||
If `uri_pattern` starts with `@` symbol, then Mongoose compares
|
||||
it with the `HOST` header of the request. If they are equal, Mongoose sets
|
||||
document root to `file_or_directory_path`, implementing virtual hosts support.
|
||||
|
||||
Examples:
|
||||
|
||||
# Redirect all accesses to `.doc` files to a special script
|
||||
mongoose -url_rewrites **.doc$=/path/to/cgi-bin/handle_doc.cgi
|
||||
|
||||
# Implement user home directories support
|
||||
mongoose -url_rewrites /~joe/=/home/joe/,/~bill=/home/bill/
|
||||
|
||||
# Redirect 404 errors to a specific error page
|
||||
mongoose -url_rewrites 404=/cgi-bin/error.cgi
|
||||
|
||||
# Virtual hosts example: serve foo.com domain from different directory
|
||||
mongoose -url_rewrites @foo.com=/var/www/foo.com
|
||||
|
||||
Default: not set.
|
||||
@ -1,49 +0,0 @@
|
||||
How To Create A PHP Website With Mongoose
|
||||
===========================================
|
||||
|
||||
## 1. Create a directory which will contain your website files. For example, on drive `C:\`, create a directory called `my_website`:
|
||||
|
||||
|
||||
|
||||
## 2. Inside `my_website` directory, create a new file called "index". This will be the default web page shown when the website is visited.
|
||||
|
||||
|
||||
|
||||
## 3. Open index file with your favorite editor (for example, Notepad) and enter some HTML / PHP code:
|
||||
|
||||
|
||||
|
||||
## 4. Save this file as `index.php`:
|
||||
|
||||
|
||||
|
||||
|
||||
## 5. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside `my_website` directory:
|
||||
|
||||
|
||||
|
||||
## 6. Double-click mongoose executable. An icon will appear on a system tray in the bottom right corner of the desktop:
|
||||
|
||||
|
||||
|
||||
## 7. Download PHP 5.3 zip (do NOT download PHP 5.5 cause you might have missing DLLs problem) from http://windows.php.net/download and extract it to `C:\php5` directory:
|
||||
|
||||
|
||||
## 8. Click on the mongoose icon and choose "Edit Settings" menu.:
|
||||
|
||||
|
||||
## 9. A settings dialog will appear. Click on `cgi_interpreter` button:
|
||||
|
||||
|
||||
|
||||
## 10. Choose `C:\php5\php-cgi.exe` and click "Save Settings":
|
||||
|
||||
|
||||
|
||||
## 11. Click on the mongoose icon and choose "Go to my address" menu:
|
||||
|
||||
|
||||
|
||||
## 12. A browser will popup displaying `index.php`.
|
||||
|
||||
|
||||
@ -1,218 +0,0 @@
|
||||
# Mongoose Release Notes
|
||||
|
||||
## Release 5.6, 2015-03-17
|
||||
|
||||
Changes in Libmongoose library:
|
||||
|
||||
- Added `-dav_root` configuration option that gives an ability to mount
|
||||
a different root directory (not document_root)
|
||||
- Fixes for build under Win23 and MinGW
|
||||
- Bugfix: Double dots removal
|
||||
- Bugfix: final chunked response double-send
|
||||
- Fixed compilation in 64-bit environments
|
||||
- Added OS/2 compatibility
|
||||
- Added `getaddrinfo()` call and `NS_ENABLE_GETADDRINFO`
|
||||
- Various SSL-related fixes
|
||||
- Added integer overflow protection in `iobuf_append()` and `deliver_websocket_frame()`
|
||||
- Fixed NetBSD build
|
||||
- Enabled `NS_ENABLE_IPV6` build for Visual Studio 2008+
|
||||
- Enhanced comma detection in `parse_header()`
|
||||
- Fixed unchanged memory accesses on ARM
|
||||
- Added ability to use custom memory allocator through NS_MALLOC, NS_FREE, NS_REALLOC
|
||||
|
||||
Changes in Mongoose binary:
|
||||
|
||||
- Added `-start_browser` option to disable automatic browser launch
|
||||
- Added experimental SSL support. To listen on HTTPS port, use `ssl://PORT:SSL_CERT` format. For example, to listen on HTTP port 8080 and HTTPS port 8043, use `-listening_port 8080,ssl://8043:ssl_cert.pem`
|
||||
|
||||
## Release 5.5, October 28 2014
|
||||
|
||||
Changes in Libmongoose library:
|
||||
|
||||
- Added new API function: `mg_forward()` for proxying functionality
|
||||
- Added new API function: `mg_send_file_data()` for sending file data
|
||||
- Added new utility API functions: `mg_mmap() and mg_munmap()`
|
||||
- Changed the way SSL settings are handled: removed `ssl_certificate` and
|
||||
`ssl_ca_certificate` options, and instead made `listening_port` accept
|
||||
`ssl://PORT:SSL_CERT:CA_CERT` notation
|
||||
- Added ability to listen on multiple ports, see `listening_port` documentation
|
||||
- Added `enable_proxy` option
|
||||
- Added [cookie_authentication](https://github.com/cesanta/mongoose/tree/master/examples/cookie_authentication) example
|
||||
- Added [websocket\_ssl\_proxy](https://github.com/cesanta/mongoose/tree/master/examples/websocket_ssl_proxy) example
|
||||
- Added [http_client](https://github.com/cesanta/mongoose/tree/master/examples/http_client) example
|
||||
- Increased default 'idle connection' timeout from 30 to 300 seconds
|
||||
- Fixed MinGW build
|
||||
- Refactored all examples, put each in it's own directory with dedicated build
|
||||
- Many smaller bugfixed, including SSL, CGI, API, proxy, etc
|
||||
|
||||
Changes in pre-compiled binaries:
|
||||
|
||||
- Support for multiple listening ports
|
||||
- Fixed CGI handling for scripts that specify interpreter in the hashbang line
|
||||
|
||||
## Release 5.4, July 28 2014
|
||||
|
||||
Changes in Libmongoose library:
|
||||
|
||||
- Added `hexdump_file` option for low-level request/reply debugging
|
||||
- Added `mg_template()` API function for generating HTML pages from
|
||||
templates with expansions
|
||||
- Fixed `struct mg_connection::local_ip` handling, `mg_set_option()`
|
||||
behavior with NULL values
|
||||
- Added `mg_send_file()` call to send arbitrary file to the client
|
||||
- Added `mg_terminate_ssl()` for SSL termination functionality
|
||||
- Added HTTP proxy support, `enable_proxy` config option
|
||||
- Added `mg_next()` for iterating over existing active connections
|
||||
- Added client-side SSL auth, `ssl_ca_certificate` option
|
||||
- Added `mg_wakeup_server_ex()` for pushing messages to existing connections
|
||||
- Added `MG_WS_HANDSHAKE` and `MG_WS_CONNECT` events that are sent on
|
||||
Websocket handshake is connection establishment, respectively
|
||||
- Removed server-side Lua support
|
||||
- Filesystem access, reading from socket/SSL performance improvements
|
||||
- DAV PROPFIND memory leak fixed
|
||||
- Added `big_upload.c` and enhanced `upload.c` example
|
||||
- Added `proxy.c` example that demonstrates proxy functionality and SSE pushes
|
||||
- Added `websocket2.c` example that shows simple web chat implementation
|
||||
over websockets
|
||||
- Various minor fixes
|
||||
|
||||
|
||||
Changes in pre-compiled binaries:
|
||||
|
||||
- Created HTML administration console
|
||||
- When server is started, browser is started automatically
|
||||
- Fixed directory listing bug when directory contains `#` character
|
||||
- Removed built-in Lua Server Pages in the binary, and instead
|
||||
added Mongoose + Lua developer bundle which has Lua Server Pages support.
|
||||
That also solves external Lua modules loading problem.
|
||||
|
||||
|
||||
## Release 5.3, March 10 2014
|
||||
|
||||
Changes in Libmongoose library:
|
||||
|
||||
* Moved to the evented API. Updated API documentation is at
|
||||
http://cesanta.com/docs/Embed.shtml
|
||||
http://cesanta.com/docs/API.shtml
|
||||
* Added `MG_LUA` event for exporting custom variables to the Lua environment
|
||||
* Added virtual hosts capability, see `url_rewrites` option description at
|
||||
http://cesanta.com/docs/Options.shtml
|
||||
* Added mjpg serving example
|
||||
* Cleaned up and documented HTTP client API, with unit tests
|
||||
* Added `mg_wakeup_server()` to awaken `mg_poll_server()`
|
||||
from another thread
|
||||
* Moved Mongoose IO core to [https://github.com/cesanta/net_skeleton](Net Skeleton)
|
||||
* Added connection hexdump functionality for developers
|
||||
* Bug fixes
|
||||
|
||||
Changes in pre-compiled binaries:
|
||||
|
||||
* New awesome Mongoose logos by our designer Katrin - thanks Katrin!
|
||||
Check them out at http://cesanta.com/products.shtml
|
||||
* Added Lua Server Pages support to the free version, quick intro is at
|
||||
http://cesanta.com/docs/Lua.shtml
|
||||
* Added quick "Set shared directory" menu item to set `document_root`
|
||||
* Added SSI support to the Pro version
|
||||
* Removed SSL support from the Pro version
|
||||
|
||||
## Release 5.2, Feb 1 2014
|
||||
|
||||
* Windows binary made fully UNICODE aware. In previous versions,
|
||||
the presence of non-ASCII chars in document root, CGI script name,
|
||||
or directory name might have broken Mongoose as stand-alone
|
||||
or as Windows service. Now Mongoose works with non-ASCII paths properly.
|
||||
Internally, Mongoose uses UTF8 encoding. When making WinAPI calls,
|
||||
mongoose converts UTF8 strings to wide chars and calls UNICODE API.
|
||||
* Enhanced authorization API by providing `mg_set_auth_handler()` and
|
||||
`mg_authorize_digest()`
|
||||
* Removed `mg_add_uri_handler()`, added `mg_set_request_handler()`.
|
||||
There is only oneURI handler that handles all requests, just like in 4.x.
|
||||
The reason for this change is to provide an ability to catch all URIs,
|
||||
and at the same time signal Mongoose to continue handling specific URIs.
|
||||
* Added `mg_parse_multipart()` API for file uploads.
|
||||
Note that the restriction on uploading huge files still exists,
|
||||
and will be eliminated in the next release.
|
||||
* Allowing mongoose to bind to port 0, in which case it'll bind to any
|
||||
random unused port.
|
||||
* Moved `idle_timeout_ms` run-time option to compile-time flag
|
||||
* Added asynchronous HTTP client, not documented yet. Documentation and
|
||||
examples are coming in the next couple of weeks. Async Websocket client
|
||||
is scheduled for the next release. See usage examples at `unit_test.c`
|
||||
* Windows and MacOS pre-built binaries are now split to free and paid ones,
|
||||
paid binaries include CGI, SSL, Lua, Sqlite, support and updates.
|
||||
Linux pre-built binary includes all functionality and is free, and will
|
||||
continue to be free. Source code for Windows and MacOS GUI is closed.
|
||||
Disclaimer: source code for the command line stand-alone server,
|
||||
as well as Mongoose library itself, will never be closed.
|
||||
* Multiple bug fixes and minor enhancements
|
||||
|
||||
## Release 5.1, Jan 10 2014
|
||||
|
||||
* CGI-related bugs where fixed, primarily for Windows platform
|
||||
* Bugs on Windows related to UNICODE support were fixed
|
||||
* Added a feature to support "error pages" through redirect.
|
||||
Done using `-url_redirects` option, details are on
|
||||
http://cesanta.com/docs/Options.shtml
|
||||
|
||||
## Release 5.0, Jan 6 2014
|
||||
|
||||
* Internal core has been changed from blocking, thread-per-connection to
|
||||
non-blocking, asynchronous, one thread for all.
|
||||
* API modification for server creation and response creation. That allowed
|
||||
keep-alive support for dynamic requests, boosting the embedded performance
|
||||
to 100+ thousands requests per second on a single core
|
||||
(as measured on my development MacBook laptop)
|
||||
* Unified handling of POST requests and Websocket requests by putting a
|
||||
payload into `conn->content`, `conn->content_len` attributes.
|
||||
That simplified user code and eliminated the need of `mg_read()`,
|
||||
since mongoose buffers all data prior to calling the callback
|
||||
* keep-alive support is the default
|
||||
* Dropped SSI support and throttling support
|
||||
* Several configuration parameters are gone:
|
||||
* `cgi_environment` (replaced with MONGOOSE_CGI),
|
||||
* `protect_uri` (not useful)
|
||||
* `ssi_pattern` (SSI support is gone)
|
||||
* `throttle` (throttling support is gone)
|
||||
* `error_log_file` (not used)
|
||||
* `enable_keep_alive` (enabled by default)
|
||||
* `listening_ports` (renamed to listening_port)
|
||||
* `num_threads` (core has changed to single thread)
|
||||
* `put_delete_auth_file` (renamed to dav_auth_file)
|
||||
* `authentication_domain` (renamed to auth_domain)
|
||||
* Due to the async, non-blocking nature of the core, few restrictions
|
||||
are now in place:
|
||||
* user callbacks must not block
|
||||
* POST and Websocket data are now buffered, and cannot be huge
|
||||
* mongoose is now capable on listening on only one port
|
||||
|
||||
## Release 4.1, Oct 2013
|
||||
## Release 4.0, Oct 2013
|
||||
## Release 3.8, Sep 2013
|
||||
|
||||
## Release 3.7, Feb 2 2013
|
||||
|
||||
* Added "redirect to SSL port" functionality, e.g. if you specify
|
||||
`-listening_ports 8080r,8043s`
|
||||
then all requests to HTTP port 8080 will be redirected to HTTPS port 8043
|
||||
* Added `mg_download()` API, an HTTP client interface!
|
||||
* Lua server pages now must output HTTP headers -- full control for Lua
|
||||
* Added pre-built binary for MacOS, with initial GUI support
|
||||
* API change: got rid of events, moved to struct `mg_callbacks`
|
||||
* Bugfixes, thanks to contributors
|
||||
|
||||
|
||||
## Release 3.7, Jan 18 2013
|
||||
* Fixed source code archive (main.c was missing)
|
||||
* Extended Windows GUI functionality:
|
||||
* Added "Start browser" systray popup menu item
|
||||
* Enhanced configuration editor
|
||||
* Renamed config options:
|
||||
* `put_delete_passwords_file` -> `put_delete_auth_file`
|
||||
* `global_passwords_file` -> `global_auth_file`
|
||||
* `select()` changed to `poll()`, to avoid big file descriptor
|
||||
`FD_SET` problem on UNIX
|
||||
* Couple of bugfixes, thanks to contributors
|
||||
|
||||
|
||||
Earlier release notes could be found by searching
|
||||
[Mongoose mailing list](https://groups.google.com/forum/#!forum/mongoose-users)
|
||||
70
docs/SSL.md
70
docs/SSL.md
@ -1,70 +0,0 @@
|
||||
# Mongoose SSL guide
|
||||
|
||||
SSL is a protocol that makes web communication secure. To enable SSL
|
||||
in mongoose, 2 steps are required:
|
||||
|
||||
1. Create valid SSL certificate file
|
||||
2. Append SSL certificate file path to the `listening_ports` option
|
||||
|
||||
Below is the `mongoose.conf` file snippet for typical SSL setup:
|
||||
|
||||
document_root www_root # Serve files in www_root directory
|
||||
listening_ports 80,ssl://443:cert.pem # Listen on ports 80 and 443
|
||||
|
||||
## How to create SSL certificate file
|
||||
|
||||
SSL certificate file is a text file that must contain at least two
|
||||
sections:
|
||||
|
||||
1. A private key
|
||||
2. A certificate
|
||||
|
||||
Both sections should be chunks of text in PEM format. When PEM file is
|
||||
opened in a text editor, it looks like this:
|
||||
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
MIIEogIBAAKCAQEAwONaLOP7EdegqjRuQKSDXzvHmFMZfBufjhELhNjo5KsL4ieH
|
||||
hYN0Zii2yTb63jGxKY6gH1R/r9dL8kXaJmcZrfSa3AgywnteJWg=
|
||||
-----END RSA PRIVATE KEY-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIDBjCCAe4CCQCX05m0b053QzANBgkqhkiG9w0BAQQFADBFMQswCQYDVQQGEwJB
|
||||
SEGI4JSxV56lYg==
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
Two aforementioned sections are clearly seen. Typically, those section
|
||||
are bigger then in the example shown. The text between the `BEGIN` and
|
||||
`END` is the text representation of binary data, a private key and a
|
||||
certificate. Therefore, in order to create a certificate file,
|
||||
|
||||
* private key must be converted to PEM format
|
||||
* certificate must be converted to PEM format
|
||||
* those two should be concatenated into a single file
|
||||
|
||||
If the certificate chain in used, a chain file also needs to be
|
||||
converted into PEM format and appended to the certificate file.
|
||||
|
||||
## How SSL works
|
||||
|
||||
SSL is a protocol that can encrypt communication between two parties. If third
|
||||
party observes all messages passed by, it would be very
|
||||
hard for the third party (though not impossible) to decrypt the communication.
|
||||
|
||||
The idea is based on so-called public key encryption. Communicating parties
|
||||
have two keys: a public key and a private key. A public key is advertised
|
||||
to everybody, and it is contained in a certificate. A private key is kept
|
||||
secret. Security algorithm works in a way that anybody can encrypt
|
||||
a message using public key, and only private key can decrypt it.
|
||||
|
||||
This is why web server needs both private key and certificate: private key
|
||||
is used to decrypt incoming messages, and certificate is used to tell the
|
||||
public key to the other party. When communication starts, parties exchange
|
||||
their public keys, and keep private keys to themselves. Man-in-the-middle
|
||||
who observes the communication is unable to decrypt the messages cause
|
||||
private keys are required for decryption.
|
||||
|
||||
Encryption algorithms are built on top of hard mathematical problem, which
|
||||
makes it very expensive for man-in-the-middle to compute private keys.
|
||||
For example, RSA algorithm is based on a mathematical problem of factorization.
|
||||
It is easy to generate two very large prime numbers `P` and `Q` and make
|
||||
a product `P * Q`. But given a product, it is very hard to recover these
|
||||
two prime numbers - this is called factorization.
|
||||
@ -1,86 +0,0 @@
|
||||
# Mongoose User Guide
|
||||
|
||||
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 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 Windows and Mac, Mongoose iconifies itself to the system tray when started.
|
||||
Right-click on the icon to pop 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 -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, 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:
|
||||
|
||||
# This is a comment
|
||||
document_root C:\www
|
||||
listening_port 80
|
||||
ssl_certificate C:\mongoose\ssl_cert.pem
|
||||
|
||||
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 used as
|
||||
document root.
|
||||
|
||||
Note that configuration options on the command line must start with `-`,
|
||||
and their names are the same as in the config file. Exampli gratia,
|
||||
the following two setups are equivalent:
|
||||
|
||||
$ mongoose -listening_port 1234 -document_root /var/www
|
||||
|
||||
$ cat > mongoose.conf
|
||||
listening_ports 1234
|
||||
document_root /var/www
|
||||
^D
|
||||
$ mongoose
|
||||
|
||||
Mongoose can also be used to modify `.htpasswd` passwords file:
|
||||
|
||||
$ 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
|
||||
recognized by the file name pattern. Mongoose uses shell-like glob
|
||||
patterns. Pattern match starts at the beginning of the string, so essentially
|
||||
patterns are prefix patterns. Syntax is as follows:
|
||||
|
||||
** 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.
|
||||
|
||||
All other characters in the pattern match themselves. Examples:
|
||||
|
||||
# Pattern Meaning
|
||||
**.cgi$ Any string that ends with .cgi
|
||||
/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
|
||||
@ -1,53 +0,0 @@
|
||||
# This program is used to embed arbitrary data into a C binary. It takes
|
||||
# a list of files as an input, and produces a .c data file that contains
|
||||
# contents of all these files as collection of char arrays.
|
||||
#
|
||||
# Usage: perl <this_file> <file1> [file2, ...] > embedded_data.c
|
||||
|
||||
foreach my $i (0 .. $#ARGV) {
|
||||
open FD, '<:raw', $ARGV[$i] or die "Cannot open $ARGV[$i]: $!\n";
|
||||
printf("static const unsigned char v%d[] = {", $i);
|
||||
my $byte;
|
||||
my $j = 0;
|
||||
while (read(FD, $byte, 1)) {
|
||||
if (($j % 12) == 0) {
|
||||
print "\n";
|
||||
}
|
||||
printf ' %#04x,', ord($byte);
|
||||
$j++;
|
||||
}
|
||||
print " 0x00\n};\n";
|
||||
close FD;
|
||||
}
|
||||
|
||||
print <<EOS;
|
||||
|
||||
#include <stddef.h>
|
||||
#include <string.h>
|
||||
|
||||
static const struct embedded_file {
|
||||
const char *name;
|
||||
const unsigned char *data;
|
||||
size_t size;
|
||||
} embedded_files[] = {
|
||||
EOS
|
||||
|
||||
foreach my $i (0 .. $#ARGV) {
|
||||
print " {\"$ARGV[$i]\", v$i, sizeof(v$i) - 1},\n";
|
||||
}
|
||||
|
||||
print <<EOS;
|
||||
{NULL, NULL, 0}
|
||||
};
|
||||
|
||||
const char *find_embedded_file(const char *name, size_t *size) {
|
||||
const struct embedded_file *p;
|
||||
for (p = embedded_files; p->name != NULL; p++) {
|
||||
if (!strcmp(p->name, name)) {
|
||||
if (size != NULL) { *size = p->size; }
|
||||
return (const char *) p->data;
|
||||
}
|
||||
}
|
||||
return NULL;
|
||||
}
|
||||
EOS
|
||||
Loading…
Reference in New Issue
Block a user