TIPIDEE-QUICKSTART(7)

NAME
tipidee-quickstart - a tipidee quickstart guide

DESCRIPTION

  Preparation
Make sure you have s6[1] and s6-networking[2] installed alongside tipidee.

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.

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.

Compile a default configuration for tipidee: ‘:> /usr/pkg/etc/tipidee.conf && tipidee-config’. If you need more than the basic defaults, you can also write a real /usr/pkg/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 addresses.

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’, and your local IP address is ${ip}, the basic command line for an HTTP service is: ‘s6-envuidgid www s6-tcpserver -U ${ip} 80 s6-tcpserver-access tipideed’.

•   s6-envuidgid(8) puts the uid and gid of user ‘www’ into the environment, for s6-tcpserver(8) to drop root privileges to.

•   s6-tcpserver(8) 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(8) performs DNS requests to fill environment variables that tipidee needs. ( The main purpose of this program 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(8) is the tipidee daemon, and will handle HTTP requests until the client closes the connection or tipideed(8) 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 ${ip} 443 tipideed’.

•   s6-envuidgid(8) puts the uid and gid of user ‘www’ into the environment. env(1) adds the appropriate CERTFILE and KEYFILE variables to the environment, so TLS programs down the line can find the certificate and key.

•   s6-tlsserver(8) rewrites itself into a command line that does a lot of different things; the long-running process is still s6-tcpserver(8), listening and accepting client connections. For every client, it spawns a process that sets up the TLS transport layer and eventually exec(3) s into tipideed(8).

•   tipideed(8) always speaks plaintext HTTP, it has no knowledge of cryptography itself, but it is aware ( via an environment variable) 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.

SEE ALSO
env(1), exec(3), s6-envuidgid(8), s6-tcpserver(8), s6-tcpserver-access(8), s6-tlsserver(8), tipideed(8)

[1] https://skarnet.org/software/s6/

[2] https://skarnet.org/software/s6-networking/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/tipidee/quickstart.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)