Add the INSTALL file.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87472 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 449 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000000..ba598eb212
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,449 @@
+
+  APACHE INSTALLATION
+
+  Introduction
+  ============
+
+  Apache 2.0's configuration and installation environment has changed
+  completely from Apache 1.3.  Apache 1.3 used a custom set of scripts
+  to achieve easy installation.  Apache 2.0 now uses libtool and autoconf
+  to create an environment that looks like many other Open Source projects.
+
+
+  Installing the Apache 1.3 HTTP server with APACI
+  ================================================
+
+  1. Overview for the impatient
+     --------------------------
+
+     $ ./buildconf
+     $ ./configure --prefix=PREFIX
+     $ make
+     $ make install
+     $ PREFIX/bin/apachectl start
+
+     NOTE: PREFIX is not the string "PREFIX". Instead use the Unix
+           filesystem path under which Apache should be installed. For
+           instance use "/usr/local/apache" for PREFIX above.
+
+  2. Requirements
+     ------------
+
+     The following requirements exist for building Apache:
+
+     o  Disk Space: 
+
+        Make sure you have approximately 12 MB of temporary free disk space
+        available.  After installation Apache occupies approximately 5 MB of
+        disk space (the actual required disk space depends on the amount of
+        compiled in third party modules, etc).
+
+     o  ANSI-C Compiler: 
+
+        Make sure you have an ANSI-C compiler installed. The GNU C compiler
+        (GCC) from the Free Software Foundation (FSF) is recommended (version
+        2.7.2 is fine). If you don't have GCC then at least make sure your
+        vendors compiler is ANSI compliant. You can find the homepage of GNU
+        at http://www.gnu.org/ and the GCC distribution under
+        http://www.gnu.org/order/ftp.html .
+
+     o  Libtool 1.3.3:
+
+        Make sure that you have libtool 1.3.3 or later installed before
+        trying to configure and build Apache 2.0.  Libtool can be downloaded
+        from the Free Software Foundation (FSF), at 
+        http://www.gnu.org/order/ftp.html.
+
+     o  Autoconf 2.13:
+
+        Make sure that you have autoconf 2.13 or later installed before
+        trying to configure and build Apache 2.0.  Autoconf can be
+        downloaded from the Free Software Foundation (FSF), at
+        http://www.gnu.org/order/ftp.html.
+
+     o  Perl 5 Interpreter [OPTIONAL]:
+
+        For some of the support scripts like `apxs' or `dbmmanage' (which are
+        written in Perl) the Perl 5 interpreter is required (versions 5.003
+        and 5.004 are fine). If no such interpreter is found by APACI's
+        `configure' script this is no harm.  Of course, you still can build
+        and install Apache 1.3. Only those support scripts cannot be used. If
+        you have multiple Perl interpreters installed (perhaps a Perl 4 from
+        the vendor and a Perl 5 from your own), then it is recommended to use
+        the --with-perl option (see below) to make sure the correct one is
+        selected by APACI.
+
+     o  Dynamic Shared Object (DSO) support [OPTIONAL]:
+
+        To provide maximum flexibility Apache now is able to load modules
+        under runtime via the DSO mechanism by using the pragmatic
+        dlopen()/dlsym() system calls. These system calls are not available
+        under all operating systems therefore you cannot use the DSO mechanism
+        on all platforms. And Apache currently has only limited built-in
+        knowledge on how to compile shared objects because this is heavily
+        platform-dependent. The current state is this:
+
+        o Out-of-the-box supported platforms are (Not all of these will
+          work currently.  DSO support is currently available on most
+          of these platforms however):
+           - Linux     - SunOS         - UnixWare     - Darwin/Mac OS
+           - FreeBSD   - Solaris       - AIX          - OpenStep/Mach
+           - OpenBSD   - IRIX          - SCO          - DYNIX/ptx
+           - NetBSD    - HPUX          - ReliantUNIX
+           - BSDI      - Digital Unix  - DGUX
+
+        o Entirely unsupported platforms are:
+           - Ultrix
+
+        If your system is not on these lists but has the dlopen-style
+        interface, you either have to provide the appropriate compiler and
+        linker flags (see CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT
+        below) manually or at least make sure a Perl 5 interpreter is
+        installed from which Apache can guess the options.
+
+  3. Configuring the source tree
+     ---------------------------
+
+     Setup:
+ 
+     The first step in compiling Apache 2.0 is to setup the source tree so
+     that it can be built.  This is done by running:
+ 
+     ./buildconf
+
+     This script ensures that all required programs are installed on the
+     currently machine, and creates the ./configure script.  If you are
+     using a package downloaded from apache.org then this step is not 
+     necessary.
+
+     Introduction:
+
+     The next step is to configure the Apache source tree for your particular
+     platform and personal requirements. The most important setup here is the
+     location prefix where Apache is to be installed later, because Apache has
+     to be configured for this location to work correctly. But there are a lot
+     of other options available for your pleasure.
+
+     For a short impression of what possibilities you have, here is a typical
+     example which compiles Apache for the installation tree /sw/pkg/apache
+     with a particular compiler and flags plus the two additional modules
+     mod_rewrite and mod_speling for later loading through the DSO mechanism: 
+
+     $ CC="pgcc" OPTIM="-O2" \
+       ./configure --prefix=/sw/pkg/apache \
+                   --enable-rewrite=shared \
+                   --enable-speling=shared
+
+     The easiest way to find all of the configuration flags for Apache 2.0
+     is to run ./configure --help.  What follows is a brief description of
+     most of the arguments.
+
+     Reference:
+
+     $ [CC=...]        [CFLAGS_SHLIB=...]           [TARGET=...]
+       [OPTIM=...]     [LD_SHLIB=...]
+       [CFLAGS=...]    [LDFLAGS_SHLIB=...]        
+       [INCLUDES=...]  [LDFLAGS_SHLIB_EXPORT=...] 
+       [LDFLAGS=...]   [RANLIB=...]  
+       [LIBS=...]      [DEPS=...]
+       ./configure
+           [--quiet]         [--prefix=DIR]            [--enable-NAME=(shared)]
+           [--verbose]       [--exec-prefix=PREFIX]    [--disable-NAME]
+           [--shadow[=DIR]]  [--bindir=EPREFIX]        [--with-mpm=NAME]
+           [--show-layout]   [--sbindir=DIR]           
+           [--help]          [--libexecdir=DIR]        
+                             [--mandir=DIR]            
+                             [--sysconfdir=DIR]        
+                             [--datadir=DIR]           
+                             [--includedir=DIR]        
+                             [--localstatedir=DIR]
+                             [--runtimedir=DIR]        [--enable-suexec]
+                             [--logfiledir=DIR]        [--suexec-caller=UID]
+                             [--proxycachedir=DIR]     [--suexec-docroot=DIR]
+                             [--with-layout=[FILE:]ID] [--suexec-logfile=FILE]
+                                                       [--suexec-userdir=DIR]
+                             [--with-perl=FILE]        [--suexec-uidmin=UID]
+                             [--without-support]       [--suexec-gidmin=GID]
+                             [--without-confadjust]    [--suexec-safepath=PATH]
+                             [--without-execstrip]
+			     [--server-uid=UID]        [--with-maintainter-mode]
+			     [--server-gid=GID]
+
+     Use the CC, OPTIM, CFLAGS, INCLUDES, LDFLAGS, LIBS, CFLAGS_SHLIB,
+     LD_SHLIB, LDFLAGS_SHLIB, LDFLAGS_SHLIB_EXPORT, RANLIB, DEPS and TARGET
+     environment variables to override the corresponding default entries in
+     the src/Configuration.tmpl file (see there for more information about
+     their usage).
+
+     Use the --prefix=PREFIX and --exec-prefix=EPREFIX options to configure
+     Apache to use a particular installation prefix. The default is
+     PREFIX=/usr/local/apache and EPREFIX=PREFIX.
+
+     Use the --bindir=DIR, --sbindir=DIR, --libexecdir=DIR, --mandir=DIR,
+     --sysconfdir=DIR, --datadir=DIR, --includedir=DIR, --localstatedir=DIR,
+     --runtimedir=DIR, --logfiledir=DIR and proxycachedir=DIR option to change
+     the paths for particular subdirectories of the installation tree.
+     Defaults are bindir=EPREFIX/bin, sbindir=EPREFIX/sbin,
+     libexecdir=EPREFIX/libexec, mandir=PREFIX/man, sysconfdir=PREFIX/etc,
+     datadir=PREFIX/share, includedir=PREFIX/include,
+     localstatedir=PREFIX/var, runtimedir=PREFIX/var/run,
+     logfiledir=PREFIX/var/log and proxycachedir=PREFIX/var/proxy.
+
+         Note: To reduce the pollution of shared installation locations
+               (like /usr/local/ or /etc) with Apache files to a minimum the
+               string ``/apache'' is automatically appended to 'libexecdir',
+               'sysconfdir', 'datadir', 'localstatedir' and 'includedir' if
+               (and only if) the following points apply for each path
+               individually:
+
+                   1. the path doesn't already contain the word ``apache''
+                   2. the path was not directly customized by the user
+
+               Keep in mind that per default these paths are derived from
+               'prefix' and 'exec-prefix', so usually its only a matter
+               whether these paths contain ``apache'' or not. Although the
+               defaults were defined with experience in mind you always should
+               make sure the paths fit your situation by checking the finally
+               chosen paths via the --layout option.
+
+     Use the --with-layout=[F:]ID option to select a particular installation
+     path base-layout. You always _HAVE_ to select a base-layout. There are
+     currently two layouts pre-defined in the file config.layout: `Apache' for
+     the classical Apache path layout and `GNU' for a path layout conforming
+     to the GNU `standards' document. When you want to use your own custom
+     layout FOO, either add a corresponding "<Layout FOO>...</Layout>" section
+     to config.layout and use --with-layout=FOO or place it into your own
+     file, say config.mypaths, and use --with-layout=config.mypaths:FOO.
+ 
+     Use the --show-layout option to check the final installation path layout
+     while fiddling with the options above.
+ 
+     Use the --enable-rule=NAME and --disable-rule=NAME options to enable or
+     disable a particular Rule from the Apache src/Configuration.tmpl file. The
+     defaults (yes=enabled, no=disabled) can either be seen when running
+     `./configure --help' or manually looked up in the src/Configuration.tmpl
+     file.
+ 
+     Use the --enable-NAME=(shared) and --disable-NAME options to enable
+     or disable a particular already distributed module from the Apache
+     package.
+
+     Use the --with-mpm=NAME option to determine which MPM should be built
+     for your server.
+     _________________________________________________________________________
+     LIST OF AVAILABLE MODULES
+
+     Environment creation
+      (+) mod_env .......... Set environment variables for CGI/SSI scripts
+      (+) mod_setenvif ..... Set environment variables based on HTTP headers
+      (-) mod_unique_id .... Generate unique identifiers for request
+     Content type decisions
+      (+) mod_mime ......... Content type/encoding determination (configured)
+      (-) mod_mime_magic ... Content type/encoding determination (automatic)
+      (+) mod_negotiation .. Content selection based on the HTTP Accept* headers
+     URL mapping
+      (+) mod_alias ........ Simple   URL translation and redirection
+      (-) mod_rewrite ...... Advanced URL translation and redirection
+      (+) mod_userdir ...... Selection of resource directories by username
+      (-) mod_speling ...... Correction of misspelled URLs
+     Directory Handling
+      (+) mod_dir .......... Directory and directory default file handling
+      (+) mod_autoindex .... Automated directory index file generation
+     Access Control
+      (+) mod_access ....... Access Control (user, host, network)
+      (+) mod_auth ......... HTTP Basic Authentication (user, passwd)
+      (-) mod_auth_dbm ..... HTTP Basic Authentication via Unix NDBM files
+      (-) mod_auth_db ...... HTTP Basic Authentication via Berkeley-DB files
+      (-) mod_auth_anon .... HTTP Basic Authentication for Anonymous-style users
+      (-) mod_digest ....... HTTP Digest Authentication
+     HTTP response
+      (-) mod_headers ...... Arbitrary HTTP response headers (configured)
+      (-) mod_cern_meta .... Arbitrary HTTP response headers (CERN-style files)
+      (-) mod_expires ...... Expires HTTP responses 
+      (+) mod_asis ......... Raw HTTP responses 
+     Scripting
+      (+) mod_include ...... Server Side Includes (SSI) support
+      (+) mod_cgi .......... Common Gateway Interface (CGI) support
+      (+) mod_cgid ......... Common Gateway Interface (CGI) support for 
+                             multi-threaded MPMs
+      (+) mod_actions ...... Map CGI scripts to act as internal `handlers'
+     Internal Content Handlers
+      (+) mod_status ....... Content handler for server run-time status
+      (-) mod_info ......... Content handler for server configuration summary
+     Request Logging
+      (+) mod_log_config ... Customizable logging of requests
+      (-) mod_log_agent .... Specialized HTTP User-Agent logging (deprecated)
+      (-) mod_log_referer .. Specialized HTTP Referrer logging   (deprecated)
+      (-) mod_usertrack .... Logging of user click-trails via HTTP Cookies
+     Miscellaneous
+      (+) mod_imap ......... Server-side Image Map support
+      (-) mod_proxy ........ Caching Proxy Module (HTTP, HTTPS, FTP)
+      (-) mod_so ........... Dynamic Shared Object (DSO) bootstrapping
+     Experimental
+      (-) mod_mmap_static .. Caching of frequently served pages via mmap()
+     Development
+      (-) mod_example ...... Apache API demonstration (developers only)
+
+     MPMs
+          mpmt_pthread ..... Mutli-process(dynamic) Multi-threaded(static) 
+                             Unix MPM
+          prefork .......... Preforking Unix MPM
+          dexter ........... Multi-process(static) Multi-threaded(dynamic)
+                             Unix MPM
+          perchild ......... Multi-process(static) Multi-threaded(dynamic)
+                             Unix MPM, that allows a User per child process
+
+          winnt ............ Multi-process(1) Multi-threaded Windows MPM
+
+          mpmt_beos ........ Multi-process Multi-threaded Beos MPM
+          beos ............. Multi-process Multi-threaded Beos MPM
+
+          spmt_os2 ......... Single-process Multi-threaded OS/2 MPM
+     _________________________________________________________________________
+                    (+) = enabled  per default [disable with --disable-module]
+                    (-) = disabled per default [enable  with --enable-module ]
+
+     Use the --enable-suexec option to enable the suEXEC feature by building
+     and installing the "suexec" support program. Use --suexec-caller=UID to
+     set the allowed caller user id, --suexec-userdir=DIR to set the user
+     subdirectory, --suexec-docroot=DIR to set the suexec root directory,
+     --suexec-uidmin=UID/--suexec-gidmin=GID to set the minimal allowed
+     UID/GID, --suexec-logfile=FILE to set the logfile and
+     --suexec-safepath=PATH to set the safe shell PATH for the suEXEC
+     feature. At least one --suexec-xxxxx option has to be provided together
+     with the --enable-suexec option to let APACI accept your request for
+     using the suEXEC feature.
+
+     CAUTION: FOR DETAILS ABOUT THE SUEXEC FEATURE WE HIGHLY RECOMMEND YOU TO
+              FIRST READ THE DOCUMENT htdocs/manual/suexec.html BEFORE USING
+              THE ABOVE OPTIONS.
+     
+              USING THE SUEXEC FEATURE PROPERLY CAN REDUCE CONSIDERABLY THE
+              SECURITY RISKS INVOLVED WITH ALLOWING USERS TO DEVELOP AND RUN
+              PRIVATE CGI OR SSI PROGRAMS. HOWEVER, IF SUEXEC IS IMPROPERLY
+              CONFIGURED, IT CAN CAUSE ANY NUMBER OF PROBLEMS AND POSSIBLY
+              CREATE NEW HOLES IN YOUR COMPUTER'S SECURITY.  IF YOU AREN'T
+              FAMILIAR WITH MANAGING SETUID ROOT PROGRAMS AND THE SECURITY
+              ISSUES THEY PRESENT, WE HIGHLY RECOMMEND THAT YOU NOT CONSIDER
+              USING SUEXEC AND KEEP AWAY FROM THESE OPTIONS!
+
+     Use the --shadow option to let APACI create a shadow source tree of the
+     sources for building. This is useful when you want to build for different
+     platforms in parallel (usually through a NFS, AFS or DFS mounted
+     filesystem).  You may specify a directory to the --shadow option into
+     which the shadow tree will be created.
+ 
+     Use the --quiet option to disable all configuration verbose messages.
+ 
+     Use the --verbose option to enable additional verbose messages.
+     
+     Use the --server-uid option to specify the user ID you want the server to run
+     as. If not specified the server will run as user nobody.  If the user ID
+     specified is different than the ID of the user starting the server, you need to
+     start the server as root.
+
+     Use the --server-gid option to specify the group ID you want the server user ID to
+     be a member of.  If not specified, the group ID will be #-1.
+
+  4. Building the package
+     --------------------
+     
+     Now you can build the various parts which form the Apache package by
+     simply running the command
+ 
+        $ make 
+ 
+     Please be patient here, this takes approximately 2 minutes to complete
+     under a Pentium-166/FreeBSD-2.2 system, dependend on the amount of
+     modules you have enabled. 
+ 
+  5. Installing the package
+     ----------------------
+     
+     Now its time to install the package under the configured installation
+     PREFIX (see --prefix option above) by running:
+ 
+        $ make install
+ 
+     For the paranoid hackers under us: The above command really installs under
+     prefix _only_, i.e. no other stuff from your system is touched. Even if
+     you upgrade an existing installation your configuration files in
+     PREFIX/etc/ are preserved.
+
+  6. Testing the package
+     -------------------
+ 
+     Now you can fire up your Apache HTTP server by immediately running
+ 
+        $ PREFIX/bin/apachectl start
+ 
+     and then you should be able to request your first document via URL
+     http://localhost/ (when you built and installed Apache as root or at
+     least used the --without-confadjust option) or http://localhost:8080/
+     (when you built and installed Apache as a regular user). Then stop the
+     server again by running: 
+
+        $ PREFIX/bin/apachectl stop
+ 
+  7. Customizing the package
+     -----------------------
+ 
+     Finally you can customize your Apache HTTP server by editing the
+     configuration files under PREFIX/etc/.
+ 
+        $ vi PREFIX/etc/httpd.conf
+        $ vi PREFIX/etc/access.conf
+        $ vi PREFIX/etc/srm.conf
+ 
+     Have a look at the Apache manual under htdocs/manual/ or
+     http://www.apache.org/docs/ for a complete reference of available
+     configuration directives.
+
+  8. Preparing the system
+     --------------------
+
+     Proper operation of a public HTTP server requires at least the following:
+
+     1. A correctly working TCP/IP layer, since HTTP is implemented on top of
+        TCP/IP. Although modern Unix platforms have good networking layers,
+        always make sure you have all official vendor patches referring to the
+        network layer applied.
+
+     2. Accurate time keeping, since elements of the HTTP protocol are
+        expressed as the time of day.  So, it's time to investigate setting
+        some time synchronization facility on your system. Usually the ntpdate
+        or xntpd programs are used for this purpose which are based on the
+        Network Time Protocol (NTP). See the Usenet newsgroup
+        comp.protocols.time.ntp and the NTP homepage at
+        http://www.eecis.udel.edu/~ntp/ for more details about NTP software
+        and public time servers.
+
+  9. Contacts
+     --------
+
+     o If you want to be informed about new code releases, bug fixes, 
+       security fixes, general news and information about the Apache server
+       subscribe to the apache-announce mailing list as described under
+       http://www.apache.org/announcelist.html
+
+     o If you want freely available support for running Apache please join the
+       Apache user community by subscribing at least to the following USENET
+       newsgroup:
+       comp.infosystems.www.servers.unix
+
+     o If you want commercial support for running Apache please contact
+       one of the companies and contractors which are listed at
+       http://www.apache.org/info/support.cgi
+
+     o If you have a concrete bug report for Apache please go to the
+       Apache Group Bug Database and submit your report:
+       http://www.apache.org/bug_report.html
+
+     o If you want to participate in actively developing Apache please
+       subscribe to the `new-httpd' mailing list as described at
+       http://dev.apache.org/mailing-lists
+
+     Thanks for running Apache.
+                                          The Apache Group
+                                          http://www.apache.org/
+