doc: Made an actual INSTALL file.
[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
065b84ef
FT
40 Getting Started
41
42To get Ashd installed and running quickly, please follow the
43instructions in the `INSTALL' file.
44
5085a1f1
FT
45 Architecture Overview
46
47Though the server as a whole is called `Ashd', there is no actual
48program by that name. The `htparser' program of Ashd implements a
49minimal HTTP server. It speaks HTTP (1.0 and 1.1) with clients, but it
50does not know anything about actually handling the requests it
51receives. Rather, having started a handler program as specified on the
52command-line, it packages the requests up and passes them to that
53handler program. That handler program may choose to only look at part
54of the URL and pass the request on to other handler programs based on
55what it sees. In that way, the handler programs form a tree-like
56structure, corresponding roughly to the URL space of the server. In
57order to do that, the packaged request which is passed between the
58handler programs contains the part of the URL which remains to be
59parsed, referred to as the `rest string' or the `point' (in deference
60to Emacs parlance).
61
62For a technical description of the architecture, see the ashd(7)
63manpage, available in the `doc' directory of this source tree.
64
65 The Cast
66
67As an introduction to the various programs that compose Ashd, here is
68a listing of the more important programs. All of them have manpages,
69so 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
75 actual directories, in a manner akin to how most other HTTP server
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.