about summary refs log tree commit diff
path: root/doc/index.html
blob: 8a27de2ccd89cfdb5a79b021ebabad6ad8a33b94 (plain) (blame)
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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
<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 - a small and fast HTTP/1.1 server</title>
    <meta name="Description" content="tipidee - a small and fast HTTP/1.1 server" />
    <meta name="Keywords" content="tipidee web server http https laurent bercot ska skarnet.org" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>

<h1> tipidee </h1>

<h2> What is it&nbsp;? </h2>

<p>
  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. 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 with
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 roughly two groups of web servers.
</p>

<p>
 The first one is big, powerful servers such as
<a href="https://nginx.org/">nginx</a>,
<a href="https://httpd.apache.org/">Apache httpd</a>,
and so on. They focus on environments where simplicity isn't a concern
and can be traded off for features, integration with larger ecosystems,
or just serving speed. (<a href="https://www.lighttpd.net/">lighttpd</a>,
for instance, was developed as a proof of concept for solving the
<a href="http://www.kegel.com/c10k.html">c10k problem</a>.)
</p>

<p>
 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 &mdash; which means delegating the TLS layer to a super-server
and not performing the socket work itself. This is important: tying your
Web server to a TLS library makes it more difficult to maintain, more
difficult to secure, more difficult to build, and more difficult to
package and distribute. </li>
 <li> Support for HTTP 1.1, with persistent connections, and 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
similar sites that need an <em>intermediary</em> web server.
</p>

<h3> And why "tipidee"? </h3>

<p>
 Because <em>h-t-t-p-d</em> is already pretty tedious to say out loud, and
other web servers have a nasty habit of <em>adding</em> to it; but I'd rather
make it shorter. Just like the code.
</p>

<h2> Installation </h2>

<h3> Requirements </h3>

<ul>
 <li> A POSIX-compliant system with a standard C development environment </li>
 <li> GNU make, version 3.81 or later </li>
 <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
2.14.0.0 or later. It's a build-time requirement. It's also a run-time
requirement if you link against the shared version of the skalibs
library. </li>
 <li> Recommended at run-time: <a href="//skarnet.org/software/s6-networking/">s6-networking</a> version
2.6.0.0 or later. It's not a strict requirement, but tipidee relies on a super-server such as
<a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a>
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. 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. It <em>will</em> make your life easier.
 <ul>
  <li> When built with BearSSL,
<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a>
basically gives you a TLS tunnel <em>for free</em>. Bearly any RAM use.
Don't take my word for it; try it out for yourself. </li>
 </ul> </li>
</ul>

<h3> Licensing </h3>

<p>
 tipidee is free software. It is available under the
<a href="https://opensource.org/licenses/ISC">ISC license</a>.
</p>

<h3> Download </h3>

<ul>
 <li> The current released version of tipidee is
<a href="tipidee-0.0.1.0.tar.gz">0.0.1.0</a>.
(That is a lie. The link is broken, because tipidee is still
in beta. It will work when it's officially released.) </li>
 <li> You can checkout a copy of the
<a href="//git.skarnet.org/cgi-bin/cgit.cgi/tipidee/">tipidee
git repository</a>:
<pre> git clone git://git.skarnet.org/tipidee </pre> </li>
 <li> There's also a
<a href="https://github.com/skarnet/tipidee">GitHub mirror</a>
of the tipidee git repository. </li>
</ul>

<h3> Compilation </h3>

<ul>
 <li> See the enclosed INSTALL file for installation details. </li>
</ul>

<h3> Upgrade notes </h3>

<ul>
 <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between
the previous versions of tipidee and the current one. </li>
</ul>

<hr />

<h2> Reference </h2>

<h3> Commands </h3>

<ul>
<li><a href="tipideed.html">The <tt>tipideed</tt> program</a></li>
<li><a href="tipidee-config.html">The <tt>tipidee-config</tt> program</a></li>
</ul>

<h3> Internal commands </h3>

<ul>
<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>

<h3> Usage notes </h3>

<ul>
<li> tipidee's <a href="quickstart.html">quickstart guide</a> </li>
<li> A list of <a href="faq.html">caveats and FAQs</a> </li>
</ul>

<h3> Design notes </h3>

<ul>
<li> <a href="future.html">Features that may appear in future versions of tipidee</a> </li>
</ul>

<h2> Related resources </h2>

<ul>
 <li> <tt>tipidee</tt> is discussed on the
<a href="//skarnet.org/lists/#skaware">skaware</a> mailing-list. </li>
</ul>

</body>
</html>