darkhttpd(1)

General Commands Manual

darkhttpd(1)

NAME

darkhttpd - HTTP 1.1 web server for static content

SYNOPSIS

darkhttpd /path/to/wwwroot flags

DESCRIPTION

--port number (default: 8080, or 80 if running as root)

Specifies which port to listen on for connections. Pass 0 to let the system choose any free port for you.

--addr ip (default: all)

If multiple interfaces are present, specifies which one to bind the listening port to.

--ipv6

Listen on IPv6 address.

--daemon (default: don't daemonize)

Detach from the controlling terminal and run in the background.

--pidfile filename (default: no pidfile)

Write PID to the specified file. Note that if you are using --chroot, then the pidfile must be relative to, and inside the wwwroot.

--maxconn number (default: system maximum)

Specifies how many concurrent connections to accept.

--log filename (default: stdout)

Specifies which file to append the request log to.

--syslog

Use syslog for request log.

--index filename (default: index.html)

Default file to serve when a directory is requested.

--no-listing

Do not serve listing if directory is requested.

--mimetypes filename (optional)

Parses specified file for extension-MIME associations.

--default-mimetype string (optional, default: application/octet-stream)

Files with unknown extensions are served as this mimetype.

--uid uid/uname, --gid gid/gname (default: don't privdrop)

Drops privileges to given uid:gid after initialization.

--chroot (default: don't chroot)

Locks server into wwwroot directory for added security.

--no-keepalive

Disables HTTP Keep-Alive functionality.

--single-file

Only serve a single file provided as /path/to/file instead of a whole directory.

--hide-dotfiles

Don't serve dotfiles.

--forward host url (default: don't forward)

Web forward (301 redirect). Requests to the host are redirected to the corresponding url. The option may be specified multiple times, in which case the host is matched in order of appearance.

--forward-all url (default: don't forward)

Web forward (301 redirect). All requests are redirected to the corresponding url.

--forward-https

If the client requested HTTP, forward to HTTPS. This is useful if darkhttpd is behind a reverse proxy that supports SSL.

--no-server-id

Don't identify the server type in headers or directory listings.

--timeout secs (default: 30)

If a connection is idle for more than this many seconds, it will be closed. Set to zero to disable timeouts.

--auth username:password

Enable basic authentication. This is INSECURE: passwords are sent unencrypted over HTTP, plus the password is visible in ps(1) to other users on the system.

--header 'Header: Value'

Add a custom header to all responses. This option can be specified multiple times, in which case the headers are added in order of appearance.

EXAMPLES

How to run darkhttpd

Serve /var/www/htdocs on the default port (80 if running as root, else 8080):

darkhttpd /var/www/htdocs

Serve `~/public_html` on port 8081:

darkhttpd ~/public_html --port 8081

Only bind to one IP address (useful on multi-homed systems):

darkhttpd ~/public_html --addr 192.168.0.1

Serve at most 4 simultaneous connections:

darkhttpd ~/public_html --maxconn 4

Log accesses to a file:

darkhttpd ~/public_html --log access.log

Chroot for extra security (you need root privs for chroot):

darkhttpd /var/www/htdocs --chroot

Use default.htm instead of index.html:

darkhttpd /var/www/htdocs --index default.htm

Add mimetypes - in this case, serve .dat files as text/plain:

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

Drop privileges:

darkhttpd /var/www/htdocs --uid www --gid www

Use acceptfilter (FreeBSD only):

kldload accf_http
darkhttpd /var/www/htdocs --accf

Run in the background and create a pidfile:

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

Serve only one file instead of a whole directory:

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

Web forward (301) requests for some hosts:

darkhttpd /var/www/htdocs --forward example.com http://www.example.com 


  --forward secure.example.com https://www.example.com/secure

Web forward (301) requests for all hosts:

darkhttpd /var/www/htdocs --forward example.com http://www.example.com 


  --forward-all http://catchall.example.com

Arbitrary custom response headers (in this case, allow all cross-origin requests):

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

Commandline options can be combined:

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

To see a full list of commandline options, run darkhttpd without any arguments:

darkhttpd

How to run darkhttpd in Docker

First, build the image.

docker build -t darkhttpd .

Then run using volumes for the served files and port mapping for access.

For example, the following would serve files from the current user's dev/mywebsite directory on http://localhost:8080/

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

AUTHORS

The man page was created by Ulysses Apokin <ulysses@altlinux.org>, based on darkhttpd --help and README.md.

2025-09-10