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

NAME
     Trinculo - Minimal Threaded HTTPS/1.1 Server

SYNOPSIS
     trinculo [see the libserver manual for options]

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

   TRINCULO SUPPORTS:
     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.

   TRINCULO DOES NOT SUPPORT:
     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-
         Unmodified-Since".

     o   Etags

     o   Directory listings.

     o   The ~user notation in URLS.

     o   Transaction logging.

   START AND STOP TRINCULO
     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_enable="YES"
     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

     trinculo_enable="NO"

     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

   SECURITY HEADERS
     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

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

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

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

     kern.maxfiles=262144
     kern.maxfilesperproc=131072
     kern.threads.max_threads_per_proc=65526

   CROSS-ORIGIN REQUESTS
     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.

   TRINCULO CONFIGURATION
     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
     details.

     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/vnd.microsoft.icon
     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/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

     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
     order:

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

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

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

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

          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.

     CONTENT_TYPE
     CONTENT_LENGTH
     REQUEST_METHOD
     SCRIPT_NAME
     QUERY_STRING
     HTTP_COOKIE
     HTTP_REFERRER
     HTTP_ORIGIN
     REMOTE_ADDR

     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.

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

                               Tue, Aug 22, 2017