granicus.if.org Git - apache/blob - docs/manual/install.html.en

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Compiling and Installing Apache</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16
  17 <H1 ALIGN="CENTER">Compiling and Installing</H1>
  18
  19
  20 <p>This document covers compilation and installation of Apache on Unix
  21 and Unix-like systems only. For compiling and installation on Windows,
  22 see <A HREF="platform/windows.html">Using Apache with Microsoft
  23 Windows</A>.  For other platforms, see the <a
  24 href="platform/">platform</a> documentation.</p>
  25
  26 <p>Apache 2.0's configuration and installation environment has changed
  27 completely from Apache 1.3.  Apache 1.3 used a custom set of scripts
  28 to achieve easy installation.  Apache 2.0 now uses libtool and
  29 autoconf to create an environment that looks like many other Open
  30 Source projects.</p>
  31
  32 <ul>
  33 <li><a href="#overview">Overview for the impatient</a></li>
  34 <li><a href="#requirements">Requirements</a></li>
  35 <li><a href="#download">Download</a></li>
  36 <li><a href="#extract">Extract</a></li>
  37 <li><a href="#configure">Configuring the source tree</a>
  38   <ul>
  39   <li><a href="#environment">Environment Variables</a></li>
  40   <li><a href="#output">autoconf Output Options</a></li>
  41   <li><a href="#pathnames">Pathnames</a></li>
  42   <li><a href="#modules">Modules</a></li>
  43   <li><a href="#suexec">Suexec</a></li>
  44   </ul></li>
  45 <li><a href="#compile">Build</a></li>
  46 <li><a href="#install">Install</a></li>
  47 <li><a href="#customize">Customize</a></li>
  48 <li><a href="#test">Test</a></li>
  49 </ul>
  50
  51 <hr>
  52
  53 <h3><a name="overview">Overview for the impatient</a></h3>
  54
  55 <table>
  56 <tr><td><a href="#download">Download</a></td>
  57 <td><code>$ lynx http://www.apache.org/dist/httpd/httpd-2_0_<em>NN</em>.tar.gz
  58 </code></td></tr>
  59
  60 <tr><td><a href="#extract">Extract</a></td>
  61 <td><code>$ gzip -d httpd-2_0_<em>NN</em>.tar.gz<br>
  62 $ tar xvf httpd-2_0_<em>NN</em>.tar
  63 </code></td></tr>
  64
  65 <tr><td><a href="#configure">Configure</a></td>
  66 <td><code>$ ./configure --prefix=<em>PREFIX</em>
  67 </code></td></tr>
  68
  69 <tr><td><a href="#compile">Compile</a></td>
  70 <td><code>$ make
  71 </code></td></tr>
  72
  73 <tr><td><a href="#install">Install</a></td>
  74 <td><code>$ make install
  75 </code></td></tr>
  76
  77 <tr><td><a href="#customize">Customize</a></td>
  78 <td><code>$ vi <em>PREFIX</em>/conf/httpd.conf
  79 </code></td></tr>
  80
  81 <tr><td><a href="#test">Test</a></td>
  82 <td><code>$ <em>PREFIX</em>/bin/apachectl start
  83 </code></td></tr>
  84
  85 </table>
  86
  87 <p><em>NN</em> must be replaced with the current minor version number,
  88 and <em>PREFIX</em> must be replaced with the filesystem path under
  89 which the server should be installed.  If <em>PREFIX</em> is not
  90 specified, it defaults to <code>/usr/local/apache2</code>.</p>
  91
  92 <p>Each section of the compilation and installation process is
  93 described in more detail below, beginning with the requirements
  94 for compiling and installing Apache HTTPD.</p>
  95
  96 <h3><a name="requirements">Requirements</a></h3>
  97
  98 <p>The following requirements exist for building Apache:</p>
  99
 100 <ul>
 101
 102 <li>Disk Space<br><br> Make sure you have at least 50 MB of temporary
 103 free disk space available.  After installation Apache occupies
 104 approximately 10 MB of disk space.  The actual disk space requirements
 105 will vary considerably based on your chosen configuration options and
 106 any third-party modules.<br><br></li>
 107
 108 <li>ANSI-C Compiler and Build System<br><br> Make sure you have an
 109 ANSI-C compiler installed. The <a
 110 href="http://www.gnu.org/software/gcc/gcc.html">GNU C compiler
 111 (GCC)</a> from the <a href="http://www.gnu.org/">Free Software
 112 Foundation (FSF)</a> is recommended (version 2.7.2 is fine). If you
 113 don't have GCC then at least make sure your vendor's compiler is ANSI
 114 compliant.  In addition, your <code>PATH</code> must contain basic
 115 build tools such as <code>make</code>.<br><br></li>
 116
 117 <li>Accurate time keeping<br><br> Elements of the HTTP protocol are
 118 expressed as the time of day.  So, it's time to investigate setting
 119 some time synchronization facility on your system. Usually the ntpdate
 120 or xntpd programs are used for this purpose which are based on the
 121 Network Time Protocol (NTP). See the Usenet newsgroup <a
 122 href="news:comp.protocols.time.ntp">comp.protocols.time.ntp</a> and
 123 the <a href="http://www.eecis.udel.edu/~ntp/">NTP homepage</a> for more
 124 details about NTP software and public time servers.<br><br></li>
 125
 126 <li><a href="http://www.perl.org/">Perl 5</a> [OPTIONAL]<br><br> For
 127 some of the support scripts like <a href="programs/apxs.html">apxs</a>
 128 or <a href="programs/dbmmanage.html">dbmmanage</a> (which are written
 129 in Perl) the Perl 5 interpreter is required (versions 5.003 and 5.004
 130 are fine). If no such interpreter is found by the `configure' script
 131 there is no harm.  Of course, you still can build and install Apache
 132 2.0. Only those support scripts cannot be used. If you have multiple
 133 Perl interpreters installed (perhaps a Perl 4 from the vendor and a
 134 Perl 5 from your own), then it is recommended to use the --with-perl
 135 option (see below) to make sure the correct one is selected by
 136 ./configure.  <br><br></li>
 137
 138 </ul>
 139
 140 <h3><a name="download">Download</a></h3>
 141
 142 <p>Apache can be downloaded from the <a
 143 href="http://www.apache.org/dist/httpd/">Apache Software Foundation
 144 download site</a> or from a <a
 145 href="http://www.apache.org/dyn/closer.cgi">nearby mirror</a>.</p>
 146
 147 <p>Version numbers that end in <code>alpha</code> indicate early
 148 pre-test versions which may or may not work.  Version numbers ending
 149 in <code>beta</code> indicate more reliable releases that still
 150 require further testing or bug fixing.  If you wish to download the
 151 best available production release of the Apache HTTP Server, you
 152 should choose the latest version with neither <code>alpha</code> nor
 153 <code>beta</code> in its filename.</p>
 154
 155 <p>After downloading, especially if a mirror site is used, it is
 156 important to verify that you have a complete and unmodified version of
 157 the Apache HTTP Server.  This can be accomplished by testing the
 158 downloaded tarball against the PGP signature.  This, in turn, is a two
 159 step procedure.  First, you must obtain the <code>KEYS</code> file
 160 from the <a href="http://www.apache.org/dist/">Apache distribution
 161 site</a>.  (To assure that the <code>KEYS</code> file itself has not
 162 been modified, it may be a good idea to use a file from a previous
 163 distribution of Apache or import the keys from a public key server.)
 164 The keys are imported into your personal key ring using
 165 one of the following commands (depending on your pgp version):</p>
 166 <blockquote><code>
 167 $ pgp < KEYS
 168 </code></blockquote>
 169 or
 170 <blockquote><code>
 171 $ gpg --import KEYS
 172 </code></blockquote>
 173
 174 <p>The next step is to test the tarball against the PGP signature,
 175 which should always be obtained from the <a
 176 href="http://www.apache.org/dist/httpd">main Apache website</a>.  The
 177 signature file has a filename identical to the source tarball with the
 178 addition of <code>.asc</code>.  Then you can check the distribution
 179 with one of the following commands (again, depending on your pgp
 180 version):</p>
 181 <blockquote><code>
 182 $ pgp httpd-2_0_<em>NN</em>.tar.gz.asc
 183 </code></blockquote>
 184 or
 185 <blockquote><code>
 186 $ gpg --verify httpd-2_0_<em>NN</em>.tar.gz.asc
 187 </code></blockquote
 188
 189 <p>You should receive a message like</p>
 190 <blockquote><code>
 191 Good signature from user "Martin Kraemer &lt;martin@apache.org&gt;".
 192 </code></blockquote>
 193 <p>Depending on the trust relationships contained
 194 in your key ring, you may also receive a message saying that
 195 the relationship between the key and the signer of the key
 196 cannot be verified.  This is not a problem if you trust the
 197 authenticity of the <code>KEYS</code> file.</p>
 198
 199 <h3><a name="extract">Extract</a></h3>
 200
 201 <p>Extracting the source from the Apache HTTPD tarball is a simple
 202 matter of uncompressing, and then untarring:</p>
 203
 204 <blockquote><code>
 205 $ gzip -d httpd-2_0_<em>NN</em>.tar.gz<br>
 206 $ tar xvf httpd-2_0_<em>NN</em>.tar
 207 </code></blockquote>
 208
 209 <p>This will create a new directory under the current directory
 210 containing the source code for the distribution.  You should
 211 <code>cd</code> into that directory before proceeding with
 212 compiling the server.</p>
 213
 214 <h3><a name="configure">Configuring the source tree</a></h3>
 215
 216 <p>The next step is to configure the Apache source tree for your
 217 particular platform and personal requirements. This is done using the
 218 script <code>configure</code> included in the root directory of the
 219 distribution.  (Developers downloading the CVS version of the Apache
 220 source tree will need to have <code>autoconf</code> and
 221 <code>libtool</code> installed and will need to run
 222 <code>buildconf</code> before proceeding with the next steps.  This is
 223 not necessary for official releases.)</p>
 224
 225 <p>To configure the source tree using all the default options, simply
 226 type <code>./configure</code>.  To change the default options,
 227 <code>configure</code> accepts a variety of variables and command line
 228 options.  Environment variables are generally placed before the
 229 <code>./configure</code> command, while other options are placed
 230 after.  The most important option here is the location prefix where
 231 Apache is to be installed later, because Apache has to be configured
 232 for this location to work correctly. But there are a lot of other
 233 options available for your pleasure.</p>
 234
 235 <p>For a short impression of what possibilities you have, here is a
 236 typical example which compiles Apache for the installation tree
 237 /sw/pkg/apache with a particular compiler and flags plus the two
 238 additional modules mod_rewrite and mod_speling for later loading
 239 through the DSO mechanism:</p>
 240
 241 <blockquote><code>
 242      $ CC="pgcc" CFLAGS="-O2" \<br>
 243        ./configure --prefix=/sw/pkg/apache \<br>
 244                    --enable-rewrite=shared \<br>
 245                    --enable-speling=shared
 246 </code></blockquote>
 247
 248 <p>When configure is run it will take several minutes to test for
 249 the availability of features on your system and build Makefiles
 250 which will later be used to compile the server.</p>
 251
 252 <p>The easiest way to find all of the configuration flags for Apache
 253 is to run ./configure --help.  What follows is a brief description
 254 of most of the arguments and environment variables.</p>
 255
 256 <h4><a name="environment">Environment Variables</a></h4>
 257
 258 <p>The autoconf build process uses several environment variables to
 259 configure the build environment.  In general, these variables change
 260 the method used to build Apache, but not the eventual features of the
 261 server.  These variables can be placed in the environment before
 262 invoking <code>configure</code>, but it is usually easier to specify
 263 them on the <code>configure</code> command line as demonstrated
 264 in the example above.</p>
 265
 266 <dl>
 267
 268 <dt><code>CC=...</code></dt>
 269 <dd>The name of the C compiler command.</dd>
 270
 271 <dt><code>CPPFLAGS=...</code></dt> <dd>Miscellaneous C preprocessor
 272 and compiler options.</dd>
 273
 274 <dt><code>CFLAGS=...</code></dt>
 275 <dd>Debugging and optimization options for the C compiler.</dd>
 276
 277 <dt><code>LDFLAGS=...</code></dt>
 278 <dd>Miscellaneous options to be passed to the linker.</dd>
 279
 280 <dt><code>LIBS=...</code></dt>
 281 <dd>Library location information ("-L" and "-l" options)
 282 to pass to the linker.</dd>
 283
 284 <dt><code>INCLUDES=...</code></dt>
 285 <dd>Header file search directories ("-I<em>dir</em>").</dd>
 286
 287 <dt><code>TARGET=...</code> [Default: apache]</dt>
 288 <dd>Name of the executable which will be built.</dd>
 289
 290 <dt><code>NOTEST_CPPFLAGS=...</code></dt>
 291 <dt><code>NOTEST_CFLAGS=...</code></dt>
 292 <dt><code>NOTEST_LDFLAGS=...</code></dt>
 293 <dt><code>NOTEST_LIBS=...</code></dt>
 294 <dd>These variables share the same function as their non-NOTEST namesakes.
 295 However, the variables are applied to the build process only after
 296 autoconf has performed its feature testing.  This allows the inclusion of
 297 flags which will cause problems during feature testing, but must be used
 298 for the final compilation.</dd>
 299
 300 <dt><code>SHLIB_PATH=...</code></dt>
 301 <dd>Options which specify shared library paths for the compiler and
 302 linker.</dd>
 303
 304 </dl>
 305
 306 <h4><a name="output">autoconf Output Options</a></h4>
 307
 308 <dl>
 309
 310 <dt><code>--help</code></dt>
 311 <dd>Prints the usage message including all available options, but
 312 does not actually configure anything.</dd>
 313
 314 <dt><code>--quiet</code></dt>
 315 <dd>Prevents the printing of the usual "checking..." messages.</dd>
 316
 317 <dt><code>--verbose</code></dt>
 318 <dd>Prints much more information during the configuration process,
 319 including the names of all the files examined.</dd>
 320
 321 </dl>
 322
 323 <h4><a name="pathnames">Pathnames</a></h4>
 324
 325 <p>There are currently two ways to configure the pathnames under
 326 which Apache will install its files.  First, you can specify
 327 a directory and have Apache install itself under that directory
 328 in its default locations.</p>
 329
 330 <dl>
 331 <dt><code>--prefix=<em>PREFIX</em></code> [Default:
 332 /usr/local/apache2]</dt>
 333 <dd>Specifies the directory under which the Apache files will be
 334 installed.</dd>
 335 </dl>
 336
 337 <p>It is possible to specify that architecture-dependent files should
 338 be placed under a different directory.</p>
 339
 340 <dl>
 341 <dt><code>--exec-prefix=<em>EPREFIX</em></code> [Default:
 342 <em>PREFIX</em>]</dt>
 343 <dd>Specifies the directory under which architecture-dependent files
 344 will be placed.</dd>
 345 </dl>
 346
 347 <p>The second, and more flexible way to configure the install path
 348 locations for Apache is using the <code>config.layout</code> file.
 349 Using this method, it is possible to separately specify the location
 350 for each type of file within the Apache installation.  The
 351 <code>config.layout</code> file contains several example
 352 configurations, and you can also create your own custom configuration
 353 following the examples.  The different layouts in this file are
 354 grouped into <code>&lt;Layout FOO&gt;...&lt;/Layout&gt;</code>
 355 sections and referred to by name as in <code>FOO</code>.</p>
 356
 357 <dl>
 358
 359 <dt><code>--enable-layout=<em>LAYOUT</em></code></dt>
 360 <dd>Use the named layout in the <code>config.layout</code> file
 361 to specify the installation paths.</dd>
 362
 363 </dl>
 364
 365 <p>Presently it is not possible to mix the
 366 <code>--enable-layout</code> and <code>--prefix</code> options.  Nor
 367 is it possible to individually specify detailed pathnames on the
 368 <code>configure</code> command line.  If you want just a basic
 369 install, you can simply use the <code>--prefix</code> option on its
 370 own.  If you want to customize your install, you should edit the
 371 <code>config.layout</code> file and use the
 372 <code>--enable-layout</code> option.</p>
 373
 374 <h4><a name="modules">Modules</a></h4>
 375
 376 <p>Apache is a modular server.  Only the most basic functionality is
 377 included in the core server.  Extended features are available in
 378 various modules.  During the configuration process, you must select
 379 which modules to compile for use with your server.  You can view a <a
 380 href="mod/index-bytype.html">list of modules</a> included in the
 381 documentation.  Those modules with a <a
 382 href="mod/module-dict.html#Status">status</a>
 383 of "Base" are included by default and must be specifically disabled if
 384 you do not want them.  Modules with any other status must be
 385 specifically enabled if you wish to use them.</p>
 386
 387 <p>There are two ways for a module to be compiled and used with
 388 Apache.  Modules may be <em>statically compiled</em>, which means that
 389 they are permanently included in the Apache binary.  Alternatively, if
 390 your operating system supports Dynamic Shared Objects (DSOs) and
 391 autoconf can detect that support, then modules may be <em>dynamically
 392 compiled</em>.  DSO modules are stored separately from the Apache
 393 binary, and may be included or excluded from the server using the
 394 run-time configuration directives provided by <a
 395 href="mod/mod_so.html">mod_so</a>.  The mod_so is automatically
 396 included in the server if any dynamic modules are included in the
 397 compilation.  If you would like to make your server capable of loading
 398 DSOs without actually compiling any dynamic modules, you can
 399 explicitly <code>--enable-so</code>.</p>
 400
 401 <dl>
 402
 403 <dt><code>--enable-<em>MODULE</em>[=shared]</code></dt> <dd>Compile
 404 and include the module <em>MODULE</em>.  The identifier
 405 <em>MODULE</em> is the <a
 406 href="mod/module-dict.html#ModuleIdentifier"
 407 >Module Identifier</a> from the module documentation without the
 408 "_module" string.  To compile the module as a DSO, add the
 409 option <code>=shared</code>.</dd>
 410
 411 <dt><code>--disable-<em>MODULE</em></code></dt>
 412 <dd>Remove the module <em>MODULE</em> which would otherwise be
 413 compiled and included.</dd>
 414
 415 <dt><code>--enable-modules=<em>MODULE-LIST</em></code> <dd>Compile and
 416 include the modules listed in the space-separated
 417 <em>MODULE-LIST</em>.</dd>
 418
 419 <dt><code>--enable-mods-shared=<em>MODULE-LIST</em></code> <dd>Compile
 420 and include the modules in the space-separated <em>MODULE-LIST</em> as
 421 dynamically loadable (DSO) modules.</dd>
 422
 423 </dl>
 424
 425 <p>The <em>MODULE-LIST</em> in the <code>--enable-modules</code> and
 426 <code>--enable-mods-shared</code> options is usually a space-separated list
 427 of module identifiers.  For example, to enable mod_dav and mod_info, you
 428 can either use</p>
 429 <blockquote><code>
 430 ./configure --enable-dav --enable-info
 431 </code></blockquote>
 432 <p>or, equivalently,</p>
 433 <blockquote><code>
 434 ./configure --enable-modules="dav info"
 435 </code></blockquote>
 436 <p>In addition, the special keywords <code>all</code>
 437 or <code>most</code> can be used to add all or most of the modules
 438 in one step.  You can then remove any modules that you do not want
 439 with the <code>--disable-<em>MODULE</em></code> option.  For example,
 440 to include all modules as DSOs with the exception of mod_info, you can use</p>
 441 <blockquote><code>
 442 ./configure --enable-mods-shared=all --disable-info
 443 </code></blockquote>
 444
 445 <p>In addition to the standard set of modules, Apache 2.0 also
 446 includes a choice of <a href="mpm.html">Multi-Processing Modules</a>
 447 (MPMs).  One, and only one MPM must be included in the compilation
 448 process.  The default MPMs for each platform are listed on the <a
 449 href="mpm.html">MPM documentation page</a>, but can be overridden
 450 on the <code>configure</code> command line.
 451
 452 <dl>
 453
 454 <dt><code>--with-mpm=<em>NAME</em></code></dt>
 455 <dd>Choose the mpm <em>NAME</em>.
 456
 457 </dl>
 458
 459 <h4><a name="suexec">Suexec</a></h4>
 460
 461 <p>Apache includes a support program called <a
 462 href="suexec.html">suexec</a> which can be used to isolate user CGI
 463 programs.  However, if suexec is improperly configured, it can cause
 464 serious security problems.  Therefore, you should carefully read and
 465 consider the <a href="suexec.html">suexec documentation</a> before
 466 implementing this feature.</p>
 467
 468
 469 <h3><a name="compile">Build</a></h3>
 470
 471 <p>Now you can build the various parts which form the Apache package
 472 by simply running the command:</p>
 473
 474 <blockquote><code>
 475         $ make
 476 </code></blockquote>
 477
 478 <p>Please be patient here, since a base configuration takes
 479 approximately 3 minutes to compile under a Pentium III/Linux 2.2
 480 system, but this will vary widely depending on your hardware and the
 481 number of modules which you have enabled.</p>
 482
 483
 484 <h3><a name="install">Install</a></h3>
 485
 486 <p>Now its time to install the package under the configured
 487 installation <em>PREFIX</em> (see <code>--prefix</code> option above)
 488 by running:</h3> <blockquote><code> $ make install
 489 </code></blockquote>
 490
 491 <p>If you are upgrading, the installation will not overwrite
 492 your configuration files or documents.</p>
 493
 494
 495 <h3><a name="customize">Customize</a></h3>
 496
 497 <p>Next, you can customize your Apache HTTP server by editing the <a
 498 href="configuring.html">configuration files</a> under
 499 <em>PREFIX</em>/conf/.</p>
 500
 501 <blockquote><code>
 502 $ vi <em>PREFIX</em>/conf/httpd.conf
 503 </code></blockquote>
 504
 505 <p>Have a look at the Apache manual under <a
 506 href="./">docs/manual/</a> or <a
 507 href="http://httpd.apache.org/docs/">http://httpd.apache.org/docs/</a>
 508 for a complete reference of available <a
 509 href="mod/directives.html">configuration directives</a>.</p>
 510
 511 <h3><a name="test">Test</a></h3>
 512
 513 <p>Now you can <a href="invoking.html">start</a> your Apache HTTP
 514 server by immediately running:</p>
 515
 516 <blockquote><code>
 517         $ <em>PREFIX</em>/bin/apachectl start
 518 </code></blockquote>
 519
 520 <p>and then you should be able to request your first document via URL
 521 http://localhost/.  The web page you see is located under the <a
 522 href="mod/core.html#documentroot">DocumentRoot</a> which will usually
 523 be <code><em>PREFIX</em>/htdocs/</code>.  Then <a
 524 href="stopping.html">stop</a> the server again by running:</p>
 525
 526 <blockquote><code> $ <em>PREFIX</em>/bin/apachectl stop
 527 </code></blockquote>
 528
 529
 530 <!--#include virtual="footer.html" -->
 531 </BODY>
 532 </HTML>