prospero(1) FreeBSD General Commands Manual prospero(1) NAME Prospero – Minimal Event-Driven HTTPS/1.1 Server SYNOPSIS prospero -r ⟨server-root⟩ -f ⟨config-file⟩ [-s -t ⟨type-file⟩ -b ⟨buffer-size⟩ -c ⟨cache-timeout⟩ -i ⟨interface⟩ -q ⟨queue-size⟩ -m ⟨max-conns⟩ -o ⟨idle-timeout⟩ -u ⟨user⟩ -g ⟨group⟩] DESCRIPTION Prospero is a minimal, secure, event-driven web server for small websites. PROSPERO SUPPORTS: • IPv4 and IPv6 connections. • TLS 1.3 encrypted connections. • Enough of HTTP/1.1 to be functional with all browsers. • WebSocket forwarding for up to 5 local or remote WebSocket servers. • SCGI forwarding for up to 5 local or remote SCGI application servers. PROSPERO DOES NOT SUPPORT: • Connections to any port but 80 or 443. • Insecure requests. • OCSP stapling. That ship has sailed. Only Firefox still validates. • Graceful stops. The server exits soon after receiving SIGTERM. • Name-based virtual hosting. • HTTP/2 or HTTP/3. These complex protocols provide little benefit for small websites. • Plain CGI. • Access authentication. • Content negotiation beyond "If-Modified-Since", "If-Unmodified- Since", and single "Range" requests for "bytes" of static resources. • Transaction logging. • Etags • Directory listings. • The ~user notation in URLS. INSECURE CONNECTIONS Prospero redirects the first request (without reading it) on a connection to port 80 to port 443 via a "301 Permanently moved" response with a location header of the form: https://. Prospero then closes the connection. This is technically incorrect behavior because it redirects all insecure requests into secure requests for the root resource, but this will redirect browsers connecting for the first time. 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. Prospero uses two descriptors for every connection it services. kern.maxfiles=262144 kern.maxfilesperproc=131072 CACHE-CONTROL By default, prospero adds a Cache-Control: max-age=600; must-revalidate header to every response. Browsers and caches must validate the freshness of a cached response after ten minutes. This header is overridden by Cache-Control headers provided by SCGI servers. You can alter the default value of 600 seconds with the -c option. You can specify more precise cache behavior with Service Workers. CROSS-ORIGIN REQUESTS Prospero rejects HTTP/1.1 requests for files without "Referer" or "Origin" header lines that do not match Prospero's hostname unless the requested resources' filenames end in: html webmanifest txt pdf epub bz bz2 tgz txz gz Prospero will service requests for .png files without "Referer" or "Origin" headers for the following filenames only: android-chrome-192x192.png android-chrome-512x512.png apple-touch-icon.png favicon-16x16.png favicon-32x32.png Requests for files whose filenames do not have a suffix separated from the rest of the filename by a dot '.' are only successful if the requests have Referer or Origin headers and the requests are not cross-origin requests. Responses containing such files will be identified as text files with Content-Type: text/plain; charset=utf-8. By default, cross-origin checking is not performed for SCGI application servers or WebSocket servers. To turn on cross-origin checking for SCGI requests, include the -s option on the command line. To turn on cross- origin checking for WebSocket servers, include -w on the command line. 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 by the group specified by the -g option. Note that Prospero will refuse to serve a file owned by another user or group even if the file is world-readable. Prospero will refuse to serve a file marked executable. The filename-suffix-to-type mappings are described in /usr/local/share/prospero/content-types.txt You can edit the mappings file to add or modify mappings. Each filename suffix must appear by itself on a line. The type to which the suffix maps must follow on the next line. Blank lines are ignored. You must restart the server for your modifications to take effect. If you move the file to another location, or if you rename the file, you must inform the server of the fully-qualified filename with the -t option. PROSPERO CONFIGURATION If you do not want to run prospero as user www in group www, you need to manually chown(8) the executable appropriately. Prospero writes its pid into /var/run/prospero.pid. 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. If the server exits prematurely, it writes an error message to /var/log/messages before exiting. prospero_enable="YES" prospero_flags="-r -f -u -g " Start, stop, or restart prospero, or determine if it is running with the following commands. service prospero start service prospero stop service prospero restart service prospero status If you do not want prospero started on system start, set prospero_enable="NO" and use the following commands. service prospero onestart service prospero onestop service prospero onerestart service prospero onestatus 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 and percent signs must all be percent-escaped to be recognized in resource names. TLS CONFIGURATION 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. 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 10 lines are optional, and if present, define up to 5 SCGI application servers and 5 WebSocket servers to which Prospero will forward requests. The 5th, 7th, 9th, 11th, and 13th lines define WebSocket servers. The 6th, 8th, 10th, 12th, and 14th 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 WebSocket servers but no SCGI application servers, leave the SCGI server lines between the WebSocket lines blank. Blank lines at the end of the configuration file are unnecessary. There is no need to include blank lines after the last non- blank server line. 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 :. 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/, /websocket3/, /websocket4/, or /websocket5/. 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. Requests beginning with /websocket4/ are forwarded to the server defined on line 11. Requests beginning with /websocket5/ are forwarded to the server defined on line 13. 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 :. 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/, /scgi3/, /scgi4/, or /scgi5/. 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. Requests beginning with /scgi4/ are forwarded to the server defined on line 12. Requests beginning with /scgi5/ are forwarded to the server defined on line 14. 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 LOCAL_ADDR SEC_GPC The LOCAL_ADDR variable contains the textual representation of the address of the interface on which the client is connected to prospero. This variable is only set if the -s option is not present on the command line. The variable's value can be used by SCGI servers that need to perform their own cross-origin checks to verify HTTP_ORIGIN or HTTP_REFERRER values that contain IP addresses instead of hostnames. Note that IP4 addresses will be in compact IP6-mapped form. That is to say that the addresses will begin with the sequence '::ffff:'. 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. -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 with the directory separator are interpreted as requests for "index.html" in the directories specified by those paths. Requests for directories that are not terminated with the directory separator are interpreted as requests for files and fail. To prevent clients from learning about the file system, prospero pretends not to "see" file system entities in the following situations. In each of these situations, prospero returns a 404 Not Found response. • On receipt of a request for an existing non-regular file. • On receipt of a request for an existing executable file. • On receipt of a request for an existing regular file to which the server does not have read permission. • On receipt of a request for an existing regular file that is not owned the user defined by the -u option or is not in the group defined by the -g option regardless of the file's permissions. -b The -b option specifies the size of the internal buffers used by Prospero to transfer data to and from clients. The default value is 512 bytes. This value is the server's multiplexing quantum. The server will attempt to read or write no more than this quantity of bytes of data at one time. This value must be a multiple of 2 greater than 511. Note that this value must be large enough to accommodate clients' full requests. If you have an SCGI server that uses large cookies, you must specify a buffer size large enough to hold an entire client request header containing those large cookies and an entire server response header containing those cookies plus a byte for a zero- terminator. If a request header is too big, prospero considers the client to be hostile and drops the connection without explanation. If prospero generates a response header that is too big, the server logs an error message and drops the connection. -c The -c option is used to change the value of the cache timeout returned to clients in Cache-Control headers. This value defaults to 600 seconds for a timeout of 10 minutes. -f The -f option is mandatory and specifies the TLS configuration file. -s The -s option turns on cross-origin checking for SCGI servers. If you want your servers to be accessible only by referral from links on your site, add -s to your options. Otherwise, cross-origin requests for SCGI server URLs are not rejected. If you want to have a mix of both behaviors, your applications servers must perform their own cross-origin checking. -w The -w option turns on cross-origin checking for WebSocket servers. -t The -t option is only necessary if you move or rename the content- types.txt file. Use -t to specify the fully-qualified filename. -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. -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. -o The -o option sets the idle connection timeout value. This value is the number of seconds after which idle connections are closed. An idle connection is one on which no data has been transferred to or from the client for the timeout value of seconds. The default timeout value is 30 seconds. Prospero does not timeout WebSocket connections. WebSocket servers are responsible for timing-out their connections. -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 that the server switches to after establishing the listening sockets. If not specified, both values default to "nobody". AUTHORS James Bailie ⟨jimmy@mammothcheese.ca⟩ http://www.mammothcheese.ca Tue Sept 10, 2023