Added support for reading additional certificates for SNI usage.
[ashd.git] / README
CommitLineData
5085a1f1
FT
1 ashd -- A Sane HTTP Daemon
2
3Ashd is a HTTP server that follows standard Unix philosophy for
4modularity. Instead of being a monolithic program with loadable
5modules, as most other HTTP servers seem to be, Ashd is simply a
6collection of much simpler programs, passing HTTP requests to each
7other using a simple protocol.
8
9Among the nice properties brought about by such a design, the
10following might be said to stand out:
11
12 * Sanity of design -- The clean delineation of functions allows each
13 program to be very small and simple – currently, each of the
14 programs in the collection (including even the core HTTP parser
15 program, htparser, as long as one does not count its, quite
16 optional, SSL implementation) is implemented in less than 1,000
17 lines of C code (and most are considerably smaller than that),
18 allowing them to be easily studied and understood.
19
20 * Security -- Since each program runs in a process of its own, it can
21 be assigned proper permissions. Most noteworthy of all, the
22 userplex program ensures that serving of user home directories only
23 happens by code that is actually logged in as the user in question;
24 and the htparser program, being the only program which speaks
25 directly with the clients, can run perfectly well as a non-user
26 (like nobody) and be chroot'ed into an empty directory.
27
28 * Persistence -- Though Ashd is a multi-process program, it is not in
29 the same sense as e.g. Apache. Each request handler continues to
30 run indefinitely and does not spawn multiple copies of itself,
31 meaning that all process state persists between requests – session
32 data can be kept in memory, connections to back-end services can be
33 kept open, and so on.
34
35 * Clean modularity -- With only a rather basic understanding of HTTP
36 and the internal Ashd protocol, it is quite easy to write new
37 request handlers to extend the server's functionality; and one can
38 do that even without needing root privileges on the system.
39
40 Architecture Overview
41
42Though the server as a whole is called `Ashd', there is no actual
43program by that name. The `htparser' program of Ashd implements a
44minimal HTTP server. It speaks HTTP (1.0 and 1.1) with clients, but it
45does not know anything about actually handling the requests it
46receives. Rather, having started a handler program as specified on the
47command-line, it packages the requests up and passes them to that
48handler program. That handler program may choose to only look at part
49of the URL and pass the request on to other handler programs based on
50what it sees. In that way, the handler programs form a tree-like
51structure, corresponding roughly to the URL space of the server. In
52order to do that, the packaged request which is passed between the
53handler programs contains the part of the URL which remains to be
54parsed, referred to as the `rest string' or the `point' (in deference
55to Emacs parlance).
56
57For a technical description of the architecture, see the ashd(7)
58manpage, available in the `doc' directory of this source tree.
59
60 The Cast
61
62As an introduction to the various programs that compose Ashd, here is
63a listing of the more important programs. All of them have manpages,
64so please see those for further details.
65
66 * htparser -- The `actual' HTTP server. htparser is the program that
67 listens to TCP connections and speaks HTTP with the clients.
68
69 * dirplex -- dirplex is the program used for serving files from
70 actual directories, in a manner akin to how most other HTTP server
71 work. In order to do that, dirplex maps URLs into existing physical
72 files, and then performs various kinds of pattern-matching against
73 the names of those physical files to determine the handler to call
74 to actually serve them.
75
76 * patplex -- Performs pattern matching against logical request
77 parameters such as the rest string, URL or various headers to
78 determine a program to pass the request to. As such, patplex can be
79 used to implement such things as virtual directories or virtual
80 hosts.
81
82 * sendfile -- A simple handler program for sending literal file
83 contents, normally called by dirplex for serving ordinary files. It
84 handles caching using the Last-Modified and related headers. It
85 also handles MIME-type detection if a specific MIME-type was not
86 specified.
87
88 * callcgi -- Translates an Ashd request into a CGI environment, and
89 runs either the requested file directly as a CGI script, or an
90 external CGI handler. Thus, it can be used to serve, for example,
91 PHP pages.
92
93 * userplex -- Handles `user directories', to use Apache parlance; you
94 may know them otherwise as /~user/ URLs. When a request is made for
95 the directory of a specific user, it makes sure that the request
96 handler runs as the user in question.