From 09e418581e2f918feb23c75a2061b48f922d8edf Mon Sep 17 00:00:00 2001 From: Cliff Woolley Date: Sun, 20 May 2001 02:04:55 +0000 Subject: Make INSTALL just be a terse quick-start guide. The full installation documentation is now in install.html. Submitted by: Joshua Slive Reviewed by: Cliff Woolley git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89169 13f79535-47bb-0310-9956-ffa450edef68 --- INSTALL | 477 ++++------------------------------------------------------------ 1 file changed, 29 insertions(+), 448 deletions(-) (limited to 'INSTALL') diff --git a/INSTALL b/INSTALL index ced2c73298..14ff4970e4 100644 --- a/INSTALL +++ b/INSTALL @@ -1,466 +1,47 @@ - APACHE INSTALLATION + APACHE INSTALLATION OVERVIEW - Introduction - ============ + For complete installation documentation, see docs/manual/install.html or + http://httpd.apache.org/docs-2.0/install.html - 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 2.0 HTTP server - ===================================== - - 1. Overview for the impatient - -------------------------- + Quick Start + ----------- $ ./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. - - NOTE: if you are building from a copy of the Apache CVS - repository, rather than a release distribution, then you - must use the "buildconf" script before running configure. - - NOTE: If you are building on FreeBSD, you should add the argument - --with-mpm=prefork to the configure line. The Apache Group - has discovered that threads do not work well with Apache - on FreeBSD. For that reason, we disable threads by default - on FreeBSD, and you need to build the prefork MPM. If you wish - to try to make threads work on FreeBSD, they can be re-enabled - by using --enable-threads - - 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 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 the `configure' script this is no harm. Of - course, you still can build and install Apache 2.0. 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 ./configure. - - 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 apr_dso_open()/apr_dso_sym() calls. These calls - are not available under all operating systems therefore you - cannot use the DSO mechanism on all platforms. Apache relies - on autoconf to detect the ability to use DSOs, and libtool to - determine how to build DSOs. If your platform is supported by - libtool, and we can find DSO system calls, then DSOs should - work out-of-the-box. - - 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 manually or at least make sure a Perl 5 - interpreter is installed from which Apache can guess the options. - - - If you are building from a copy of the CVS repository, rather - than a release distribution, then you will need these additional - tools: - - 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. + NOTES: * Replace PREFIX with the filesystem path under which + Apache should be installed. A typical installation + might use "/usr/local/apache" for PREFIX (without the + quotes). - o Autoconf 2.13: + * If you are building on FreeBSD, be aware that threads will + be disabled and the prefork MPM will be used by default, + as threads do not work well with Apache on FreeBSD. If + you wish to try a threaded Apache on FreeBSD anyway, use + "./configure --enable-threads". - 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. + * If you are a developer building Apache directly from CVS, + you will need to run ./buildconf before running configure. - - 3. Configuring the source tree - --------------------------- - - Setup: - - If you have downloading the Apache 2.0 from the CVS, rather than - a release distribution, then you will need to prepare the source - tree for configuration and compilation. 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: + For a short impression of what possibilities you have, here is a + typical example which configures 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" CFLAGS="-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=...] [TARGET=...] - [CPPFLAGS=...] [NOTEST_CPPFLAGS=...] - [CFLAGS=...] [NOTEST_CFLAGS=...] - [CXXFLAGS=...] [NOTEST_CXXFLAGS=...] - [LDFLAGS=...] [NOTEST_LDFLAGS=...] - [LIBS=...] [NOTEST_LIBS=...] - [INCLUDES=...] [SHLIB_PATH=...] - - ./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] - [--server-gid=GID] - - [--enable-maintainter-mode] - [--enable-debug] - - Use the CC, CPPFLAGS, CFLAGS, CXXFLAGS, LDFLAGS, LIBS, INCLUDES, - SHLIB_PATH and TARGET environment variables to override or expand the - corresponding default entries as determined by configure. - - Use NOTEST_CPPFLAGS, NOTEST_CFLAGS, NOTEST_CXXFLAGS, NOTEST_LDFLAGS, - and NOTEST_LIBS to add entries that should only be used during - the actual build and compilation of Apache, such as -Werror. - - 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, --iconsdir=DIR, - --htdocsdir=DIR, --cgidir=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/bin, - libexecdir=EPREFIX/modules, mandir=PREFIX/man, - sysconfdir=PREFIX/conf, datadir=PREFIX, iconsdir=PREFIX/icons, - htdocsdir=PREFIX/htdocs, cgidir=PREFIX/cgi-bin, - includedir=PREFIX/include, localstatedir=PREFIX, - runtimedir=PREFIX/logs, logfiledir=PREFIX/logs and - proxycachedir=PREFIX/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 "..." 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-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 and Authentication - (+) 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_usertrack .... Logging of user click-trails via HTTP Cookies - - Content Management - (-) mod_dav .......... WebDAV (RFC 2518) support for Apache - (-) mod_dav_fs ....... mod_dav backend to managing filesystem content - - 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 ..... Multi-process(dynamic) Multi-threaded(static) - Unix MPM - prefork .......... Preforking 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. - - 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 --quiet option to disable all configuration verbose - messages. - - - 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/conf/ 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/conf/. - - $ vi PREFIX/conf/httpd.conf - - Have a look at the Apache manual under docs/manual/ or - http://httpd.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://httpd.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://httpd.apache.org/info/support.cgi + ./configure --prefix=/sw/pkg/apache \ + --enable-rewrite=shared \ + --enable-speling=shared - o If you have a concrete bug report for Apache please go to the - Apache Group Bug Database and submit your report: - http://httpd.apache.org/bug_report.html + The easiest way to find all of the configuration flags for Apache 2.0 + is to run ./configure --help. - o If you want to participate in actively developing Apache please - subscribe to the `new-httpd' mailing list as described at - http://www.apache.org/foundation/mailinglists.html + Thanks for using the Apache HTTP Server, version 2.0. - Thanks for running Apache httpd. + The Apache Software Foundation + http://www.apache.org/ - The Apache Group - http://www.apache.org/ -- cgit v1.2.1