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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<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 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>, 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 -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>
<div id="faq">
<h2> Frequently asked questions </h2>
</div>
<h3> I want my web server to listen to more than one address. Do I need
to do all that for every address I have? </h3>
<p>
Not necessarily: you could listen to <tt>0.0.0.0</tt> for IPv4, and
<tt>::</tt> for IPv6. But if you don't want your server to listen to
<em>all</em> the addresses on your machine, then yes, you will have
to run one process per address:port tuple.
</p>
<p>
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
<a href="//skarnet.org/software/s6/s6-log.html">s6-log</a> 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;
all your resources are still available for the serving itself.
</p>
<p>
Note that this allows you to run different instances of
<a href="tipideed.html">tipideed</a>, on different sockets, with different
configurations, if you need it. Use the <tt>-f</tt> option to specify a
different config file in your instances.
</p>
</body>
</html>
|
