Mongoose Web Server

This page aims to help application developers integrate the ​Mongoose Web / HTTP server into their RTEMS applications. Only a reasonably basic configuration is treated.

It is assumed that:

• the reader is using RTEMS 4.11 (the interface to Mongoose has changed significantly from 4.10), ​compiling it from source and is comfortable doing so
• networking is already configured and working in the application
• a file-system (from which to serve web pages and write logs to) is already configured and working in the application

What is it?

Mongoose is a lightweight web server, one of two (the other being the Simple HTTPD server) available in RTEMS.

Unfortunately, recent versions of the server have moved to an RTEMS-incompatible license and thus it is not up-to-date in RTEMS. It is anticipated that it will be removed at some future date.

Prerequisites

RTEMS must have been configured with networking and POSIX interfaces enabled.

Library

The Mongoose library must be pulled in for linking. To do so, ensure that -lmghttpd is passed to the linker.

If you're using a Makefile based on the provided ​template - available for RTEMS 4.11 in its share/rtems4.11/make/Templates/Makefile.leaf path - this can be accomplished by adding -lmghttpd to LD_LIBS; e.g.:

LD_LIBS+=-lmghttpd

CONFIGURE / confdefs.h

Mongoose uses the POSIX API and its mutex and condition variable features and thus resources must be allocated for it in the application's configuration.

It uses:

• One POSIX "master" thread
• A number of POSIX worker threads, depending on the number requested when starting Mongoose
• Two libio file descriptors for each worker thread
• Three POSIX condition variables
• One POSIX mutex

Initializing Mongoose

#include <mghttpd/mongoose.h>

in the source file you'll initialize Mongoose from.

mg_start() is used to start Mongoose:

struct mg_context *mg_start(const struct mg_callbacks *callbacks, void *user_data, const char **options)

For the basic configuration described here, NULL can be passed for the user_data parameter, but callback must be provided. To initialise a structure with no callbacks enabled, use:

struct mg_callbacks callbacks = { NULL };

The options parameter is a NULL-terminated array of string pairs, each pair giving an option name and a value (see the Mongoose documentation for a ​description of options). By way of example, options might be defined as such:

 const char *options[] = {
   "document_root",   "/usr/www",
   "listening_ports", "80",
   "num_threads",     "1",
   "thread_priority", "10",
   "access_log_file", "/var/log/httpd-access.log",
   "error_log_file",  "/var/log/httpd-error.log",
   NULL
 }

Calling mg_start() (after networking and the file-system are initialized) will return a "context" upon success, NULL upon failure (sadly, at the time of writing, not necessarily with an indication of the nature of the failure - configuring an error log (as in the example options above) is recommended for troubleshooting failures).

This context is used for further operating on that Mongoose instance (for example, in calling mg_stop() to halt it).

Done!

Hopefully at this point, you've a working Mongoose server.

Ensure there's a page for it to serve (e.g., /usr/www/index.html) and test by browsing to http://<ip>/ (where <ip> is a resolvable name or IP address for your RTEMS target)!