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

NAME
     Prospero - Minimal Event-Driven HTTPS/1.1 Server

SYNOPSIS
     prospero -r <server-root> -f <config-file> [-i <interface> -p <port> -q <queue-size> -m <max-conns> -o <ocsp-file> -u <user> -g <group>]

DESCRIPTION
     Prospero is a minimal, secure, event-driven web server.  Prospero serves
     files and performs WebSocket and SCGI forwarding for a single hostname.

   PROSPERO SUPPORTS:
     o   IPv4 and IPv6 connections.

     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   A custom pipelining extension described in caliban.8

     o   Graceful stops.

     o   WebSocket forwarding for up to 3 local or remote WebSocket servers.

     o   SCGI forwarding for up to 3 local or remote SCGI application servers.

   PROSPERO DOES NOT SUPPORT:
     o   Name-based virtual hosting.

     o   HTTP/2.

     o   CGI.

     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.

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

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

     Prospero rejects HTTP/1.1 requests for files or the WebSocket resource
     without "Referer" or "Origin" header lines that do not match Prospero's
     hostname unless the requested resources are files and their 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 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.

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

   CONTENT TYPES
     Files served by prospero 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 Prospero 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

   PROSPERO CONFIGURATION
     To be able to restart on signals and bind to port 443, the prospero
     executable is installed setuid root and executable by user and group.  If
     you do not run prospero in group www, you need to manually chgrp(1) the
     executable into the appropriate group.

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

     Prospero writes its pid into /var/run/prospero.pid if it can (ie., it is
     started as root).  You stop prospero 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 prospero 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.

     prospero_enable="YES"
     prospero_flags="-r <server-root> -f <config-file> -u <user> -g <group>"

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

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

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

     prospero_enable="NO"

     and use the following commands.

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

   PERCENT ESCAPES
     In the resource names of requests, prospero 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
     Prospero recognizes compound requests as described the caliban.8 manual
     and delivers pipelined responses to those requests.

   TLS CONFIGURATION
     To enable OCSP stapling, follow the instructions in prospero_ocsp in the
     source distribution.

     The remainder of the TLS configuration is described in a text file.  The
     -f command line option must be set to the filename of the configuration
     file.  The file must contain from 4 to 10 newline-terminated lines of
     text.  The first 4 lines describe, in order:

     1.   The hostname for which Prospero serves content.  This line may be
          blank to cause the server to take the hostname from the system
          hostname.  In requests, prospero recognizes the hostname with or
          without the "www" subdomain.  Do not include the "www" subdomain in
          the hostname.  In addition to the hostname, prospero recognizes the
          IP addresses of listening interfaces.

     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.

     The next 6 lines are optional, and if present, define up to 3 SCGI
     application servers and 3 WebSocket servers to which Prospero will
     forward requests.  The 5th, 7th, and 9th lines define WebSocket servers.
     The 6th, 8th, and 10th lines define SCGI application servers.

     Any of these lines can be blank to indicate that no server is defined.
     For example, if you want to define 3 WebSocket servers but no SCGI
     application servers, define the WebSocket servers on lines 5, 7, and 9,
     and leave lines 6, 8, and 10 blank.  Blank lines at the end of the
     configuration file are unnecessary, so line 10 can be ommitted.

     Note that local servers can listen on the loopback address, but this
     degrades performance by unnecessarily interposing the TCP/IP stack
     between Prospero and the servers.

   WEBSOCKET SERVERS
     The lines defining Websocket servers consist of the absolute path to a
     UNIX socket for a local WebSocket Server or a remote server specification
     of the form <hostname or IP addr>:<port>.

     Note that connections to a remote server are not encrypted.  Connect only
     to hosts on your LAN.

     To be recognized as a WebSocket upgrade, a request must begin with 1 of
     the following paths: /websocket/, /websocket2/, or /websocket3/.
     Requests beginning with /websocket/ are forwarded to the server defined
     on line 5.  Requests beginning with /websocket2/ are forwarded to the
     server defined on line 7.  Requests beginning with /websocket3/ are
     forwarded to the server defined on line 9.

     When a client initiates a WebSocket upgrade, prospero performs the
     WebSocket handshake and then connects to the WebSocket server.  Propero
     ignores Sec-WebSocket-Protocol headers.  Clients must NOT specify a
     protocol, or handshakes may not complete successfully with all browsers.

     Prospero then sends to the WebSocket server the content of the Cookie
     header line submitted with the upgrade request.  The cookie is terminated
     with a single newline.  The cookie line is empty if the client did not
     submit a Cookie header.

     From then on, prospero transfers data back and forth between the
     WebSocket server and the client.  The client and WebSocket server are
     responsible for framing and unframing data.

   SCGI APPLICATION SERVERS
     The lines defining SCGI applications servers consist of the absolute path
     to a UNIX socket for a local SCGI application server or a remote server
     specification of the form <hostname or IP addr>:<port>.

     Note that connections to remote servers are not encrypted.  Connect only
     to hosts on your LAN.

     To be recognized as a SCGI request, a request must begin with 1 of the
     following paths: /scgi/, /scgi2/, or /scgi3/.  Requests beginning with
     /scgi/ are forwarded to the server defined on line 6.  Requests beginning
     with /scgi2/ are forwarded to the server defined on line 8.  Requests
     beginning with /scgi3/ are forwarded to the server defined on line 10.

     The following environment variables are set for the SCGI server:

     CONTENT_TYPE
     CONTENT_LENGTH
     REQUEST_METHOD
     QUERY_STRING
     SCRIPT_NAME
     HTTP_REFERRER
     HTTP_ORIGIN
     HTTP_COOKIE
     REMOTE_ADDR

     Prospero does not pass on every response header line generated by the
     SCGI application.  Prospero plucks out the content of the:

     Content-Type
     Content-Length
     Content-Disposition
     Cache-Control
     Location
     Set-Cookie x 5

     header lines and formats its own response header.  Only the "Content-
     Type" header line is necessary.  If it is missing, Prospero inserts
     "Content-Type: text/plain; charset=utf-8" into the response header.

     Responses from the SCGI server that contain a "Location" header line are
     formatted into "303 see other" responses.  Those responses must not
     contain bodies.  All other SCGI server responses are formatted into "200
     OK" responses and must contain bodies.  This means that error messages
     must be delivered to the client as HTML.

   COMMAND-LINE OPTIONS
     The following options are recognized.

     -f  The -f option is mandatory and specifies the TLS configuration file.

     -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 prospero services.  If not set, prospero maintains
         no more than 50000 simultaneous connections.

     -o  The -o option specifies the absolute filename of the file containing
         the OCSP server's response.  See the prospero_ocsp script for
         instructions on how to set up OCSP stapling.

     -p  The -p option specifies the port to listen on.  This defaults to 443.

     -i  The -i option limits prospero to accepting connections only from a
         specified interface.  Supply the IP address of the desired interface
         as argument.  By default, prospero 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 prospero
         server processes.  If not specified, both values default to "nobody".

     -x  The -x option prevents prospero from becoming a daemon.  Prospero
         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, prospero does not write its pid to /var/run/prospero.pid.

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

                               Thu Aug 16, 2018