From 1845a4aa93200b92cfdf93c3d5038e01646b5ef9 Mon Sep 17 00:00:00 2001
From: Emil Mikulic <emikulic@gmail.com>
Date: Mon, 18 Jan 2021 00:37:47 +1100
Subject: [PATCH] Update readme: add introduction, markdown.

---
 README.md | 138 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 110 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index b9b121b..cd85400 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,145 @@
-How to build darkhttpd
-----------------------
+# darkhttpd
+
+https://unix4lyfe.org/darkhttpd/
+
+When you need a web server in a hurry.
+
+Features:
+* Simple to set up:
+  * Single binary, no other files, no installation needed.
+  * Standalone, doesn't need `inetd` or `ucspi-tcp`.
+  * No messing around with config files - all you have to specify is the `www` root.
+* Written in C - efficient and portable.
+* Small memory footprint.
+* Event loop, single threaded - no fork() or pthreads.
+* Generates directory listings.
+* Supports HTTP GET and HEAD requests.
+* Supports Range / partial content. (try streaming music files or resuming a download)
+* Supports If-Modified-Since.
+* Supports Keep-Alive connections.
+* Supports IPv6.
+* Can serve 301 redirects based on Host header.
+* Uses sendfile() on FreeBSD, Solaris and Linux.
+* Can use acceptfilter on FreeBSD.
+* At some point worked on FreeBSD, Linux, OpenBSD, Solaris.
+* ISC license.
+* suckless.org says [darkhttpd sucks less](http://suckless.org/rocks/).
+
+Security:
+* Can log accesses, including Referer and User-Agent.
+* Can chroot.
+* Can drop privileges.
+* Impervious to `/../` sniffing.
+* Times out idle connections.
+* Drops overly long requests.
+
+Limitations:
+* Only serves static content - no CGI.
+
+## How to build darkhttpd
 
 Simply run make:
-  $ make
 
+```
+make
+```
 
-
-How to run darkhttpd
---------------------
+## 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
+```
+./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
+
+```
+./darkhttpd ~/public_html --addr 192.168.0.1
+```
 
 Serve at most 4 simultaneous connections:
-  $ ./darkhttpd ~/public_html --maxconn 4
+
+```
+./darkhttpd ~/public_html --maxconn 4
+```
 
 Log accesses to a file:
-  $ ./darkhttpd ~/public_html --log access.log
+
+```
+./darkhttpd ~/public_html --log access.log
+```
 
 Chroot for extra security (you need root privs for chroot):
-  $ ./darkhttpd /var/www/htdocs --chroot
+
+```
+./darkhttpd /var/www/htdocs --chroot
+```
 
 Use default.htm instead of index.html:
-  $ ./darkhttpd /var/www/htdocs --index default.htm
+
+```
+./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
+
+```
+$ cat extramime
+text/plain  dat
+$ ./darkhttpd /var/www/htdocs --mimetypes extramime
+```
 
 Drop privileges:
-  $ ./darkhttpd /var/www/htdocs --uid www --gid www
+
+```
+./darkhttpd /var/www/htdocs --uid www --gid www
+```
 
 Use acceptfilter (FreeBSD only):
-  $ kldload accf_http
-  $ ./darkhttpd /var/www/htdocs --accf
+
+```
+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
+
+```
+./darkhttpd /var/www/htdocs --pidfile /var/run/httpd.pid --daemon
+```
 
 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
+
+```
+./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
+
+```
+./darkhttpd /var/www/htdocs --forward example.com http://www.example.com \
+  --forward-all http://catchall.example.com
+```
 
 Commandline options can be combined:
-  $ ./darkhttpd ~/public_html --port 8080 --addr 127.0.0.1
+
+```
+./darkhttpd ~/public_html --port 8080 --addr 127.0.0.1
+```
 
 To see a full list of commandline options,
 run darkhttpd without any arguments:
-  $ ./darkhttpd
 
-vim:set ts=2 sw=2 et tw=80:
+```
+./darkhttpd
+```
+
+Enjoy.