trinculo(8)             FreeBSD System Manager's Manual            trinculo(8)

     Trinculo - Minimal Threaded HTTPS/1.1 Server

     trinculo [see the libserver manual for options]

     Trinculo is a minimal, secure, multithreaded web server.  Trinculo serves
     files and performs SCGI and WebSocket forwarding for a single hostname.

     o   IPv4 and IPv6 clients.

     o   TLS encrypted connections ONLY, with:

         o   TLS >= 1.0

         o   Session resumption.

         o   Perfect forward secrecy.

         o   OCSP stapling.

     o   HEAD, GET, and POST request methods.

     o   HTTP/1.1 persistent connections.

     o   The caliban(8) extension.

     o   Forwarding to SCGI servers.

     o   Forwarding to WebSocket servers.

     o   Unencrypted connections.

     o   HTTP/2.

     o   Virtual hosting.

     o   Plain CGI.

     o   Access authentication.

     o   Content negotiation headers beyond "If-Modified-Since", and "If-

     o   Etags

     o   Directory listings.

     o   The ~user notation in URLS.

     o   Transaction logging.

     A rc.d script is installed in /usr/local/etc/rc.d/.  Add the following
     lines to /etc/rc.conf to start trinculo on system start.  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 the libserver manual.

     trinculo_flags="-q <backlog> -p <port-number> -f <config-file> -r <server-root> -u <user> -g <group> -n <min-threads> -m <max-threads>"

     Ensure that the value that you set for the -m option is equal to or less
     than the value of kern.threads.max_threads_per_proc.  You can set the
     value of this variable in in /etc/sysctl.conf.

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

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

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


     and use the following commands.

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

     Trinculo adds the following 3 headers to every response it generates.
     These can only be altered by modifying the source code and recompiling.

     Strict-Transport-Security: max-age=31536000
     X-XSS-Protection: 1; mode=block
     X-Frame-Options: SAMEORIGIN

     In the resource names of requests, trinculo 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.

     Trinculo recognizes compound requests as described in the caliban(8)
     manual and delivers pipelined responses to those requests.

     By default, FreeBSD limits each process to a low number of maximum
     simultaneously open descriptors.  This places a limit on the number of
     simultaneous connections stephano may service.  The sysctl settings that
     follow must be set to appropriate values for your system.  Set these
     values at the command-line with the "sysctl" utility.  Place these
     settings in /etc/sysctl.conf to set them on system start.


     Trinculo rejects HTTP/1.1 requests with "Host" header lines that do not
     specify the host for which Trinculo is configured to serve content.  This
     prevents third parties from pointing their domains to your server.

     Trinculo rejects HTTP/1.1 requests for files without "Referer" or
     "Origin" header lines that match Trinculo's hostname unless the requested
     resources are files and their filenames end in .html, .pdf, .tgz, .txz,
     or to resources on your host other than documents and archives.  SCGI
     servers must perform their own cross-origin checks.  It can be useful for
     SCGI servers to service links from other origins or from email.

     Trinculo services requests from insecure origins when the hostname of the
     request and the hostname of the origin are Trinculo's hostname.  Such
     requests are security upgrades.

     To restart on signals and bind to port 443, the trinculo executable is
     installed setuid root and executable by user and group.  If you do not
     run trinculo in group www, chgrp(1) the executable into the group you
     specify with the -g option.

     Trinculo is built on top of libserver and accepts the command line
     options that libserver accepts.  Consult the libserver manual for

     Files served by trinculo 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 trinculo will refuse to serve a file owned by another user and
     group even if the file is world-readable.

     The root resource must be named "index.html".  Requests for directories
     are interpreted as requests for "index.html" inside the directories.  To
     be recognized as a request for a directory, a request must end with a
     directory separator: '/'.

     When waiting for a request, trinculo drops connections after 10 seconds
     of inactivity.

     The following filename suffix to type 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/
     svg      image/svg+xml

     gz       application/x-gzip
     tgz      application/x-compressed
     txz      application/x-compressed
     zip      application/zip
     pdf      application/pdf
     mp3      audio/mpeg

     doc      application/msword
     dot      application/msword
     docx     application/vnd.openxmlformats-officedocument.wordprocessingml.document
     dotx     application/vnd.openxmlformats-officedocument.wordprocessingml.template
     docm     application/
     dotm     application/

     xls      application/
     xlt      application/
     xla      application/
     xlsx     application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
     xltx     application/vnd.openxmlformats-officedocument.spreadsheetml.template
     xlsm     application/
     xltm     application/
     xlam     application/
     xlsb     application/

     ppt      application/
     pot      application/
     pps      application/
     ppa      application/
     pptx     application/vnd.openxmlformats-officedocument.presentationml.presentation
     potx     application/vnd.openxmlformats-officedocument.presentationml.template
     ppsx     application/vnd.openxmlformats-officedocument.presentationml.slideshow
     ppam     application/
     pptm     application/
     potm     application/
     ppsm     application/

     Configuration is specified with a configuation file.  The -f command line
     option must be set to the filename of the configuration file.  The file
     must contain 7 newline-terminated lines of text.  The lines describe, in

     1.   The hostname the server will recognize in request Host headers and
          SNI.  Trinculo will recognize the hostname preceded with the "www"
          subdomain.  Do not include the "www" subdomain in your hostname.
          Leave this line blank to make trinculo take the hostname from the
          system hostname.  Trinculo will also recognize the IP address of a
          connection's interface as a valid hostname.

     2.   The absolute path to the file containing the server's TLS key.

     3.   The TLS key password.  This line can be blank if there is no

     4.   The absolute path to the file containing the TLS certificate chain.

     5.   The absolute path to the file that will hold the response from the
          OCSP server.  If you do not want to enable OCSP stapling, insert an
          empty line.  If you want to enable OCSP stapling, read and install
          trinculo_ocsp from the source distribution.  Then insert the value
          of ${OCSP} from that file.

     6.   The absolute path of the WebSocket configuration file.  This line
          may be empty if no WebSocket service is available.

          Each line of the WebSocket configuration file contains a virtual
          path, one or more tab characters, a hostname, one or more tab
          characters, and a port.  WebSocket handshakes that request entities
          whose names begin with the virtual path are forwarded to the host
          listening on the port.

          For a localhost server, the hostname must be a single dot '.'
          character and the port must be an absolute path to a UNIX-domain

          For a TCP server, the hostname must be the hostname or IP address of
          the remote host, and the port must be the port number to connect to.

          o   Trinculo performs the WebSocket handshake and then connects to
              the WebSocket server.

          o   Trinculo sends to the server the content of the Cookie header
              supplied with the request, terminated with a newline only, and
              then proxies data back and forth between the server and the
              client.  If no Cookie was supplied by the client, the cookie
              line will consist only of the newline character.

          o   The WebSocket server is responsible for framing and unframing

          o   Trinculo ignores Sec-WebSocket-Protocol headers.  Clients must
              NOT specify a sub-protocol, or handshakes may not complete
              successfully with all browsers.

     7.   The absolute path of the SCGI server configuration file.  This line
          may be empty if there are no SCGI servers available.

          Each line of the SCGI configuration file contains a virtual path,
          one or more tab characters, a hostname, one or more tab characters,
          and a port.  Requests for entities whose name begins with the
          virtual path are forwarded to the host listening on the port.

          For a localhost server, the hostname must be a single dot '.'
          character and the port must be an absolute path to a UNIX-domain

          For a TCP server, the hostname must be the hostname or IP address of
          the remote host, and the port must be the port number to connect to.

     The following environment variables are set for the SCGI server.


     The server need only supply a Content-Type or a Location header.  If
     present, other headers are passed to the client unmodified.

     o   DO NOT send a Status header.  Trinculo crafts its own Status headers.

         o   If the SCGI server supplies a Location header, the client will
             receive a 303 See Other response.

         o   If the SCGI server does not supply a Location header, the client
             will receive a 200 OK response.

         o   If the server drops the connection, the client will receive a 500
             Internal Error response.

     o   Do not add a Date header to responses.  Trinculo always adds a date
         header to all responses.

     o   There is no limit imposed on the length of SCGI response header
         lines.  You can set big cookies, but be advised that client request
         header lines cannot be longer than 8192 bytes.

     James Bailie <>

                               Tue, Aug 22, 2017