gonzalo(1)              FreeBSD General Commands Manual             gonzalo(1)

     Gonzalo - Minimal Event-Driven HTTP/1.1 Server

     gonzalo -r <server-root> [-h <hostname> -i <interface> -p <port> -q <queue-size> -m <max-conns> -u <user> -g <group>]

     Gonzalo is a minimal, insecure, event-driven web server.  Gonzalo serves
     files for a single hostname.  Gonzalo is Prospero's helper.

     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.

     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.

     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.


     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.


     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:


     Gonzalo will only service requests for .png files without "Referer" or
     "Origin" headers for the following filenames:


     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.

     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

     webmanifest application/manifest+json

     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

     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

     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

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


     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

     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.

     Gonzalo recognizes compound requests as described the gonzalopipe.8
     manual and delivers pipelined responses to those requests.

     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

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


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

     James Bailie <jimmy@mammothcheese.ca>

                                Thu Aug 8, 2019