Commit | Line | Data |
---|---|---|
5085a1f1 FT |
1 | ashd -- A Sane HTTP Daemon |
2 | ||
3 | Ashd is a HTTP server that follows standard Unix philosophy for | |
4 | modularity. Instead of being a monolithic program with loadable | |
5 | modules, as most other HTTP servers seem to be, Ashd is simply a | |
6 | collection of much simpler programs, passing HTTP requests to each | |
7 | other using a simple protocol. | |
8 | ||
9 | Among the nice properties brought about by such a design, the | |
10 | following 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 | ||
42 | Though the server as a whole is called `Ashd', there is no actual | |
43 | program by that name. The `htparser' program of Ashd implements a | |
44 | minimal HTTP server. It speaks HTTP (1.0 and 1.1) with clients, but it | |
45 | does not know anything about actually handling the requests it | |
46 | receives. Rather, having started a handler program as specified on the | |
47 | command-line, it packages the requests up and passes them to that | |
48 | handler program. That handler program may choose to only look at part | |
49 | of the URL and pass the request on to other handler programs based on | |
50 | what it sees. In that way, the handler programs form a tree-like | |
51 | structure, corresponding roughly to the URL space of the server. In | |
52 | order to do that, the packaged request which is passed between the | |
53 | handler programs contains the part of the URL which remains to be | |
54 | parsed, referred to as the `rest string' or the `point' (in deference | |
55 | to Emacs parlance). | |
56 | ||
57 | For a technical description of the architecture, see the ashd(7) | |
58 | manpage, available in the `doc' directory of this source tree. | |
59 | ||
60 | The Cast | |
61 | ||
62 | As an introduction to the various programs that compose Ashd, here is | |
63 | a listing of the more important programs. All of them have manpages, | |
64 | so 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. |