diff options
author | Laurent Bercot <ska-skaware@skarnet.org> | 2023-08-23 15:36:55 +0000 |
---|---|---|
committer | Laurent Bercot <ska@appnovation.com> | 2023-08-23 15:36:55 +0000 |
commit | e6ada0b74352f77124a682d98c6d842fd5c44b45 (patch) | |
tree | 77e406393684f15dfa4aa8e41f16ec3d27e90286 | |
parent | 8d8edcd55e8601b888bf310c813d26fc328c9eaf (diff) | |
download | tipidee-e6ada0b74352f77124a682d98c6d842fd5c44b45.tar.xz |
Add some doc
Signed-off-by: Laurent Bercot <ska@appnovation.com>
39 files changed, 297 insertions, 7 deletions
diff --git a/doc/index.html b/doc/index.html index 9f3bc2f..6cb995d 100644 --- a/doc/index.html +++ b/doc/index.html @@ -20,18 +20,34 @@ <h2> What is it ? </h2> <p> - tipidee is a web server. It supports HTTP/1.1. It aims to be compliant + tipidee is a web server. It supports HTTP 1.0 and 1.1. It aims to be compliant with <a href="https://datatracker.ietf.org/doc/html/rfc9112">RFC 9112</a>: while it only implements a very limited subset of the optional functionality -in HTTP/1.1, it implements all the mandatory parts. +in HTTP 1.1, it implements all the mandatory parts. It is usable with both +HTTP and HTTPS. +</p> + +<p> + It runs under a super-server, e.g. inetd, +<a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a>, or +<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a> +(for HTTPS). Traditionally, inetd-mode web servers aren't considered performant, +but tipidee aims to eke out every single drop of performance that is attainable from +its programming model. </p> <hr /> +<ul> + <li> For the impatient: a <a href="quickstart.html">quickstart guide</a>. </li> +</ul> + +<hr /> + <h2> Why another Web server? </h2> <p> - There are two groups of web servers. + There are roughly two groups of web servers. </p> <p> @@ -46,14 +62,41 @@ for instance, was developed as a proof of concept for solving the </p> <p> - The second one is + The second one is small, quick-and-dirty servers, aimed at easily deploying +basic HTTP service for serving static files for prototying or in resource +constrained environments such as embedded devices. Among them, for instance, +<a href="https://busybox.net/">busybox httpd</a>, +<a href="http://www.eterna.com.au/bozohttpd/">bozohttpd</a>, or various +httpds from <a href="https://acme.com/software/">ACME Labs</a>. +</p> + +<p> + And, surprisingly, not much in between. There are a ton of supposedly +"tiny" or "minimal" servers, written in languages whose naked runtime uses +more resources than <a href="//skarnet.org/software/">the whole skarnet.org +ecosystem</a> by two orders of magnitude; but there isn't one that focused +on what I want from a web server, which is: +</p> + +<ul> + <li> Usability with HTTPS without the need to entangle the code with a +given TLS library (which means delegating the TLS layer to a super-server +and not performing the socket work itself) </li> + <li> Support for HTTP 1.1, not only 1.0 </li> + <li> Support for real CGI, not only NPH </li> +</ul> + +<p> + All in all, I felt that despite how crowded the web server space is, +there wasn't a satisfactory offer for the needs of skarnet.org and a +few similar sites. </p> <h3> And why "tipidee"? </h3> <p> - Because <em>h-t-t-p-d</em> is pretty tedious to say out loud, and only -keeping the last syllables makes it easier. + Because <em>h-t-t-p-d</em> is pretty tedious to say out loud. +kKeeping the last three syllables makes it easier. </p> <h2> Installation </h2> @@ -72,7 +115,10 @@ library. </li> on a super-server to listen to the network and provide connection information via environment variables. It also defers to tools such as <a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a> -to provide access control and connection fine-tuning. </li> +to provide access control and connection fine-tuning. And if you want +to run an HTTPS server, you'll need something like +<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a> +to manage the TLS transport layer. </li> </ul> <h3> Licensing </h3> @@ -126,6 +172,12 @@ the previous versions of tipidee and the current one. </li> <li><a href="tipidee-config-preprocess.html">The <tt>tipidee-config-preprocess</tt> internal program</a></li> </ul> +<h3> Configuration format </h3> + +<ul> +<li><a href="tipidee.conf.html">The <tt>/etc/tipidee.conf</tt> file format</a></li> +</ul> + <h2> Related resources </h2> <ul> diff --git a/doc/quickstart.html b/doc/quickstart.html new file mode 100644 index 0000000..4b369eb --- /dev/null +++ b/doc/quickstart.html @@ -0,0 +1,107 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>tipidee: quickstart guide</title> + <meta name="Description" content="tipidee: quickstart" /> + <meta name="Keywords" content="tipidee quickstart guide" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">tipidee</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> A tipidee quickstart guide </h1> + +<h3> Preparation </h3> + +<ol> + <li> Make sure you have <a href="//skarnet.org/software/s6/">s6</a> and + <a href="//skarnet.org/software/s6-networking/">s6-networking</a> installed +alongside tipidee. </li> + <li> Prepare your document root for every virtual domain you aim to serve. +For instance, if your documents are in <tt>/home/www</tt> and you need to +serve the <tt>example.com</tt> and <tt>example.org</tt> domains, create +<tt>/home/www/example.com</tt> and <tt>/home/www/example.org</tt> directories, +they will be the document roots for the <tt>example.com</tt> and <tt>example.org</tt> +virtual sites respectively. </li> + <li> Symlink these canonical directories to all the <em>host:port</em> combinations +you want them to be available on. If you want <tt>example.com</tt> and +<tt>example.org</tt> to be both available on ports 80 and 443, then symlink +<tt>example.com</tt> to <tt>example.com:80</tt> and <tt>example.com:443</tt> +in the <tt>/home/www</tt> directory, and do the same with <tt>example.org</tt>. </li> + <li> Compile a default configuration for tipidee: +<tt>:> /etc/tipidee.conf && tipidee-config</tt>. + <ul> + <li> If you need more than the basic defaults, you can also write a real +<a href="tipidee.conf.html">/etc/tipidee.conf</a> config file before running +<a href="tipidee-config.html">tipidee-config</a>. </li> + </ul> </li> +</ol> + +<h3> Running the server </h3> + +<ul> + <li> 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. </li> + <li> Start these processes in the <tt>/home/www</tt> directory, the base +for all the domains you're serving. </li> + <li> Assuming you want to run the server as user <tt>www</tt>, +the basic command line for an HTTP service is: +<tt>s6-envuidgid www s6-tcpserver -U example.com 80 s6-tcpserver-access -v0 -- tipideed</tt>. + <ul> + <li> <a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> +puts the uid and gid of user <tt>www</tt> into the environment, for <tt>s6-tcpserver</tt> +to drop root privileges to. </li> + <li> <a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a> +binds to the address and port given, drops privileges, and listens; it accepts connections +and spawns a new process for each one. </li> + <li> <a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a> +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. </li> + <li> <a href="tipideed.html">tipideed</a> is the tipidee daemon, and will +handle HTTP requests until the client closes the connection or tipideed itself +needs to close it. </li> + </ul> </li> + <li> HTTPS requires a bit of additional setup for TLS. If +your certificate is in <tt>/etc/ssl/acme/example.com/cert.pem</tt> and the +corresponding private key is in <tt>/etc/ssl/acme/private/example.com/key.pem</tt>, +the basic command line for your HTTPS service could look like: +<tt>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<tt>. + <ul> + <li> <a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> +puts the uid and gid of user <tt>www</tt> into the environment. </li> + <li> <tt>env</tt> adds the appropriate CERTFILE and KEYFILE variables to the +environment, so TLS programs down the line can find the certificate and key. + <li> <a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a> +rewrites itself into a command line that does a lot of different things; the +long-running process is still <a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a> +listening. For every client connection, it spawns a process that sets up the TLS +transport layer and eventually execs into <tt>tipideed</tt>. </li> + <li> <a href="tipideed.html">tipideed</a> 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 <tt>HTTPS=on</tt> marker. </li> + </ul> </li> + <li> 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. </li> +</ul> + + <h3> tipidee service templates </h3> + +<p> + The tipidee source distribution comes with an <tt>examples/</tt> subdirectory +containing service files to run tipidee under various service managers. +</p> + +</body> +</html> diff --git a/examples/s6-rc/httpd-4-log/consumer-for b/examples/s6-rc/httpd-4-log/consumer-for new file mode 100644 index 0000000..3dfc041 --- /dev/null +++ b/examples/s6-rc/httpd-4-log/consumer-for @@ -0,0 +1 @@ +httpd-4 diff --git a/examples/s6-rc/httpd-4-log/notification-fd b/examples/s6-rc/httpd-4-log/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpd-4-log/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpd-4-log/pipeline-name b/examples/s6-rc/httpd-4-log/pipeline-name new file mode 100644 index 0000000..291f119 --- /dev/null +++ b/examples/s6-rc/httpd-4-log/pipeline-name @@ -0,0 +1 @@ +httpd-4-pipeline diff --git a/examples/s6-rc/httpd-4-log/run b/examples/s6-rc/httpd-4-log/run new file mode 100755 index 0000000..51897c7 --- /dev/null +++ b/examples/s6-rc/httpd-4-log/run @@ -0,0 +1,5 @@ +#!/bin/execlineb -S1 + +s6-setuidgid wwwlog +exec -c +s6-log -d3 t s1000000 n20 /var/log/httpd-4 diff --git a/examples/s6-rc/httpd-4-log/type b/examples/s6-rc/httpd-4-log/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpd-4-log/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpd-4/notification-fd b/examples/s6-rc/httpd-4/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpd-4/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpd-4/producer-for b/examples/s6-rc/httpd-4/producer-for new file mode 100644 index 0000000..9835bc1 --- /dev/null +++ b/examples/s6-rc/httpd-4/producer-for @@ -0,0 +1 @@ +httpd-4-log diff --git a/examples/s6-rc/httpd-4/run b/examples/s6-rc/httpd-4/run new file mode 100755 index 0000000..190392f --- /dev/null +++ b/examples/s6-rc/httpd-4/run @@ -0,0 +1,10 @@ +#!/bin/execlineb -P + +fdmove -c 2 1 +backtick -E ip { pipeline { s6-dnsip4 example.com } head -n 1 } +s6-envuidgid www +cd /home/www +fdmove 1 3 +s6-tcpserver4 -v2 -1 -U -c 512 -- $ip 80 +s6-tcpserver-access -lexample.com -- +tipideed -v2 -- diff --git a/examples/s6-rc/httpd-4/type b/examples/s6-rc/httpd-4/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpd-4/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpd-6-log/consumer-for b/examples/s6-rc/httpd-6-log/consumer-for new file mode 100644 index 0000000..a8c09a3 --- /dev/null +++ b/examples/s6-rc/httpd-6-log/consumer-for @@ -0,0 +1 @@ +httpd-6 diff --git a/examples/s6-rc/httpd-6-log/notification-fd b/examples/s6-rc/httpd-6-log/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpd-6-log/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpd-6-log/pipeline-name b/examples/s6-rc/httpd-6-log/pipeline-name new file mode 100644 index 0000000..bccca20 --- /dev/null +++ b/examples/s6-rc/httpd-6-log/pipeline-name @@ -0,0 +1 @@ +httpd-6-pipeline diff --git a/examples/s6-rc/httpd-6-log/run b/examples/s6-rc/httpd-6-log/run new file mode 100755 index 0000000..50d7448 --- /dev/null +++ b/examples/s6-rc/httpd-6-log/run @@ -0,0 +1,5 @@ +#!/bin/execlineb -S1 + +s6-setuidgid wwwlog +exec -c +s6-log -d3 t s1000000 n20 /var/log/httpd-46 diff --git a/examples/s6-rc/httpd-6-log/type b/examples/s6-rc/httpd-6-log/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpd-6-log/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpd-6/notification-fd b/examples/s6-rc/httpd-6/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpd-6/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpd-6/producer-for b/examples/s6-rc/httpd-6/producer-for new file mode 100644 index 0000000..eb26378 --- /dev/null +++ b/examples/s6-rc/httpd-6/producer-for @@ -0,0 +1 @@ +httpd-6-log diff --git a/examples/s6-rc/httpd-6/run b/examples/s6-rc/httpd-6/run new file mode 100755 index 0000000..ae4dbba --- /dev/null +++ b/examples/s6-rc/httpd-6/run @@ -0,0 +1,10 @@ +#!/bin/execlineb -P + +fdmove -c 2 1 +backtick -E ip { pipeline { s6-dnsip6 example.com } head -n 1 } +s6-envuidgid www +cd /home/www +fdmove 1 3 +s6-tcpserver6 -v2 -1 -U -c 512 -- $ip 80 +s6-tcpserver-access -lexample.com -- +tipideed -v2 -- diff --git a/examples/s6-rc/httpd-6/type b/examples/s6-rc/httpd-6/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpd-6/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpsd-4-log/consumer-for b/examples/s6-rc/httpsd-4-log/consumer-for new file mode 100644 index 0000000..df47160 --- /dev/null +++ b/examples/s6-rc/httpsd-4-log/consumer-for @@ -0,0 +1 @@ +httpsd-4 diff --git a/examples/s6-rc/httpsd-4-log/notification-fd b/examples/s6-rc/httpsd-4-log/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpsd-4-log/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpsd-4-log/pipeline-name b/examples/s6-rc/httpsd-4-log/pipeline-name new file mode 100644 index 0000000..52ff5c9 --- /dev/null +++ b/examples/s6-rc/httpsd-4-log/pipeline-name @@ -0,0 +1 @@ +httpsd-4-pipeline diff --git a/examples/s6-rc/httpsd-4-log/run b/examples/s6-rc/httpsd-4-log/run new file mode 100755 index 0000000..770d831 --- /dev/null +++ b/examples/s6-rc/httpsd-4-log/run @@ -0,0 +1,5 @@ +#!/bin/execlineb -S1 + +s6-setuidgid wwwlog +exec -c +s6-log -d3 t s1000000 n20 /var/log/httpsd-4 diff --git a/examples/s6-rc/httpsd-4-log/type b/examples/s6-rc/httpsd-4-log/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpsd-4-log/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpsd-4/notification-fd b/examples/s6-rc/httpsd-4/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpsd-4/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpsd-4/producer-for b/examples/s6-rc/httpsd-4/producer-for new file mode 100644 index 0000000..1c2200a --- /dev/null +++ b/examples/s6-rc/httpsd-4/producer-for @@ -0,0 +1 @@ +httpsd-4-log diff --git a/examples/s6-rc/httpsd-4/run b/examples/s6-rc/httpsd-4/run new file mode 100755 index 0000000..54be026 --- /dev/null +++ b/examples/s6-rc/httpsd-4/run @@ -0,0 +1,11 @@ +#!/bin/execlineb -P + +fdmove -c 2 1 +backtick -E ip { pipeline { s6-dnsip4 example.com } head -n 1 } +s6-envuidgid www +export KEYFILE /etc/ssl/acme/private/example.com/key.pem +export CERTFILE /etc/ssl/acme/example.com/cert.pem +cd /home/www +fdmove 1 3 +s6-tlsserver -v -4 -1 -U -c 512 -K 30000 -- $ip 443 +tipideed -v2 -- diff --git a/examples/s6-rc/httpsd-4/type b/examples/s6-rc/httpsd-4/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpsd-4/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpsd-6-log/consumer-for b/examples/s6-rc/httpsd-6-log/consumer-for new file mode 100644 index 0000000..f8b60ce --- /dev/null +++ b/examples/s6-rc/httpsd-6-log/consumer-for @@ -0,0 +1 @@ +httpsd-6 diff --git a/examples/s6-rc/httpsd-6-log/notification-fd b/examples/s6-rc/httpsd-6-log/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpsd-6-log/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpsd-6-log/pipeline-name b/examples/s6-rc/httpsd-6-log/pipeline-name new file mode 100644 index 0000000..82fd962 --- /dev/null +++ b/examples/s6-rc/httpsd-6-log/pipeline-name @@ -0,0 +1 @@ +httpsd-6-pipeline diff --git a/examples/s6-rc/httpsd-6-log/run b/examples/s6-rc/httpsd-6-log/run new file mode 100755 index 0000000..a8281ad --- /dev/null +++ b/examples/s6-rc/httpsd-6-log/run @@ -0,0 +1,5 @@ +#!/bin/execlineb -S1 + +s6-setuidgid wwwlog +exec -c +s6-log -d3 t s1000000 n20 /var/log/httpsd-6 diff --git a/examples/s6-rc/httpsd-6-log/type b/examples/s6-rc/httpsd-6-log/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpsd-6-log/type @@ -0,0 +1 @@ +longrun diff --git a/examples/s6-rc/httpsd-6/notification-fd b/examples/s6-rc/httpsd-6/notification-fd new file mode 100644 index 0000000..00750ed --- /dev/null +++ b/examples/s6-rc/httpsd-6/notification-fd @@ -0,0 +1 @@ +3 diff --git a/examples/s6-rc/httpsd-6/producer-for b/examples/s6-rc/httpsd-6/producer-for new file mode 100644 index 0000000..7a7db95 --- /dev/null +++ b/examples/s6-rc/httpsd-6/producer-for @@ -0,0 +1 @@ +httpsd-6-log diff --git a/examples/s6-rc/httpsd-6/run b/examples/s6-rc/httpsd-6/run new file mode 100755 index 0000000..652a354 --- /dev/null +++ b/examples/s6-rc/httpsd-6/run @@ -0,0 +1,11 @@ +#!/bin/execlineb -P + +fdmove -c 2 1 +backtick -E ip { pipeline { s6-dnsip6 example.com } head -n 1 } +s6-envuidgid www +export KEYFILE /etc/ssl/acme/private/example.com/key.pem +export CERTFILE /etc/ssl/acme/example.com/cert.pem +cd /home/www +fdmove 1 3 +s6-tlsserver -v -6 -1 -U -c 512 -K 30000 -- $ip 443 +tipideed -v2 -- diff --git a/examples/s6-rc/httpsd-6/type b/examples/s6-rc/httpsd-6/type new file mode 100644 index 0000000..5883cff --- /dev/null +++ b/examples/s6-rc/httpsd-6/type @@ -0,0 +1 @@ +longrun diff --git a/examples/tipidee.conf b/examples/tipidee.conf new file mode 100644 index 0000000..f75a9cc --- /dev/null +++ b/examples/tipidee.conf @@ -0,0 +1,41 @@ +### Global definitions + +# After 1 minute without a new request, exit +global read_timeout 60000 + +# If the client fails to read a response for 1 minute, exit +global write_timeout 60000 + +# If a CGI script takes more than 10s to run, kill it and respond 504 instead +global cgi_timeout 10000 + +# Serve .ini and .cfg files as plain text +content-type text/plain .ini .cfg + + +### Definitions for the example.com virtual domain +domain example.com + +# CGI scripts called nph-foobar are considered non-parsed-headers +nph-prefix nph- + +# CGI scripts live under /cgi-bin +cgi /cgi-bin/ + +# Serve http://example.com/README as plain text +file-type /README text/plain + +# Redirect http://example.com/rickroll to a fan favorite video. +# Make it temporary to avoid revealing the trick in the client. +redirect /rickroll 307 https://www.youtube.com/watch?v=dQw4w9WgXcQ + +# Permanently redirect http://example.com/community/foobar... requests +# to https://example.org/foobar... +redirect /community/ 308 https://example.org + + +### Definitions for the example.org virtual domain +domain example.org + +nph-prefix nph- +cgi /cgi-bin/ |