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 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 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 Fri Feb 02, 2018