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 | ||
065b84ef FT |
40 | Getting Started |
41 | ||
42 | To get Ashd installed and running quickly, please follow the | |
43 | instructions in the `INSTALL' file. | |
44 | ||
5085a1f1 FT |
45 | Architecture Overview |
46 | ||
47 | Though the server as a whole is called `Ashd', there is no actual | |
48 | program by that name. The `htparser' program of Ashd implements a | |
49 | minimal HTTP server. It speaks HTTP (1.0 and 1.1) with clients, but it | |
50 | does not know anything about actually handling the requests it | |
51 | receives. Rather, having started a handler program as specified on the | |
52 | command-line, it packages the requests up and passes them to that | |
53 | handler program. That handler program may choose to only look at part | |
54 | of the URL and pass the request on to other handler programs based on | |
55 | what it sees. In that way, the handler programs form a tree-like | |
56 | structure, corresponding roughly to the URL space of the server. In | |
57 | order to do that, the packaged request which is passed between the | |
58 | handler programs contains the part of the URL which remains to be | |
59 | parsed, referred to as the `rest string' or the `point' (in deference | |
60 | to Emacs parlance). | |
61 | ||
62 | For a technical description of the architecture, see the ashd(7) | |
63 | manpage, available in the `doc' directory of this source tree. | |
64 | ||
65 | The Cast | |
66 | ||
67 | As an introduction to the various programs that compose Ashd, here is | |
68 | a listing of the more important programs. All of them have manpages, | |
69 | so please see those for further details. | |
70 | ||
71 | * htparser -- The `actual' HTTP server. htparser is the program that | |
72 | listens to TCP connections and speaks HTTP with the clients. | |
73 | ||
74 | * dirplex -- dirplex is the program used for serving files from | |
84a034e1 | 75 | actual directories, in a manner akin to how most other HTTP servers |
5085a1f1 FT |
76 | work. In order to do that, dirplex maps URLs into existing physical |
77 | files, and then performs various kinds of pattern-matching against | |
78 | the names of those physical files to determine the handler to call | |
79 | to actually serve them. | |
80 | ||
81 | * patplex -- Performs pattern matching against logical request | |
82 | parameters such as the rest string, URL or various headers to | |
83 | determine a program to pass the request to. As such, patplex can be | |
84 | used to implement such things as virtual directories or virtual | |
85 | hosts. | |
86 | ||
87 | * sendfile -- A simple handler program for sending literal file | |
88 | contents, normally called by dirplex for serving ordinary files. It | |
89 | handles caching using the Last-Modified and related headers. It | |
90 | also handles MIME-type detection if a specific MIME-type was not | |
91 | specified. | |
92 | ||
93 | * callcgi -- Translates an Ashd request into a CGI environment, and | |
94 | runs either the requested file directly as a CGI script, or an | |
95 | external CGI handler. Thus, it can be used to serve, for example, | |
96 | PHP pages. | |
97 | ||
98 | * userplex -- Handles `user directories', to use Apache parlance; you | |
99 | may know them otherwise as /~user/ URLs. When a request is made for | |
100 | the directory of a specific user, it makes sure that the request | |
101 | handler runs as the user in question. |