home *** CD-ROM | disk | FTP | other *** search
/ PC Online 1999 April / PCO0499.ISO / filesbbs / os2 / apach134.arj / APACH134.ZIP / src / README < prev   
Encoding:
Text File  |  1996-12-03  |  6.8 KB  |  148 lines
  1. The following document was written by Robert S. Thau (rst@ai.mit.edu) on the
  2. release of Apache 1.0.  Some details may have changed since then regarding the
  3. functions and names of modules, but the basic ideas are still intact.
  4.  =================================================
  5.  
  6. The basic idea of the new Apache release is to make a modular
  7. "tinkertoy" server, to which people can easily add code which is
  8. valuable to them (even if it isn't universally useful) without hairing
  9. up a monolithic server.  Applications for this idea include database
  10. integration, support for experimental search and scripting extensions,
  11. new authentication modes (digest authentication, for instance, could
  12. be done entirely as a module), and so forth.  All modules have the
  13. same interface to the server core, and through it, to each other.
  14.  
  15. In particular, the following are modules in the current code base:
  16. common log format (other loggers can easily coexist with it), auth and
  17. dbm auth (although both use common code in http_protocol.c to parse
  18. the Authorization: line), directory handling (which can be added or
  19. replaced), handling of aliases and access control, content
  20. negotiation, CGI, includes, aliases, and so forth.  (What's left in
  21. the basic server?  Not a whole lot).  The configuration file commands
  22. which configure these things are defined, for the most part, by the
  23. modules themselves, and not by the server core (each module has, or
  24. can have, a command dispatch table).
  25.  
  26. Besides carving up the base code into modules, this release makes a
  27. few other fairly pervasive changes.  Most of the global variables are
  28. gone; most of the MAX_STRING_LENGTH char arrays are gone (the few that
  29. are left being sprintf() targets, or I/O buffers of various sorts),
  30. and unmunge_name has vanished.  The most drastic change is the use of
  31. a "compool" strategy to manage resources allocated for a request ---
  32. the code in alloc.c keeps track of it all and allows it to be freed en
  33. bloc at the end of the request.  This strategy seems to be effective
  34. in stanching memory and descriptor leaks.
  35.  
  36. Additional third-party modules can be found at
  37. <URL:http://www.apache.org/dist/contrib/modules/>.
  38.  
  39.  
  40. A brief code review:
  41.  
  42. The code here can be divided into the server core (the http_* files,
  43. along with alloc.c and the various utility files), and several modules
  44. (the mod_* files).
  45.  
  46. The core interfaces to modules through the "module" structure which
  47. describes each one.  There's a linked list of these things rooted at
  48. top_module, through which http_config.c dispatches when necessary.  The
  49. module structures themselves are defined at the bottom of the mod_foo
  50. files.  (Loading new modules dynamically at runtime should be simple;
  51. just push them onto the linked list.  The only complication is what to
  52. do with AddModule commands when the config files are reread,
  53. particularly if you find a module has been taken out).
  54.  
  55. In addition to the core itself (which does have a module structure to
  56. hold its command tables, and the handlers for various phases of
  57. request handling which make it *barely* a web server on its own),
  58. the modules included here are the following:
  59.  
  60. mod_mime.c --- deduction of MIME types and content-encodings from
  61.   filename extensions.  This module defines the AddType, AddEncoding,
  62.   and TypesConfig config-file directives.  This code is off in a
  63.   module by itself so that people who want to experiment with other
  64.   meta-information schemes can replace it, and still have content
  65.   negotiation work.
  66.  
  67. mod_log_config.c --- logging in configurable or common log format.
  68.  
  69. mod_auth.c --- HTTP authentication.  Defines the AuthUserFile and
  70.   AuthGroupFile directives (other auth-related commands are handled by
  71.   the core itself, so it knows which requests require it to poll the
  72.   modules for authentication handlers).
  73.  
  74. mod_auth_dbm.c --- DBM auth.  Untested, and left out of the modules
  75.   list in modules.c because of that, but it does at least compile.
  76.   Grump. 
  77.  
  78. mod_access.c --- access checking by DNS name or IP address; defines
  79.   the "order", "allow" and "deny" config-file commands.  (If this
  80.   module is compiled out, the server fails safe --- any attempt to
  81.   configure access control will die on a config file syntax error when
  82.   the relevant commands go unrecognized).
  83.  
  84. mod_negotiation.c --- Content negotiation.  Defines the
  85.   CacheNegotiatedDocs config-file command.  Making this a module is
  86.   perhaps going overboard, but I wanted to see how far I could push
  87.   it. 
  88.  
  89. mod_alias.c --- Alias command and file translation.
  90.  
  91. mod_userdir.c --- ditto for Userdir.
  92.  
  93. mod_cgi.c --- Common Gateway Interface.  Also defines ScriptAlias,
  94.   because scripts are treated slightly differently depending on
  95.   whether they are ScriptAliased or not (in particular, ExecCGI is not
  96.   required in the former case).
  97.  
  98. mod_includes.c --- server-side includes.
  99.  
  100. mod_dir.c --- defines a whole *raft* of commands; handles directories.
  101.  
  102. mod_asis.c --- ASIS file handling.
  103.  
  104. mod_dld.c --- the experimental runtime-code-loader described above.
  105.   You'll have to alter the makefile and modules.c to make this active
  106.   if you want it.
  107.  
  108.  
  109.  
  110. As to the core, here's a brief review of what's where:
  111.  
  112. http_protocol.c --- functions for dealing directly with the client.
  113.   Reading requests, writing replies of various sorts.  I've tried to
  114.   route all data transfer between server and client through here, so
  115.   there's a single piece of code to change if we want to add, say,
  116.   HTTP-NG packetization.  The major glaring exception is NPH- CGI
  117.   scripts; what *will* we do with those for HTTP-NG?
  118.  
  119. http_request.c --- functions which direct the processing of requests,
  120.   including error handling.  Generally responsible for making sure
  121.   that the right module handlers get invoked, in the right order.
  122.   (This includes the "sub-request" mechanism, which is used by
  123.   includes and other stuff to ask about the status of particular
  124.   subfiles).
  125.  
  126. http_core.c --- 
  127.   Contains the core module structure, its command table, and the
  128.   command handlers, also the filename translation routine, and the
  129.   like for the core.  (Basically, this is all of the core module stuff
  130.   which looks more or less like the boilerplate from the other modules).
  131.  
  132. http_config.c --- Functions to read config files and dispatch to the
  133.   command handlers; also, routines to manage configuration vectors,
  134.   and to dispatch to modules' handlers for the various phases of
  135.   handling a request.  
  136.  
  137. http_log.c --- just the error log.  Error handling is split between
  138.   http_protocol.c (for generating the default error responses) and
  139.   http_request.c (for executive handling, including ErrorDocument
  140.   invocation); transaction logging is in the modules.
  141.  
  142. http_main.c --- System startup, restart, and accepting connections;
  143.   also timeout handling (which is pretty grotesque right now; ideas?)
  144.  
  145. alloc.c --- allocation of all resources which might have to be reclaimed
  146.   eventually, including memory, files, and child processes.
  147.  
  148.