README

   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                            Getting Started
  41
  42 To  get  Ashd  installed   and  running  quickly,  please  follow  the
  43 instructions in the `INSTALL' file.
  44
  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
  75    actual directories, in a manner akin to how most other HTTP servers
  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.