gonzalo(8) FreeBSD System Manager's Manual gonzalo(8)
NAME
Gonzalo - Minimal Event-Driven HTTP/1.1 Server
SYNOPSIS
gonzalo -r <server-root> [-h <hostname> -i <interface> -p <port> -q <queue-size> -m <max-conns> -u <user> -g <group>]
DESCRIPTION
Gonzalo is a minimal, insecure, event-driven web server. Gonzalo serves
files for a single hostname. Gonzalo is Prospero's helper.
GONZALO SUPPORTS:
o IPv4 and IPv6 connections.
o HEAD and GET request methods.
o HTTP/1.1 persistent connections.
o A custom pipelining extension described in caliban.8
o Graceful stops.
GONZALO DOES NOT SUPPORT:
o Name-based virtual hosting.
o HTTP/2.
o TLS encrypted connections. Prospero(8) provides TLS.
o CGI. Prospero provides SCGI and WebSocket forwarding.
o Access authentication.
o Content negotiation beyond "If-Modified-Since", "If-Unmodified-
Since", and single "Range" requests for "bytes" of static resources.
o Transaction logging.
o Etags
o Directory listings.
o The ~user notation in URLS.
RATIONALE FOR DUAL SERVERS
To aid security, Gonzalo deliberately only services insecure requests for
static resources. If you have static data that you do not want delivered
insecurely, you can give Gonzalo a different root directory from
Prospero. If you are paranoid, you can run Gonzalo on a different host.
If you do not want any resource delivered insecurely, you can only run
Prospero, or you can keep Gonzalo's root directory empty but for an index
page to redirect browsers to Prospero.
Secondary reasons for having two servers are that they make use of
hardware parallelism, and the performance loss associated with encrypted
connections only affects encrypted connections.
SYSTEM CONFIGURATION
By default, FreeBSD limits each process to a low number of maximum
simultaneously open descriptors. This places a limit on the number of
connections gonzalo 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=131072
kern.kq_calloutmax=131072
To increase performance, gonzalo attempts to set the accf_http accept
filter on the listening socket. For this to succeed, you must load the
module before starting gonzalo.
kldload accf_http
To load the module automatically at system boot-up, add the following
line to /boot/loader.conf.
accf_http_load="YES"
CROSS-ORIGIN REQUESTS
Gonzalo rejects HTTP/1.1 requests with "Host" header lines that do not
specify the host for which gonzalo is configured to serve content. This
prevents third parties from pointing their domains to your server.
Gonzalo rejects HTTP/1.1 requests without "Referer" or "Origin" header
lines that do not match gonzalo's hostname unless the requested
resources' filenames end in .html, .pdf, .epub, .bz, .bz2, .tgz, .txz, or
.gz. This prevents third parties from stealing your bandwidth by linking
to resources on your host other than web pages and archives.
Gonzalo rejects requests from secure origins when the hostname of the
request and the hostname of the origin are Gonzalo's hostname. Such
requests are security downgrades.
CONTENT TYPES
Files served by gonzalo reside in the directory specified by the -r
option. Files must be owned and readable by the user specified by the -u
option or be in and be readable by the group specified by the -g option.
Note that gonzalo will refuse to serve a file owned by another user and
group even if the file is world-readable.
Only the following filename suffix mappings are recognized:
html text/html; charset=utf-8
txt text/plain; charset=utf-8
css text/css
js application/x-javascript
woff font/woff
woff2 font/woff2
ttf font/opentype
otf font/opentype
appcache text/cache-manifest
png image/png
jpg image/jpeg
gif image/gif
ico image/vnd.microsoft.icon
svg image/svg+xml
bz application/x-bzip
bz2 application/x-bzip2
gz application/x-gzip
tgz application/x-compressed
txz application/x-compressed
zip application/zip
pdf application/pdf
epub application/epub+zip
rtf application/rtf
mp3 audio/mpeg
mpeg video/mpeg
odp application/vnd.oasis.opendocument.presentation
ods application/vnd.oasis.opendocument.spreadsheet
odt application/vnd.oasis.opendocument.text
doc application/msword
dot application/msword
docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
dotx application/vnd.openxmlformats-officedocument.wordprocessingml.template
docm application/vnd.ms-word.document.macroEnabled.12
dotm application/vnd.ms-word.template.macroEnabled.12
xls application/vnd.ms-excel
xlt application/vnd.ms-excel
xla application/vnd.ms-excel
xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
xltx application/vnd.openxmlformats-officedocument.spreadsheetml.template
xlsm application/vnd.ms-excel.sheet.macroEnabled.12
xltm application/vnd.ms-excel.template.macroEnabled.12
xlam application/vnd.ms-excel.addin.macroEnabled.12
xlsb application/vnd.ms-excel.sheet.binary.macroEnabled.12
ppt application/vnd.ms-powerpoint
pot application/vnd.ms-powerpoint
pps application/vnd.ms-powerpoint
ppa application/vnd.ms-powerpoint
pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
potx application/vnd.openxmlformats-officedocument.presentationml.template
ppsx application/vnd.openxmlformats-officedocument.presentationml.slideshow
ppam application/vnd.ms-powerpoint.addin.macroEnabled.12
pptm application/vnd.ms-powerpoint.presentation.macroEnabled.12
potm application/vnd.ms-powerpoint.template.macroEnabled.12
ppsm application/vnd.ms-powerpoint.slideshow.macroEnabled.12
GONZALO CONFIGURATION
To be able to restart on signals and bind to port 80, the gonzalo
executable is installed setuid root and executable by user and group. If
you do not run gonzalo in group www, you need to manually chgrp(1) the
executable into the appropriate group.
When waiting for a request, gonzalo drops connections after 10 seconds of
inactivity.
Gonzalo writes its pid into /var/run/gonzalo.pid if it can (ie., it is
started as root). You stop gonzalo 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 gonzalo on system boot. Replace the items
in brackets with values appropriate for your system. These are the
minimal set of options you should start with. The available options are
described in full at the end of this manual page.
gonzalo_enable="YES"
gonzalo_flags="-r <server-root> -u <user> -g <group>"
Start, stop, or restart gonzalo, or determine if it is running with the
following commands.
/usr/local/etc/rc.d/gonzalo start
/usr/local/etc/rc.d/gonzalo stop
/usr/local/etc/rc.d/gonzalo restart
/usr/local/etc/rc.d/gonzalo status
If you do not want gonzalo started on system start, set
gonzalo_enable="NO"
and use the following commands.
/usr/local/etc/rc.d/gonzalo forcestart
/usr/local/etc/rc.d/gonzalo forcestop
/usr/local/etc/rc.d/gonzalo forcerestart
/usr/local/etc/rc.d/gonzalo forcestatus
PERCENT ESCAPES
In the resource names of requests, gonzalo converts every sequence of
bytes consisting of a percent sign followed by two hexadecimal digits
into the byte specified by the hexadecimal value. Whitespace,
semicolons, and percent signs must all be percent-escaped to be
recognized in resource names.
COMPOUND REQUESTS WITH PIPELINED RESPONSES
Gonzalo recognizes compound requests as described the gonzalopipe.8
manual and delivers pipelined responses to those requests.
COMMAND-LINE OPTIONS
The following options are recognized.
-h The -h option sets the hostname for which gonzalo serves content. If
the option is not present on the command line, then the hostname is
taken from the system hostname. In requests, gonzalo recognizes this
hostname with or without the "www" subdomain. Do not include the
"www" subdomain in the hostname. In addition to the hostname,
gonzalo recognizes the IP addresses of listening interfaces.
If the system hostname cannot be determined, or the system hostname
is "localhost", then gonzalo uses the IPv4 loopback address as the
hostname: 127.0.0.1.
-r The -r option is mandatory and specifies the server root directory.
The root resource must be named "index.html". Requests for paths
that end in the directory separator are interpreted as requests for
"index.html" in the directories specified by those paths.
-m The -m option specifies the maximum number of simultaneous
connections that each gonzalo process services. If not set, gonzalo
maintains no more than 50000 simultaneous connections.
-p The -p option specifies the port to listen on. This defaults to 80.
-i The -i option limits gonzalo to accepting connections only from a
specified interface. Supply the IP address of the desired interface
as argument. By default, gonzalo accepts connections on all
interfaces capable of IPv4 or IPv6.
-q The -q option sets the number of incoming connections queued by the
operating system for the server. The queue defaults to 2048
connections. increasing this value may help the server cope with
high demand if the server is dropping connections.
-u
-g The -u and the -g options specify the user and group of gonzalo
server processes. If not specified, both values default to "nobody".
-x The -x option prevents gonzalo from becoming a daemon. Gonzalo 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,
gonzalo does not write its pid to /var/run/gonzalo.pid.
AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca
Thu Aug 16, 2018