darkhttpd

You can run darkhttpd using Docker by building the image from the provided Dockerfile and then running it with volume mounts and port mappings.

1. Build the image:

docker build -t darkhttpd .

2. Run the container: To serve files from ~/dev/mywebsite on http://localhost:8080/:

docker run -p 8080:80 -v ~/dev/mywebsite:/var/www/htdocs:ro darkhttpd

To build the darkhttpd binary, run the make command in the repository root. If your C compiler is not aliased to cc, you must specify it using the CC environment variable.

make
# Or if using gcc specifically:
CC=gcc make

To run the test suite, use make test.

On FreeBSD, you may need to provide specific environment variables for the test runner:

ASAN_OPTIONS=" " PYTHON=python3.11 make test

darkhttpd is a lightweight web server designed to serve static content. It requires a root directory as a positional argument. By default, it uses port 80 if run as root, or 8080 otherwise.

Basic Usage

Serve a directory on the default port:

./darkhttpd /var/www/htdocs

Serve a specific directory on a custom port:

./darkhttpd ~/public_html --port 8081

Serve only a single file instead of a directory:

./darkhttpd ~/public_html/index.html --single-file

darkhttpd provides several mechanisms to enhance security:

• --chroot: Use chroot to restrict the server to the specified directory (requires root privileges).
• --uid <user> --gid <group>: Drop privileges to a specific user and group.
• --log <file>: Log accesses (including Referer and User-Agent) to a specified file.
• --pidfile <path> --daemon: Run the server in the background and create a PID file.

Example: Run as a daemon with a PID file:

./darkhttpd /var/www/htdocs --pidfile /var/run/httpd.pid --daemon

To serve files with custom MIME types, provide a file containing mappings in the format content-type extension. Use the --mimetypes flag to specify this file.

Example: Serving .dat files as text/plain:

$ cat extramime
text/plain  dat
$ ./darkhttpd /var/www/htdocs --mimetypes extramime

You can control how darkhttpd binds to network interfaces and manages connections using the following flags:

• --port <port>: Specify a custom port.
• --addr <ip>: Bind to a specific IP address (useful for multi-homed systems).
• --maxconn <number>: Limit the number of simultaneous connections.

Example: Bind to 127.0.0.1 on port 8080:

./darkhttpd ~/public_html --port 8080 --addr 127.0.0.1

You can customize HTTP responses and handle host-based redirects:

• --header '<header>': Add an arbitrary custom response header (e.g., for CORS).
• --index <file>: Use a specific file instead of index.html as the default index.
• --forward <host> <url>: Perform a 301 redirect for a specific host.
• --forward-all <url>: Redirect all requests to a catch-all URL.

Example: Allow all cross-origin requests:

./darkhttpd /var/www/htdocs --header 'Access-Control-Allow-Origin: *'