What is libmicrohttpd?

GNU libmicrohttpd (MHD) is a small C library that lets an application act as an HTTP 1.1 server without forking a separate process or thread pool unless you ask it to. Its design emphasises minimal footprint, straightforward API, and license compatibility (LGPL‑2.1+) making it suitable for embedded devices, CLI utilities, desktop apps, or even high‑performance back‑ends. Key features include:

• Tiny static footprint (< 60 KiB when optimised).
• Support for TLS via GnuTLS, OpenSSL, mbedTLS or libtls.
• Single‑thread, external select()/poll()/epoll(), MHD_USE_THREAD_PER_CONNECTION, or thread‑pool models.
• Streaming or memory‑buffered responses; zero‑copy iovec responses since 0.9.73.
• Helpers for POST / multipart parsing, basic/RFC 7617 authentication, IP‑based throttling, and URI escaping.

Note: As of April 2025 Ubuntu ships MHD 1.0.1, the first “1.x” release focusing on long‑term ABI stability.

Primary Handles

MHD exposes opaque pointers so your program never touches internal state directly:

• struct MHD_Daemon – the running HTTP server instance.
• struct MHD_Connection – contextual information per TCP connection.
• struct MHD_Response – the HTTP reply you build.
• struct MHD_PostProcessor – incremental POST/multipart parser.

Callback‑Centric Workflow

MHD adopts an event‑driven design. Your application registers function pointers that the library invokes when:

1. A socket becomes readable/writable (internal poller model), or
2. You call MHD_run() / MHD_run_from_select() in an external main‑loop integration.

C Source

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

#define PORT 8080
static int
answer (void *cls, struct MHD_Connection *c,
        const char *url, const char *method,
        const char *ver, const char *u, size_t *s,
        void **con_cls)
{
  static const char page[] = "Hello World\n";
  struct MHD_Response *r =
      MHD_create_response_from_buffer (strlen (page),
                                       (void *) page,
                                       MHD_RESPMEM_PERSISTENT);
  int ret = MHD_queue_response (c, MHD_HTTP_OK, r);
  MHD_destroy_response (r);
  return ret;
}

int main ()
{
  struct MHD_Daemon *d =
      MHD_start_daemon (
        MHD_USE_SELECT_INTERNALLY,
        PORT,
        NULL, NULL,            // accept-policy cb
        &answer, NULL,         // request handler cb
        MHD_OPTION_END);
  getchar ();                 // wait for ⏎
  MHD_stop_daemon (d);
  return 0;
}

Compile: gcc hello.c -lmicrohttpd -o hello Run: ./hello and visit http://localhost:8080.

Flow Chart

1. MHD accepts TCP socket → creates MHD_Connection.
2. Parses request line + headers.
3. Invokes your MHD_AccessHandlerCallback once headers are complete.
4. If request has a body and you return MHD_YES, MHD calls your MHD_ContentReaderCallback (or POST processor) chunk‑by‑chunk.
5. You craft a MHD_Response and queue it.
6. When finished, connection is either kept‑alive or closed depending on headers & flags.

Creation Helpers

Function	Typical Use‑Case
MHD_create_response_from_buffer	Small static strings held in memory.
MHD_create_response_from_fd	Efficient sendfile() of large files.
MHD_create_response_from_callback	Generate/stream data on demand (e.g., DB rows).
MHD_create_response_from_iovec	Zero‑copy scatter‑gather, new since 0.9.73.

Queuing & Headers

After constructing you attach it with MHD_queue_response(). Custom headers are applied using MHD_add_response_header().

Incremental Parsing

For application/x-www-form-urlencoded and multipart/form-data bodies call MHD_create_post_processor() inside your access‑handler, then feed chunks to MHD_post_process(). This keeps memory usage O(chunkSize) instead of O(bodySize).

Enabling TLS

Compile MHD against your preferred SSL backend (--with-ssl=gnutls|openssl|mbedtls). At runtime pass one of:

MHD_start_daemon (MHD_USE_THREAD_PER_CONNECTION    |
                  MHD_USE_TLS,      /* ← enable SSL */
                  443,
                  NULL, NULL,
                  &handler, NULL,
                  MHD_OPTION_HTTPS_MEM_KEY,  key_pem,
                  MHD_OPTION_HTTPS_MEM_CERT, cert_pem,
                  MHD_OPTION_END);

The library automatically performs the TLS handshake before invoking your access callback. Example file‑server with TLS is shipped in https_fileserver_example.c.

Built‑in Modes

• MHD_USE_SELECT_INTERNALLY – single background thread + select().
• MHD_USE_INTERNAL_POLLING_THREAD – automatically chooses poll/epoll/kqueue.
• MHD_USE_THREAD_PER_CONNECTION – naive but quick to prototype.
• MHD_OPTION_THREAD_POOL_SIZE – N‑worker model, good balance for many cores. Reddit users report outperforming nginx when tuned with 2× CPU cores.
• “External” mode: omit these flags and drive sockets yourself via MHD_get_fdset().

Settings

• Use MHD_OPTION_CONNECTION_MEMORY_LIMIT to bound RAM per connection.
• Enable TCP SO_REUSEPORT on Linux 3.9+ to allow multi‑daemon scaling.
• Prefer sendfile() or iovec responses for static assets.
• Hand‑off heavy work to worker threads via message‑queues to keep callbacks non‑blocking.

Hardening Checklist

• Always set MHD_OPTION_CONNECTION_LIMIT and reasonable timeouts.
• Disable HTTP methods you do not need; filter inside access callback.
• Validate Host header if generating absolute redirects.
• On TLS, enforce modern cipher‑suites and HSTS at the application layer.
• Sandbox (seccomp, pledge, chroot) if embedding into SUID/privileged binaries.

From Source

git clone https://git.gnunet.org/libmicrohttpd.git
cd libmicrohttpd
./bootstrap
./configure --prefix=/usr/local --enable-messages --with-ssl=openssl
make -j$(nproc)
sudo make install

Pkg‑config

Add pkg-config --cflags --libs libmicrohttpd to your build system. If you rely on CMake, use find_package(PkgConfig) ….

When to Choose MHD

• Embedding HTTP endpoints into existing C/C++ daemons.
• Writing firmware web‑UIs where every KiB matters.
• Quick prototyping of REST APIs entirely in C.

Alternatives

Library	Notes
libevent‑httpd	Part of libevent; larger code base, no built‑in TLS.
civetweb / mongoose	Header‑only single‑file; BSD/MIT licensed; no LGPL obligations.
Boost.Beast	Modern C++; header‑only, but heavier compile times.

• Official GNU Homepage – documentation, mailing list.
• Official Tutorial – step‑by‑step mini‑servers.
• Upstream Git – bleeding‑edge source, examples, texinfo manual.