Documentation Source Text

Check-in [9ea89e32bf]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the althttpd.md documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 9ea89e32bfb89163262c443557b7843f1a0c4b0408ec81ba1c3f92f01892db29
User & Date: drh 2019-02-27 13:46:02.876
Context
2019-02-27
23:13
Add a note to the printf() documentation to make clear that the built-in SQLite printf() does not implement positional parameters. (check-in: e0c57dd3d0 user: drh tags: branch-3.27)
16:51
Add documentation for the Tcl command "db function" -returntype option. (check-in: 2f154421cf user: dan tags: trunk)
13:46
Updates to the althttpd.md documentation. (check-in: 9ea89e32bf user: drh tags: trunk)
13:20
Sanitize the search string when doing a search against the changelog. (check-in: 0a969667a7 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to misc/althttpd.md.
︙︙
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

average on this machine normally stays around 0.1 or 0.2.  About 19%
of the HTTP requests are CGI to various [Fossil](https://fossil-scm.org/)
source-code repositories.

Design Philosophy
----------------

Althttpd was originally designed to be launched from 
[xinetd](https://en.wikipedia.org/wiki/Xinetd) or
[stunnel4](https://www.stunnel.org/).  A separate process
is started for each incoming connection, and that process is
wholly focused on serving that one connection.  A single althttpd
process will handle one or more HTTP requests over the same connection.
When the connection closes, the althttpd process exits.

Newer versions of althttpd can operate stand-alone.  Althttpd
itself listens on port 80 for incoming HTTP requests, then forks
a copy of itself to handle each inbound connection.  Each connection
is still handled using a separate process.  The only difference is
that the connection-handler process is now started by a master
althttpd instance rather than by xinetd or stunnel4.

Althttpd has no configuration file.  All configuration is handled
using command-line arguments.



Althttpd does not itself handle TLS connection.  For HTTPS, althttpd
relies on stunnel4 to handle TLS protocol negotiation, decryption, and
encryption.

Because each althttpd process only needs to service a single
connection, althttpd is single threaded.  Furthermore, each process
only lives for the duration of a single connection, which means that
althttpd does not need to worry too much about memory leaks.




Source Code
-----------

The complete source code for althttpd is contained within a single
C-code file with no dependences outside of the standard C library.








|

|





|






|
|
>
>

|







>
>








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

average on this machine normally stays around 0.1 or 0.2.  About 19%
of the HTTP requests are CGI to various [Fossil](https://fossil-scm.org/)
source-code repositories.

Design Philosophy
----------------

Althttpd is usually launched from 
[xinetd](https://en.wikipedia.org/wiki/Xinetd) or
[stunnel4](https://www.stunnel.org/). A separate process
is started for each incoming connection, and that process is
wholly focused on serving that one connection.  A single althttpd
process will handle one or more HTTP requests over the same connection.
When the connection closes, the althttpd process exits.

Althttpd can also operate stand-alone. Althttpd
itself listens on port 80 for incoming HTTP requests, then forks
a copy of itself to handle each inbound connection.  Each connection
is still handled using a separate process.  The only difference is
that the connection-handler process is now started by a master
althttpd instance rather than by xinetd or stunnel4.

Althttpd has no configuration file. All configuration is handled
using a few command-line arguments. This helps to keep this
configuration simple and mitigate worries about about introducing
a security vulnerability through a misconfigured web server.

Althttpd does not itself handle TLS connections.  For HTTPS, althttpd
relies on stunnel4 to handle TLS protocol negotiation, decryption, and
encryption.

Because each althttpd process only needs to service a single
connection, althttpd is single threaded.  Furthermore, each process
only lives for the duration of a single connection, which means that
althttpd does not need to worry too much about memory leaks.
These design factors help keep the althttpd source code simple,
which facilitates security auditing and analysis.


Source Code
-----------

The complete source code for althttpd is contained within a single
C-code file with no dependences outside of the standard C library.
︙︙
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

the chroot jail.

The -root option tells althttpd where to find the document hierarchy.
In the case of sqlite.org, all content is served from /home/www.
At the top level of this document hierarchy is a bunch of directories
whose names end with ".website".  Each such directory is a separate
website.  The directory is chosen based on the Host: parameter of the
incoming HTTP request.  A _partial_ list of the directories on sqlite.org
is this:

>
    3dcanvas_tcl_lang_org.website
    3dcanvas_tcl_tk.website
    androwish_org.website
    canvas3d_tcl_lang_org.website








|








108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

the chroot jail.

The -root option tells althttpd where to find the document hierarchy.
In the case of sqlite.org, all content is served from /home/www.
At the top level of this document hierarchy is a bunch of directories
whose names end with ".website".  Each such directory is a separate
website.  The directory is chosen based on the Host: parameter of the
incoming HTTP request.  A partial list of the directories on sqlite.org
is this:

>
    3dcanvas_tcl_lang_org.website
    3dcanvas_tcl_tk.website
    androwish_org.website
    canvas3d_tcl_lang_org.website
︙︙
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

On a minimal installation that only hosts a single website, it suffices
to have a single subdirectory named "default.website".

Within the *.website directory, the file to be served is selected by
the HTTP request URI.  Files that are marked as executable are run
as CGI.  Non-executable files with a name that ends with ".scgi"
and that have content of the form "SCGI hostname port" relay an SCGI
request to hostname:port. All other non-execcutable files are delivered
as-is.

If the request URI specifies the name of a directory within *.website,
then althttpd appends "/index.html" and "/index.cgi", in that order,
looking for a match.

If a prefix of a URI matches the name of an executable file then that








|








154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

On a minimal installation that only hosts a single website, it suffices
to have a single subdirectory named "default.website".

Within the *.website directory, the file to be served is selected by
the HTTP request URI.  Files that are marked as executable are run
as CGI.  Non-executable files with a name that ends with ".scgi"
and that have content of the form "SCGI hostname port" relay an SCGI
request to hostname:port. All other non-executable files are delivered
as-is.

If the request URI specifies the name of a directory within *.website,
then althttpd appends "/index.html" and "/index.cgi", in that order,
looking for a match.

If a prefix of a URI matches the name of an executable file then that
︙︙