1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
<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/docs</tt> and you need to
serve the <tt>example.com</tt> and <tt>example.org</tt> domains, create
<tt>/home/www/docs/example.com</tt> and <tt>/home/www/docs/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/docs</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 addresses. </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>, and your
local IP address is ${ip}, the basic command line for an HTTP service is:
<tt>s6-envuidgid www s6-tcpserver -U ${ip} 80 s6-tcpserver-access 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. (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.) </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 ${ip} 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 and accepting client connections. For every client, 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 aware (via an environment variable)
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>
|
