Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
drood(8)		  BSD System Manager's Manual		      drood(8)

NAME
     Drood -- Minimal Event-Driven HTTP/1.1 Server

SYNOPSIS
     drood -r <server-root> [-i	<interface> -p <port> -e <root resource> -d
	   <scgi-dir> -m <instances> -a	<max connections> -t <read timeout> -w
	   <write timeout> -u <user> -g	<group>	-l <log	file> -s
	   <host|port|suffix> -x -c]

DESCRIPTION
     Drood is a	small, fast, insecure, event-driven web	server.

   DROOD SUPPORTS:
     +o	 IPv4 and IPv6 connections.

     +o	 HEAD, GET, and	POST request methods.

     +o	 HTTP/1.1 persistent connections.

     +o	 Name-based virtual hosting.

     +o	 SCGI forwarding.

     +o	 WebSocket forwarding.

     +o	 A custom pipelining extension described in droodpipe.8

     +o	 Gzip content-encoding.

     +o	 Request logging.

     +o	 Graceful stops	and restarts.

   DROOD DOES NOT SUPPORT:
     +o	 HTTP/2.

     +o	 TLS encrypted connections.

     +o	 Plain CGI.

     +o	 Access	authentication.

     +o	 Content negotiation beyond "Accept-Encoding", "If-Modified-Since",
	 and "If-Unmodified-Since".  The only content encoding supported is
	 gzip.

     +o	 Etags

     +o	 Directory listings.

     +o	 The ~user notation in URLS.

   SYSTEM CONFIGURATION
     Drood is a	hybrid server. It forks	one worker process per processor on
     the host system, and then each worker process becomes an event-driven
     server.  The master process sleeps	waiting	for signals.

     By	default, FreeBSD limits	each process to	a low number of	maximum	simul-
     taneously open descriptors.  This places a	limit on the number of connec-
     tions drood may multiplex.	 Set these values at the command-line with the
     "sysctl" utility, or enable them permanently by placing these lines in
     /etc/sysctl.conf on the host machine.  Your system	will complain about
     these values if it	lacks resources.

     kern.maxfiles=262144
     kern.maxfilesperproc=65536
     kern.kq_calloutmax=262144

     To	increase performance, drood attempts to	set the	accf_http accept fil-
     ter on the	listening socket.  For this to succeed,	you must load the mod-
     ule before	starting drood.

     kldload accf_http

     To	load the module	automatically at system	boot-up, add the following
     line to /boot/loader.conf.

     accf_http_load="YES"

   DROOD CONFIGURATION
     Drood writes its pid into /var/run/drood.pid if it	can (ie., it is
     started as	root).	You stop drood with a SIGTERM and restart it with a
     SIGHUP.

     A rc.d script is installed	in /usr/local/etc/rc.d/.  Add the following
     lines to /etc/rc.conf to start drood on system boot.  Replace the items
     in	brackets with values appropriate for your system.  These are the mini-
     mal set of	options	you should start with.	The available options are de-
     scribed in	full at	the end	of this	manual page.

     drood_enable="YES"
     drood_flags="-r <server-root> -u <user> -g	<group>"

     Start, stop, or restart drood, or determine if it is running with the
     following commands.

     /usr/local/etc/rc.d/drood start
     /usr/local/etc/rc.d/drood stop
     /usr/local/etc/rc.d/drood restart
     /usr/local/etc/rc.d/drood status

     If	you do not want	drood started on system	start, set

     drood_enable="NO"

     and use the following commands.

     /usr/local/etc/rc.d/drood forcestart
     /usr/local/etc/rc.d/drood forcestop
     /usr/local/etc/rc.d/drood forcerestart
     /usr/local/etc/rc.d/drood forcestatus

   GZIP	CONTENT	ENCODING
     To	enable gzip content-encoding for static	resources, manually gzip the
     those resources.  The original resources must be available	in the same
     directory for clients which cannot	handle the encoding.  Gzipped versions
     must have the ".gz" filename suffix.

     Drood does	not compare the	modification times of the uncompressed and
     compressed	resources.  Drood sends	a compressed resource if it exists, it
     is	readable, and the client wants it.  You	can keep Makefiles in your
     html directories to keep your compressed resources	up to date with	gzip
     -k.  Drood	does not provide directory listings to clients,	so clients
     cannot know about the Makefiles.  As long as the Makefiles	are not	read-
     able by the user or group drood is	running	as, client requests for	them
     fail.

   MAPPING FILENAME SUFFIXES TO	MIME TYPES
     The mappings from filename	suffixes to MIME types that drood recognizes
     out-of-the-box are	listed in  /usr/local/etc/drood/types.tab.  Any	file
     that cannot be identified by these	mappings is identified by the server
     as	"text/plain; charset=utf-8".  To add a mapping,	add a line to
     types.tab.

     +o	 Each line contains one	filename suffix	to be mapped and one MIME type
	 separated by one or more tab characters.

     +o	 The first line	must not be blank.

     +o	 Blank lines are ignored after the first line.

     +o	 Drood refuses to run if it finds empty	fields in types.tab.

     +o	 If you	modify types.tab, you must restart drood for the changes to
	 take effect.

   REQUEST ALIASES
     Drood can substitute one request for another.  The	substitution mappings
     are stored	in /usr/local/etc/drood/aliases.tab.  To create	a substitu-
     tion, add a line to aliases.tab.

     +o	 Each line contains one	original request and one substitution sepa-
	 rated by one or more tab characteres.

     +o	 The first line	must not be blank.

     +o	 Blank lines are ignored after the first line.

     +o	 Drood refuses to run if it finds empty	fields in aliases.tab.

     +o	 If you	modify aliases.tab, you	must restart drood for the changes to
	 take effect.

     Request mapping is	used to	shorten	dynamic	URLs.  All virtual hosts share
     the virtual SCGI directory, so request mapping affects all	virtual	hosts.
     For example, if you have configured drood to forward requests for re-
     sources with the .scgi suffix to an SCGI application server (-s option),
     but you want to simplify your URLS	so that	they do	not contain the	SCGI
     path or the .scgi suffix, you could use substitions similar to the	fol-
     lowing.

     /foobar<tab>/cgi-bin/foobar.scgi
     /tooley<tab>/cgi-bin/tooley.scgi?special

     If	the original request contains GET parameters, they are appended	to the
     substitution:

     /foobar?tiddlywinks=10 => /cgi-bin/foobar.scgi?tiddlywinks=10
     /tooley?hooply=mugwump => /cgi-bin/tooley.scgi?special&hooply=mugwump

   PERCENT ESCAPES
     In	the resource names of requests,	drood will convert every sequence of
     bytes consisting of a percent sign	followed by two	hexadecimal digits
     into the byte specified by	the hexadecimal	value.	Whitespace, semi-
     colons, and percent signs must all	be percent-escaped to be recognized in
     resource names.

   COMPOUND REQUESTS WITH PIPELINED RESPONSES
     Drood recognizes compound requests	as described the droodpipe.8 manual
     and delivers pipelined responses to those requests.

   SCGI	AND WEBSOCKETS
     You can configure drood to	forward	request	to SCGI	and WebSocket servers.
     See the -s	and options in the following section of	the manual.

   COMMAND-LINE	OPTIONS
     The following options are recognized.  Only the -r	option is required.

     -a	 The -a	option specifies the maximum number of simultaneous connec-
	 tions that each drood process will service.  If not set, drood	will
	 continue to accept connections	until it runs out memory.

     -m	 The -m	option specifies how many worker processes are run and de-
	 faults	to the number of CPUs on the host system.

     -r	 The -r	option is mandatory and	specifies the server root directory.

	 The resources served-up by drood are determined by the	"Host" header
	 of requests.

	 +o   For every hostname	you want to be recognized by the server, cre-
	     ate an identically-named subdirectory of the server root direc-
	     tory.

	 +o   Place the files for each virtual host into	its identically-named
	     subdirectory.

	 +o   Name one directory	"default".  This directory is used to fulfill
	     static requests when no "Host" header is supplied by a client
	     (eg., HTTP/1.0 requests).	You can	make this directory a symbolic
	     link.

	 +o   If	you want a directory to	be used	for more than one hostname,
	     create symbolic links for the extra hostnames.

	 An example root directory follows.  Only the first entry is an	actual
	 virtual host subdirectory.  The rest are links	to it.

	 mammothcheese.ca	      -> actual	subdirectory (IPv4)
	 www.mammothcheese.ca	      -> link to above (IPv4)
	 default		      -> link (IPv4/IPv6 HTTP/1.0)

	 If you	want to	accept connections specified by	IP address, include
	 links for valid addresses:

	 69.28.67.32		      -> link (IPv4 Decimal)
	 127.0.0.1		      -> link (IPv4 Loopback)

	 If you	instruct drood to listen on a port other than port 80 (-p op-
	 tion),	that port number appears in client "Host" headers.  Adjust
	 your entries accordingly:

	 mammothcheese.ca:8080	      -> actual	subdirectory (IPv4)
	 www.mammothcheese.ca:8080    -> link to above
	 (etc)

     -e	 The root resource of all virtual hosts	defaults to a static resource
	 named "index.html", which may be a link.  Change the name of the re-
	 source	with the -e option.  This value	specified names	the root re-
	 source	of all virtual hosts.  The value must not begin	with a vir-
	 gule: /.

	 If a request is received for any directory, that request is inter-
	 preted	as a request for the root resource residing in the directory.

	 You can specify a dynamic resource as the root	resource with the -e
	 option.  If you do so,	include	the -d option to tell the server where
	 SCGI programs live.

	 drood -r /usr/local/www/drood -d cgi-bin -e cgi-bin/index.cgi

     -c	 The -c	option causes drood to reject cross-origin HTTP/1.1 requests
	 for all static	resources except those whose filenames end with	.html,
	 .tgz, .txz, or

     -d	 The -d	option specifies a virtual directory that is used in URLS to
	 specify SCGI and WebSocket requests.  The value given to this option
	 cannot	contain	the directory separator	character "/", nor can it be
	 ".." or ".".  This directory is a virtual entity and should not exist
	 in the	filesystem.

	 All virtual hosts share the SCGI virtual directory.  If you want to
	 know what hostname a server has been invoked for, examine the
	 SERVER_NAME environment variable.  If no "Host" header	was supplied
	 with a	request, SERVER_NAME is	set to the string "default".

	 +o   SCGI responses must contain a "Content-Type" or "Location"	header
	     and be separated from response bodies with	a blank	line.  Other
	     headers are optional and are unaltered by drood.

	 +o   DO	NOT send Status	headers.  Drood	creates	its own	status head-
	     ers.

	     +o	 If a "Location" header	is present, drood creates a "303 See
		 Other"	status header.

	     +o	 If no "Location" header is present, drood creates a "200 OK"
		 status	header.

	 +o   Always send response bodies unless	your responses contain Loca-
	     tion headers.  Report errors to clients in	HTML response bodies.

	 +o   If	an SCGI	server does not	send a Content-Length header and the
	     client request is an HTTP/1.1 request, then drood automatically
	     adds the "Transfer-Encoding: chunked" header and chunks the re-
	     sponse body for the client.

	 Requests for SCGI resources must include the SCGI path	in their URLs
	 because this is how drood differentiates static requests from dynamic
	 requests.  If -d is "cgi-bin",	then the following is a	request	to run
	 foobar.cgi.

	 http://host.domain/cgi-bin/foobar.cgi

	 The following environment variables are set for SCGI programs.	 Drood
	 does not propagate cookies to SCGI servers because drood is an	inse-
	 cure server.

	 SCGI
	 SCRIPT_NAME
	 QUERY_STRING
	 SERVER_SOFTWARE
	 HTTP_USER_AGENT
	 HTTP_REFERRER
	 HTTP_ORIGIN
	 SERVER_NAME
	 SERVER_PORT
	 CONTENT_TYPE
	 REMOTE_ADDR
	 GZIP

	 If the	client can receive gzipped data, GZIP is set to	1.  If the
	 client	cannot receive gzipped data, GZIP is set to 0.	If an SCGI
	 server	gzips its output, the program must generate a

	 Content-Encoding: gzip\r\n"

	 header	to notify clients of the encoding.

     -s	 The -s	option informs drood what dynamic resources are	supplied by
	 SCGI and WebSocket servers.

	 Drood uses the	suffixes of dynamic resources to determine which re-
	 sources are forwarded to which	servers.  You register each suffix to
	 be forwarded with a separate -s option.

	 Each option value has this form:  <host>|<port>|<suffix>.

	 +o   <host> is the hostname of the SCGI	server or its IP address.

	 +o   <port> is the port	number the SCGI	server is listening on.

	 +o   <suffix> is the filename suffix to	associate with this SCGI
	     server.  The suffix value must not	contain	a dot.

	 Requests for items in the SCGI	directory whose	filenames are termi-
	 nated by <suffix> are forwarded to the	SCGI server at <host> listen-
	 ing on	<port>.

	 For example, to forward all requests whose URLs match this pattern

	 http://hostname.domain/cgi-bin/*.scgi

	 to a local server running on port 4000, use the following command
	 line.	Note that it is	necessary to quote the -s option value to pre-
	 vent the shell	from interpreting it as	a pipeline.

	 drood -d cgi-bin -s '127.0.0.1|4000|scgi'

	 To specify a UNIX-domain SCGI server, leave the <host>	part empty,
	 and put the absolute path to the listening socket in the <port> part.

	 drood -d cgi-bin -s '|/full/path/to/socket|scgi'

	 To specify a TCP WebSocket server, prepend "ws:<protocols>:" to the
	 hostname or IP	address	of the server.	The <protocols>	field may be
	 empty.

	 drood -d cgi-bin -s 'ws::127.0.0.1|8000|echo'

	 To specify a UNIX-domain WebSocket server, leave the hostname out of
	 the <host> part and put the absolute path to the listening socket
	 into the <port> part.

	 drood -d cgi-bin -s 'ws::|/var/run/echo.socket|echo'

	 If you	want to	specify	the sub-protocols that a WebSocket server sup-
	 ports,	place the list of sub-protocols	into the <protocols> part of
	 the <host> field.  Protocol names must	be listed in order of priority
	 and must be separated by commas.

	 Drood completes the WebSocket handshake and connects to the WebSocket
	 server.  Drood	then sends to the server 2 newline-terminated lines.
	 The first line	names the virtual host to which	the client submitted
	 its request.  The second line names the sub-protocol selected during
	 the WebSocket handshake.

	 mammothcheese.ca<newline>
	 chat<newline>

	 After sending the protocol line, drood	exchanges data between the
	 client	and the	WebSocket server for the lifetime of the connection.
	 Drood does not	modify the exchanged data in any way.  WebSocket
	 servers are responsible for implementing the WebSocket	protocol to
	 commmunicate with their clients.

     -p	 The -p	option specifies the port to listen on.	 This defaults to 80.

     -i	 The -i	option limits drood to accepting connections only from a spec-
	 ified interface.  Supply the IP address of the	desired	interface as
	 argument.  By default,	drood accepts connections on all interfaces
	 capable of IPv4 or IPv6.

     -u

     -g	 The -u	and the	-g options specify the user and	group of drood server
	 processes.  If	not specified, both values default to "nobody".

     -t	 The -t	option specifies the value of the read timeout in seconds.
	 When reading a	request	from a client, drood drops the connection if
	 it cannot read	the complete request header within 20 seconds.	To
	 change	this value, provide a number in	the range of 1-60 as argument.

     -w	 The -w	option specifies the value of the write	timeout	in minutes.
	 When writing a	response to a client, drood drops the connection if 60
	 minutes have elapsed.	To change this value provide a number in range
	 of 0-120 minutes as argument.	Setting	this value to 0	disables the
	 write timeout.

     -x	 The -x	option prevents	drood from becoming a daemon.  Drood runs in
	 the foreground	of the terminal	where it was started and is stopped
	 with signals (ie., Control-C).	 When the -x option is present,	drood
	 does not write	its pid	to /var/run/drood.pid.

     -l	 The -l	option turns-on	request	logging.  The option specifies the
	 fully-qualified filename of a file to hold the	log.  If the file does
	 not exist, drood attempts to create it.  The file or the directory in
	 which it resides must be writeable drood at startup before it changes
	 to the	user and group specified by the	-u and -g options.

	 Logging is turned-off by default.  Request logging differs from
	 transaction logging in	that requests are logged as they arrive	in-
	 stead of after	they have been processed.  In particular, this means
	 the response code and the number of bytes transferred are not
	 recorded in log records, because they are not known at	the time re-
	 quests	are logged.  Drood does	not use	the common log file format.
	 It uses its own, simpler-to-parse format.

	 Each line of the logfile is a complete	request	record.	 The fields of
	 request records are ordered as	follows	with all fields	separated by
	 single	| characters.

	 +o   The date and time of the request with this	strftime(3) format.
	     %a, %d %b %Y %H:%M:%S %Z

	 +o   The client	IP address.  The IP address is expressed in IPv6 pre-
	     sentation format.	IPv4 clients' addresses	are written as
	     IPv4-mapped IPv6 addresses.

	 +o   The request User-Agent header or "no user-agent header".

	 +o   The request method

	 +o   The request URL

	 +o   The request Referer (sic) header or "no referrer header".

	 Add the following line	to /usr/local/etc/newsyslog.conf.d/newsys-
	 log.conf to instruct newsyslog(8) to turn over	the request log	every
	 night at midnight.  The five most recent logfiles are renamed and
	 kept on-hand.

	 /var/log/drood-requests.log 600 5 * @T00 B /var/run/drood.pid

	 Do use	the B option.  Do not use the Z	option.	 The B option prevents
	 newsyslog from	inserting a turnover message and timestamp at the end
	 of the	old logfile.  The Z option instructs newsyslog to compress the
	 old logfile.  When drood restarts, new	processes use the new logfile,
	 but old processes that	use the	old logfile may	persist	until all ac-
	 tive connections have been closed.

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

				 Oct 08, 2016

NAME | SYNOPSIS | DESCRIPTION | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=drood&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help