darkhttpd

Serve files via a simple web server

TLDR

Start server serving the specified document root

$ darkhttpd [path/to/docroot]

Start server on specified port (port 8080 by default if running as non-root user)

$ darkhttpd [path/to/docroot] --port [port]

Listen only on specified IP address (by default, the server listens on all interfaces)

$ darkhttpd [path/to/docroot] --addr [ip_address]

directory
The root directory from which to serve files. If not specified, the current working directory will be used. This directory should typically contain the 'index.html' file for the root path.

-p
Specifies the TCP port number on which darkhttpd will listen for incoming connections. The default port is typically 80 (HTTP) but may be 8000 if not running as root.

-i

    Binds the server to a specific IP address or hostname, rather than listening on all available network interfaces.

-a
    Enables basic HTTP authentication for all served content using the provided username and password pair.

-r
    Enables chroot functionality. The server will change its root directory to the specified directory argument before dropping privileges, enhancing security by confining file access.

-d
    Daemonizes the server process, causing it to run in the background and detach from the controlling terminal.

-e
    Specifies a directory containing custom HTTP error pages (e.g., '404.html', '500.html') to be served on errors.

-l
    Logs all incoming requests (similar to an Apache-style access log) to the specified file path.

-c
    Changes the current working directory to the specified path before starting the server. This is similar to running `cd ` first.

-z
    Disables directory indexing. If a directory without an 'index.html' or similar default file is accessed, it will result in a 403 Forbidden error instead of a directory listing.

-v
    Enables verbose logging, providing more detailed output to standard error (stderr), useful for debugging and troubleshooting.

-h
    Displays a brief help message with command-line options and then exits.

DESCRIPTION

darkhttpd is a very small, single-file, and highly efficient HTTP/1.1 web server created by Niels Provos. It is renowned for its minimalist design, making it ideal for serving static content, quick file sharing, or embedding in small systems. Unlike feature-rich servers, darkhttpd focuses solely on core functionality: serving files quickly and securely with minimal overhead. It supports essential HTTP/1.1 features like directory listings, basic authentication, range requests, and 'If-Modified-Since' headers.

Its compact codebase (often just a single C file) contributes to its security by making it easier to audit and reducing the attack surface. It does not support scripting languages (like PHP or CGI) or HTTPS directly, requiring a reverse proxy for SSL encryption. Despite its simplicity, it is a robust choice for scenarios where a lightweight, secure, and static file server is needed without the complexity of larger alternatives.

CAVEATS

darkhttpd does not natively support HTTPS/SSL encryption; a separate reverse proxy (such as Nginx or HAProxy) is required to add SSL capabilities. It also explicitly lacks support for dynamic content generation via scripting languages (CGI, PHP, Python, etc.) and advanced features like virtual hosts, URL rewriting, or sophisticated access control lists. While designed with security in mind, its robustness in production environments still relies on proper system configuration, judicious use of options like -r (chroot), and running as a non-root user after binding to privileged ports.

SECURITY BEST PRACTICES

When running darkhttpd, especially in exposed environments, it is highly recommended to use the -r (chroot) option to confine the server to its designated content directory, limiting potential system compromise. Additionally, ensure the server runs as a non-root user with minimal privileges. For ports below 1024, bind as root then drop privileges, or use `setcap`.
Consider implementing a firewall (e.g., `ufw`, `iptables`) to restrict access to the server's port to only necessary IP addresses or networks.

COMMON USE CASES

darkhttpd is perfectly suited for:

Quickly sharing files over a local network or VPN.
Serving static assets (HTML, CSS, JavaScript, images) for web development or testing environments.
Embedding within constrained environments, specialized appliances, or IoT devices due to its small footprint.
As a lightweight backend for simple single-page applications (SPAs) or APIs where static file serving is the primary requirement.

HISTORY

darkhttpd was developed by Niels Provos, a well-known security researcher and developer, with a strong emphasis on minimalism and security. Its design reflects a philosophy of 'less is more' in terms of features, aiming for a small, auditable, and reliable codebase. It has been used in various contexts where a straightforward, static web server is needed without the overhead and complexity of larger alternatives. Its development history is marked by consistent adherence to its original design principles of being tiny, fast, and secure.