GNU Libmicrohttpd

GNU libmicrohttpd is a small C library that makes it easy to run an HTTP server as part of another application. GNU Libmicrohttpd is free software and part of the GNU project. Key features that distinguish GNU Libmicrohttpd from other projects are:

  • C library: fast and small
  • API is simple, expressive and fully reentrant
  • Implementation is HTTP 1.1 compliant
  • HTTP server can listen on multiple ports
  • Various threading modes: run in application thread, internal thread, thread pool, and thread-per-connection
  • Three different sockets polling modes: select(), poll(), and epoll
  • Minimised number of sys-calls to avoid extra user/kernel mode switches
  • Supported platforms include GNU/Linux, FreeBSD, OpenBSD, NetBSD, Android, Darwin (macOS), W32, OpenIndiana/Solaris, and z/OS
  • Support for IPv6
  • Support for SHOUTcast
  • Support for incremental processing of POST data (optional)
  • Support for basic and digest authentication (optional)
  • Support for TLS (requires libgnutls, optional)
  • Binary is only about 32k (without TLS support and other optional features)

GNU libmicrohttpd was started because the author needed an easy way to add a concurrent HTTP server to other projects. Existing alternatives were either non-free, not reentrant, standalone, of terrible code quality, or a combination thereof. Do not use GNU libmicrohttpd if you are looking for a standalone HTTP server, there are many other projects out there that provide that kind of functionality already. However, if you want to be able to serve simple WWW pages from within your C or C++ application, check it out.

Table of Contents

Downloading libmicrohttpd

Source Code
Libmicrohttpd is available from the main GNU FTP server via HTTP(S) and FTP. It can also be found on the GNU mirrors; please use a mirror if possible.
Debian .deb package
The debian package can be downloaded from the official debian archive. The respective packages for libmicrohttpd are libmicrohttpd and for development libmicrohttpd-dev.
Tar Package
The latest version can be found on GNU mirrors. If the mirror does not work, you should be able to find them on the main FTP server.

Latest release is libmicrohttpd-latest.tar.gz.

Windows
Latest Windows binary is libmicrohttpd-latest-w32-bin.zip.

Documentation

In addition to the brief documentation on this webpage, we have various other forms of documentation available:

microhttpd.h
This include file documents most of the API in detail.
Manual
A manual for Libmicrohttpd is available online, as is documentation for most GNU software. You may also find more information about Libmicrohttpd by running info libmicrohttpd or man libmicrohttpd, or by looking at /usr/share/doc/libmicrohttpd/, /usr/local/doc/libmicrohttpd/, or similar directories on your system.
Tutorial
The GNU Libmicrohttpd tutorial is available as one document in PDF and HTML formats.
Compatibility
API/ABI compatibility report comparing most recent GNU libmicrohttpd versions

Mailing lists

Libmicrohttpd uses the libmicrohttpd mailinglist to discuss all aspects of Libmicrohttpd, including support, development, and enhancement requests, as well as bug reports.

Announcements about Libmicrohttpd and most other GNU software are made on info-gnu (archive).

Security reports that should not be made immediately public can be sent directly to the maintainer. If there is no response to an urgent issue, you can escalate to the general security mailing list for advice.

Getting involved

Development of Libmicrohttpd, and GNU in general, is a volunteer effort, and you can contribute. For information, please read How to help GNU. If you'd like to get involved, it's a good idea to join the discussion mailing list (see above).

Development
Known bugs and open feature requests are tracked in our bugtracker. You need to sign up for a reporter account. Please make sure you report bugs under libmicrohttpd and not under any of the other projects.
Git access

You can access the current development version of libmicrohttpd using

$ git clone https://git.gnunet.org/libmicrohttpd.git

Our website is kept at

$ cvs -z3 -d:pserver:[email protected]:/web/libmicrohttpd co libmicrohttpd

Quick Introduction

Dependencies
GNU Libmicrohttpd can be used without any dependencies; however, for TLS (HTTPS) support it require libgnutls. Furthermore, the testcases use libcurl. Some extended testcases also use zzuf and socat (to simulate clients that violate the HTTP protocols). You can compile and use GNU Libmicrohttpd without installing libgnutls, libcurl, zzuf or socat.
A minimal example
Before including the microhttpd.h header, you may need to include the headers of your operating system that define the size_t, fd_set, socklen_t and struct sockaddr data types and define MHD_PLATFORM_H. Otherwise, the microhttpd.h header will attempt to include the appropriate headers automatically, which may fail for more exotic platforms.

The following is a minimal example for GNU/Linux (included in the distribution): 

#include <microhttpd.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>

#define PAGE "<html><head><title>libmicrohttpd demo</title>"\
             "</head><body>libmicrohttpd demo</body></html>"

static enum MHD_Result
ahc_echo(void * cls,
         struct MHD_Connection * connection,
         const char * url,
         const char * method,
         const char * version,
         const char * upload_data,
         size_t * upload_data_size,
         void ** ptr) {
  static int dummy;
  const char * page = cls;
  struct MHD_Response * response;
  int ret;

  if (0 != strcmp(method, "GET"))
    return MHD_NO; /* unexpected method */
  if (&dummy != *ptr)
    {
      /* The first time only the headers are valid,
         do not respond in the first round... */
      *ptr = &dummy;
      return MHD_YES;
    }
  if (0 != *upload_data_size)
    return MHD_NO; /* upload data in a GET!? */
  *ptr = NULL; /* clear context pointer */
  response = MHD_create_response_from_buffer (strlen(page),
                                              (void*) page,
  					      MHD_RESPMEM_PERSISTENT);
  ret = MHD_queue_response(connection,
			   MHD_HTTP_OK,
			   response);
  MHD_destroy_response(response);
  return ret;
}

int main(int argc,
	 char ** argv) {
  struct MHD_Daemon * d;
  if (argc != 2) {
    printf("%s PORT\n",
	   argv[0]);
    return 1;
  }
  d = MHD_start_daemon(MHD_USE_THREAD_PER_CONNECTION,
		       atoi(argv[1]),
		       NULL,
		       NULL,
		       &ahc_echo,
		       PAGE,
		       MHD_OPTION_END);
  if (d == NULL)
    return 1;
  (void) getc (stdin);
  MHD_stop_daemon(d);
  return 0;
}
Threading modes
The example above uses the simplest threading mode, MHD_USE_THREAD_PER_CONNECTION. In this mode, MHD starts one thread to listen on the port for new connections and then spawns a new thread to handle each connection. This mode is great if the HTTP server has hardly any state that is shared between connections (no synchronization issues!) and may need to perform blocking operations (such as extensive IO or running of code) to handle an individual connection.

The second threading mode, MHD_USE_SELECT_INTERNALLY, uses only a single thread to handle listening on the port and processing of requests. This mode is preferable if spawning a thread for each connection would be costly. If the HTTP server is able to quickly produce responses without much computational overhead for each connection, this mode can be a great choice. Note that MHD will still start a single thread for itself – this way, the main program can continue with its operations after calling MHD_daemon_start. Naturally, if the HTTP server needs to interact with shared state in the main application, synchronization will be required. If such synchronization in code providing a response results in blocking, all HTTP server operations on all connections will stall. This mode is a bad choice if response data (for responses generated using the MHD_create_response_from_callback function) cannot always be provided instantly. The reason is that the code generating responses should not block (since that would block all other connections) and on the other hand, if response data is not available immediately, MHD will start to busy wait on it. Use the first mode if you want to block on providing response data in the callback, or the last mode if you want to use a more event-driven mode with one big select loop.

The third mode combines a thread pool with the MHD_USE_SELECT_INTERNALLY mode, which can benefit implementations that require scalability. As said before, by default this mode only uses a single thread. When combined with the thread pool option, it is possible to handle multiple connections with multiple threads. The number of threads is specified using the MHD_OPTION_THREAD_POOL_SIZE; any value greater than one for this option will activate the use of the thread pool. In contrast to the MHD_USE_THREAD_PER_CONNECTION mode (where each thread handles one and only one connection), threads in the pool can handle a large number of concurrent connections. Using MHD_USE_SELECT_INTERNALLY in combination with a thread pool is typically the most scalable (but also hardest to debug) mode of operation for MHD.

The fourth threading mode (used when no specific flag is given), uses no threads. Instead, the main application must (periodically) request file descriptor sets from MHD, perform a select call and then call MHD_run. MHD_run will then process HTTP requests as usual and return. MHD_run is guaranteed to not block; however, access handlers and response processing callbacks that it invokes may block. This mode is useful if a single-threaded implementation is desired and in particular if the main application already uses a select loop for its processing. If the application is not ready to provide a response, it can just return zero for the number of bytes read and use its file descriptors in the external select loop to wake up and continue once the data is ready – MHD will unlist the socket from the write set if the application failed to provide response data (this only happens in this mode).

The testcases provided include examples for using each of the threading modes.

Generating responses
MHD provides various functions to create struct MHD_Response objects. A response consists of a set of HTTP headers and a (possibly empty) body. The three main ways to create a response are either by specifying a given (fixed-size) body (MHD_create_response_from_data), by providing a function of type MHD_ContentReaderCallback which provides portions of the response as needed or by providing an open file descriptor (MHD_create_response_from_fd). The first response construction is great for small and in particular static webpages that fit into memory. The second response type should be used for response objects where the size is initially not known or where the response maybe too large to fit into memory. Finally, using a file descriptor can be used on Linux systems to use the highly efficient sendfile call for the file transfer.

A response is used by calling MHD_queue_response which sends the response back to the client on the specified connection. Once created, a response object can be used any number of times. Internally, each response uses a reference counter. The response is freed once the reference counter reaches zero. The HTTP server should call MHD_destroy_response when a response object is no longer needed, that is, the server will not call MHD_queue_response again using this response object. Note that this does not mean that the response will be immediately destroyed – destruction may be delayed until sending of the response is complete on all connections that have the response in the queue.

Queueing responses
Clients should never create a "100 CONTINUE" response. MHD handles "100 CONTINUE" internally and only allows clients to queue a single response per connection. Furthermore, clients must not queue a response before the request has been fully received (except in the case of rejecting PUT or POST operations in HTTP 1.1). If a client attempts to queue multiple responses or attempts to queue a response early, MHD_queue_response will fail (and return MHD_NO).

The callback function for the respective URL will be called at least twice. The first call happens after the server has received the headers. The client should use the last void** argument to store internal context for the session. The first call to the callback function is mostly for this type of initialization and for internal access checks. At least, the callback function should "remember" that the first call with just the headers has happened. Queueing a response during the first call (for a given connection) should only be used for errors – if the client queues a response during this first call, a "100 CONTINUE" response will be suppressed, the request body will not be read and the connection will be closed after sending the response. After the first call, the callback function will be called with upload data. Until *upload_data_size is zero, the callback may not queue a response, any such attempt will fail. The callback function should update *upload_data_size to indicate how many bytes were processed. Depending on available buffer space, incremental processing of the upload maybe required. Once all of the upload data has been processed, MHD will call the callback a second time with *upload_data_size being zero. At this point, the callback should queue a "normal" response. If queueing a response is not possible, the callback may either block or simply not queue a response depending on the threading mode that is used. If the callback does not queue a response at this point, MHD will either (eventually) timeout the connection or keep calling it.

Parsing of POST requests
MHD includes a set of three functions for parsing and processing data received in POST requests. The functions allow incremental parsing and processing of POST data. Only a tiny fraction of the overall POST data needs to fit into memory. As a result, applications using MHD can support POST requests of arbitrary size. POST data is processed by providing MHD with a callback function that is called on portions of the received values. The POST parser itself is invoked repeatedly whenever more input bytes become available. MHD supports both uri- and multipart/form-encoded POST data.
Memory Management
The application can determine the size of buffers that MHD should use for handling of HTTP requests and parsing of POST data. This way, MHD users can trade-off processing time and memory utilization. Applications can limit the overall number of connections MHD will accept, as well as the total amount of memory used per connection. MHD will gracefully handle all out-of-memory situations (by closing the connection and cleaning up any remaining state).
Related projects
Projects that use libmicrohttpd
If you write an application that uses libmicrohttpd, please let us know so that we can add you to the list!
Alternatives
If you are aware of a competing library that might be a better fit for some developers, please let us know so that we can add it to the list!

Licensing

Libmicrohttpd is free software; you can redistribute it and/or modify it under the GNU LGPL v2.1 or at your option any later version. If you disable HTTPS/TLS support, you can also choose the second license, the eCos License. If you have questions about licensing, please contact the maintainer.