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

NAME
     Stephano - Minimal Threaded HTTP/1.1 Server

SYNOPSIS
     stephano [see the libserver manual for options]

DESCRIPTION
     Stephano is a minimal, insecure, multithreaded web server.  Stephano
     serves files for a single hostname.

   STEPHANO SUPPORTS:
     o   IPv4 and IPv6 clients.

     o   HTTP/1.1 persistent connections.

     o   The caliban(8) extension.

   STEPHANO DOES NOT SUPPORT:
     o   TLS.  Trinculo(8) provides TLS.

     o   HTTP/2.

     o   Virtual hosting.

     o   Dynamic resources.  Trinculo(8) provides SCGI and WebSockets.

     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   Logging beyond syslogging errors.

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

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

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

     stephano_enable="YES"
     stephano_flags="-q <backlog> -p <port-number> -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 stephano, or determine if it is running with the
     following commands.

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

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

     stephano_enable="NO"

     and use the following commands.

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

   PERCENT ESCAPES
     In the resource names of requests, stephano 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
     Stephano 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.kern.max_threads_per_proc=65526

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

     Stephano rejects cross-origin HTTP/1.1 requests for all resources except
     for those whose filename ends in .html, .pdf, .tgz, .txz, or .gz.

   CONTENT TYPES
     Files served by stephano 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 stephano 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: '/'.

     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

     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

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

                               Thu, Aug 17, 2017