tipidee
Software
skarnet.org

A tipidee quickstart guide

Preparation

1. Make sure you have s6 and s6-networking installed alongside tipidee.
2. Prepare your document root for every virtual domain you aim to serve. For instance, if your documents are in /home/www/docs and you need to serve the example.com and example.org domains, create /home/www/docs/example.com and /home/www/docs/example.org directories, they will be the document roots for the example.com and example.org virtual sites respectively.
3. Symlink these canonical directories to all the host:port combinations you want them to be available on. If you want example.com and example.org to be both available on ports 80 and 443, then symlink example.com to example.com:80 and example.com:443 in the /home/www/docs directory, and do the same with example.org.
4. Compile a default configuration for tipidee: :> /etc/tipidee.conf && tipidee-config.
   • If you need more than the basic defaults, you can also write a real /etc/tipidee.conf config file before running tipidee-config.

Running the server

• You need one long-running process per port you want tipidee to serve. If you want to serve HTTP on port 80 and HTTPS on port 443, then you'll need two services. Or four if you want to serve on both IPv4 and IPv6 adresses.
• Start these processes in the /home/www directory, the base for all the domains you're serving.
• Assuming you want to run the server as user www, the basic command line for an HTTP service is: s6-envuidgid www s6-tcpserver -U example.com 80 s6-tcpserver-access -v0 -- tipideed.
  • s6-envuidgid puts the uid and gid of user www into the environment, for s6-tcpserver to drop root privileges to.
  • s6-tcpserver binds to the address and port given, drops privileges, and listens; it accepts connections and spawns a new process for each one.
  • s6-tcpserver-access performs DNS requests to fill environment variables that tipidee needs. Its main purpose is to perform access control, but we're not using it for that here: chances are your web server is public access and doesn't need to be IP-restricted.
  • tipideed is the tipidee daemon, and will handle HTTP requests until the client closes the connection or tipideed itself needs to close it.
• HTTPS requires a bit of additional setup for TLS. If your certificate is in /etc/ssl/acme/example.com/cert.pem and the corresponding private key is in /etc/ssl/acme/private/example.com/key.pem, the basic command line for your HTTPS service could look like: s6-envuidgid www env CERTFILE=/etc/ssl/acme/example.com/cert.pem KEYFILE=/etc/ssl/acme/private/example.com/key.pem s6-tlsserver -U -e example.com 443 tipideed.
  • s6-envuidgid puts the uid and gid of user www into the environment.
  • env adds the appropriate CERTFILE and KEYFILE variables to the environment, so TLS programs down the line can find the certificate and key.
  • s6-tlsserver rewrites itself into a command line that does a lot of different things; the long-running process is still s6-tcpserver listening. For every client connection, it spawns a process that sets up the TLS transport layer and eventually execs into tipideed.
  • tipideed always speaks plaintext HTTP, it has no knowledge of cryptography itself, but it is made aware that it's running under TLS, and CGI scripts it runs will have the HTTPS=on marker.
• These command lines will block (remain in the foreground) and log everything to their stderr. For more server-like functionality, you should integrate them to your service manager scripts.

tipidee service templates

The tipidee source distribution comes with an examples/ subdirectory containing service files to run tipidee under various service managers.

I want my web server to listen to more than one address. Do I need to do all that for every address I have?

Not necessarily: you could listen to 0.0.0.0 for IPv4, and :: for IPv6. But if you don't want your server to listen to all the addresses on your machine, then yes, you will have to run one process per address:port tuple.

It's okay though: every listening process is very small. The skarnet.org server has two network cards and runs a web server on both of them, on IPv4 and IPv6, over HTTP and HTTPS, which makes 8 services. Plus one s6-log logger process for each of these services. Plus a supervisor for every service and every logger — for a whooping total of 64 long-running processes just for its web server functionality; and it's still not even noticeable, the amount of resources it consumes is negligible. So, don't worry about it.

Note that this allows you to run different instances of tipideed with different configurations, if you need it. Use the -f option to specify a different config file for tipideed.