Darkhttpd: Difference between revisions

From Alpine Linux
mNo edit summary
m (→‎man darkhttpd: updated)
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Draft}}


Darkhttpd is a simple, fast HTTP 1.1 web server for static content.  It does not support PHP or CGI etc but is designed to serve static content, which it does very well.  Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]
Darkhttpd is a simple, fast HTTP 1.1 web server for static content.  It does not support PHP or CGI etc but is designed to serve static content, which it does very well.  Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]
Line 11: Line 10:
= Configure =
= Configure =


Default location of files to serve: {{Path|/var/www/localhost/hdocs}}
Default location of files to serve: {{Path|/var/www/localhost/htdocs}}


Default log path: {{Path|/var/log/darkhttpd/access.log}}
Default log path: {{Path|/var/log/darkhttpd/access.log}}
Line 28: Line 27:
</pre>
</pre>


So by default we will serve pages from {{Path|/var/www/localhost/hdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/hdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.  
The default values have been chosen to provide sane, secure settings.  
Line 36: Line 35:
For a full list of available options, run: {{Cmd|darkhttpd}}
For a full list of available options, run: {{Cmd|darkhttpd}}


and amend the <code>command_args</code> line as you see fit.
and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:
 
<pre>
#! /sbin/runscript
 
description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>


= Use =
= Use =


Filesharing is made easy; simply add your files under {{Path|/var/www/localhost/hdocs}}  
Filesharing is made easy; simply add your files under the server root, by default {{Path|/var/www/localhost/htdocs}}


== Test ==
== Test ==


Create a test page under {{Path|/var/www/localhost/hdocs}}
Create a test page under the server root, by default {{Path|/var/www/localhost/htdocs}}


{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}
{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}
Line 77: Line 88:


To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}
To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}
= Troubleshooting =
* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>
This error message appears to be benign and of no consequence so can be ignored.  I can only replicate this error on a VMWare vSphere client.
* If the daemon will not start, ensure you haven't made a syntax error in the init script.
* Ensure the daemon is running with {{Cmd|rc-status}}
* Make use of the logs to check it is receiving requests.  To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server.  If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.


= man darkhttpd =
= man darkhttpd =
<pre>
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.12, copyright (c) 2003-2016 Emil Mikulic.
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]
usage: darkhttpd /path/to/wwwroot [flags]
 
flags: --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.
 
--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.


flags:  --port number (default: 8080, or 80 if running as root)
--chroot (default: don't chroot)
                Specifies which port to listen on for connections.
Locks server into wwwroot directory for added security.


        --addr ip (default: all)
--daemon (default: don't daemonize)
                If multiple interfaces are present, specifies
Detach from the controlling terminal and run in the background.
                which one to bind the listening port to.


        --maxconn number (default: system maximum)
--index filename (default: index.html)
                Specifies how many concurrent connections to accept.
Default file to serve when a directory is requested.


        --log filename (default: stdout)
--no-listing
                Specifies which file to append the request log to.
Do not serve listing if directory is requested.


        --chroot (default: don't chroot)
--mimetypes filename (optional)
                Locks server into wwwroot directory for added security.
Parses specified file for extension-MIME associations.


        --daemon (default: don't daemonize)
--default-mimetype string (optional, default: application/octet-stream)
                Detach from the controlling terminal and run in the background.
Files with unknown extensions are served as this mimetype.


        --index filename (default: index.html)
--uid uid/uname, --gid gid/gname (default: don't privdrop)
                Default file to serve when a directory is requested.
Drops privileges to given uid:gid after initialization.


        --mimetypes filename (optional)
--pidfile filename (default: no pidfile)
                Parses specified file for extension-MIME associations.
Write PID to the specified file.  Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.


        --uid uid/uname, --gid gid/gname (default: don't privdrop)
--no-keepalive
                Drops privileges to given uid:gid after initialization.
Disables HTTP Keep-Alive functionality.


        --pidfile filename (default: no pidfile)
--forward host url (default: don't forward)
                Write PID to the specified file. Note that if you are
Web forward (301 redirect).
                using --chroot, then the pidfile must be relative to,
Requests to the host are redirected to the corresponding url.
                and inside the wwwroot.
The option may be specified multiple times, in which case
the host is matched in order of appearance.


        --no-keepalive
--forward-all url (default: don't forward)
                Disables HTTP Keep-Alive functionality.
Web forward (301 redirect).
All requests are redirected to the corresponding url.


        --forward host url (default: don't forward)
--no-server-id
                Web forward (301 redirect).
Don't identify the server type in headers
                Requests to the host are redirected to the corresponding url.
or directory listings.
                The option may be specified multiple times, in which case
                the host is matched in order of appearance.


        --no-server-id
--ipv6
                Don't identify the server type in headers
Listen on IPv6 address.
                or directory listings.
</pre>
</pre>
[[Category:Server]]

Revision as of 11:33, 29 March 2017

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to Lighttpd for running an Alpine mirror

For a full list of features see the darkhttpd homepage

Install

apk add darkhttpd

Configure

Default location of files to serve: /var/www/localhost/htdocs

Default log path: /var/log/darkhttpd/access.log

There's no configuration file for darkhttpd, everything is controlled from the command line or in our case the OpenRC init file, which is stored in /etc/init.d/darkhttpd and by default looks like this:

#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"

So by default we will serve pages from /var/www/localhost/htdocs and darkhttpd will run as a background daemon, chrooted to /var/www/localhost/htdocs with a user of darkhttpd and group of www-data. Logs will go to /var/log/darkhttpd/access.log. The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run:

darkhttpd

and amend the command_args line as you see fit. For example, you might wish to serve files from /var/files instead, so you can edit the /etc/init.d/darkhttpd file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"

Use

Filesharing is made easy; simply add your files under the server root, by default /var/www/localhost/htdocs

Test

Create a test page under the server root, by default /var/www/localhost/htdocs

echo "this is a test page" > /var/www/localhost/htdocs/index.html

Note: You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.

Start the daemon:

rc-service darkhttpd start

Output should be something like this:

 * Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100                                

Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile:

tail /var/log/darkhttpd/access.log

Controlling darkhttpd status

Stop, start and restart the daemon in the usual fashion:

rc-service darkhttpd start

rc-service darkhttpd stop

rc-service darkhttpd restart

Auto-start darkhttpd at boot

To add the daemon to the default runlevel so it auto-starts at boot, do:

rc-update add darkhttpd

Troubleshooting

  • When restarting the daemon you may see an error message:
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

  • If the daemon will not start, ensure you haven't made a syntax error in the init script.
  • Ensure the daemon is running with

    rc-status

  • Make use of the logs to check it is receiving requests. To do this, run

    tail -f /var/log/darkhttpd/access.log

    and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?

Use 'Ctrl C' to exit back to the prompt when finished testing.

man darkhttpd

darkhttpd/1.12, copyright (c) 2003-2016 Emil Mikulic.
usage:	darkhttpd /path/to/wwwroot [flags]

flags:	--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.

	--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.

	--chroot (default: don't chroot)
		Locks server into wwwroot directory for added security.

	--daemon (default: don't daemonize)
		Detach from the controlling terminal and run in the background.

	--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.

	--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.

	--no-keepalive
		Disables HTTP Keep-Alive functionality.

	--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.

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

	--ipv6
		Listen on IPv6 address.