1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
5 <relativepath href="."/>
7 <title>Compiling and Installing</title>
11 <p>This document covers compilation and installation of Apache
12 on Unix and Unix-like systems only. For compiling and
13 installation on Windows, see <a
14 href="platform/windows.html">Using Apache with Microsoft
15 Windows</a>. For other platforms, see the <a
16 href="platform/">platform</a> documentation.</p>
18 <p>Apache 2.0's configuration and installation environment has
19 changed completely from Apache 1.3. Apache 1.3 used a custom
20 set of scripts to achieve easy installation. Apache 2.0 now
21 uses <code>libtool</code> and <code>autoconf</code>
22 to create an environment that looks like many other Open Source
27 <section id="overview"><title>Overview for the
32 <td><a href="#download">Download</a></td>
35 http://www.apache.org/dist/httpd/httpd-2_0_<em>NN</em>.tar.gz</code>
40 <td><a href="#extract">Extract</a></td>
42 <td><code>$ gzip -d httpd-2_0_<em>NN</em>.tar.gz<br />
43 $ tar xvf httpd-2_0_<em>NN</em>.tar</code> </td>
47 <td><a href="#configure">Configure</a></td>
49 <td><code>$ ./configure --prefix=<em>PREFIX</em></code>
54 <td><a href="#compile">Compile</a></td>
56 <td><code>$ make</code> </td>
60 <td><a href="#install">Install</a></td>
62 <td><code>$ make install</code> </td>
66 <td><a href="#customize">Customize</a></td>
68 <td><code>$ vi <em>PREFIX</em>/conf/httpd.conf</code> </td>
72 <td><a href="#test">Test</a></td>
74 <td><code>$ <em>PREFIX</em>/bin/apachectl start</code>
79 <p><em>NN</em> must be replaced with the current minor version
80 number, and <em>PREFIX</em> must be replaced with the
81 filesystem path under which the server should be installed. If
82 <em>PREFIX</em> is not specified, it defaults to
83 <code>/usr/local/apache2</code>.</p>
85 <p>Each section of the compilation and installation process is
86 described in more detail below, beginning with the requirements
87 for compiling and installing Apache HTTPD.</p>
90 <section id="requirements"><title>Requirements</title>
92 <p>The following requirements exist for building Apache:</p>
96 <dd>Make sure you have at least 50 MB of temporary free disk
97 space available. After installation Apache occupies
98 approximately 10 MB of disk space. The actual disk space
99 requirements will vary considerably based on your chosen
100 configuration options and any third-party modules.</dd>
102 <dt>ANSI-C Compiler and Build System</dt>
103 <dd>Make sure you have an ANSI-C compiler installed. The <a
104 href="http://www.gnu.org/software/gcc/gcc.html">GNU C
105 compiler (GCC)</a> from the <a
106 href="http://www.gnu.org/">Free Software Foundation (FSF)</a>
107 is recommended (version 2.7.2 is fine). If you don't have GCC
108 then at least make sure your vendor's compiler is ANSI
109 compliant. In addition, your <code>PATH</code> must contain
110 basic build tools such as <code>make</code>.</dd>
112 <dt>Accurate time keeping</dt>
113 <dd>Elements of the HTTP protocol are expressed as the time of
114 day. So, it's time to investigate setting some time
115 synchronization facility on your system. Usually the
116 <code>ntpdate</code> or <code>xntpd</code> programs are used for
117 this purpose which are based on the Network Time Protocol (NTP).
118 See the Usenet newsgroup <a
119 href="news:comp.protocols.time.ntp">comp.protocols.time.ntp</a>
120 and the <a href="http://www.eecis.udel.edu/~ntp/">NTP
121 homepage</a> for more details about NTP software and public
124 <dt><a href="http://www.perl.org/">Perl 5</a>
126 <dd>For some of the support scripts like <a
127 href="programs/apxs.html">apxs</a> or <a
128 href="programs/dbmmanage.html">dbmmanage</a> (which are
129 written in Perl) the Perl 5 interpreter is required (versions
130 5.003 or newer are sufficient). If no such interpreter is found by
131 the `<code>configure</code>' script there is no harm. Of course, you
132 still can build and install Apache 2.0. Only those support scripts
133 cannot be used. If you have multiple Perl interpreters
134 installed (perhaps a Perl 4 from the vendor and a Perl 5 from
135 your own), then it is recommended to use the <code>--with-perl</code>
136 option (see below) to make sure the correct one is selected
137 by <code>./configure</code>.</dd>
141 <section id="download"><title>Download</title>
143 <p>Apache can be downloaded from the <a
144 href="http://www.apache.org/dist/httpd/">Apache Software
145 Foundation download site</a> or from a <a
146 href="http://www.apache.org/dyn/closer.cgi/httpd/">nearby
149 <p>Version numbers that end in <code>alpha</code> indicate
150 early pre-test versions which may or may not work. Version
151 numbers ending in <code>beta</code> indicate more reliable
152 releases that still require further testing or bug fixing. If
153 you wish to download the best available production release of
154 the Apache HTTP Server, you should choose the latest version
155 with neither <code>alpha</code> nor <code>beta</code> in its
158 <p>After downloading, especially if a mirror site is used, it
159 is important to verify that you have a complete and unmodified
160 version of the Apache HTTP Server. This can be accomplished by
161 testing the downloaded tarball against the PGP signature. This,
162 in turn, is a two step procedure. First, you must obtain the
163 <code>KEYS</code> file from the <a
164 href="http://www.apache.org/dist/httpd/">Apache distribution
165 site</a>. (To assure that the <code>KEYS</code> file itself has
166 not been modified, it may be a good idea to use a file from a
167 previous distribution of Apache or import the keys from a
168 public key server.) The keys are imported into your personal
169 key ring using one of the following commands (depending on your
172 <example>$ pgp < KEYS</example>
176 <example>$ gpg --import KEYS</example>
178 <p>The next step is to test the tarball against the PGP
179 signature, which should always be obtained from the <a
180 href="http://www.apache.org/dist/httpd/">main Apache
181 website</a>. The signature file has a filename identical to the
182 source tarball with the addition of <code>.asc</code>. Then you
183 can check the distribution with one of the following commands
184 (again, depending on your pgp version):</p>
186 <example>$ pgp httpd-2_0_<em>NN</em>.tar.gz.asc</example>
190 <example>$ gpg --verify httpd-2_0_<em>NN</em>.tar.gz.asc</example>
192 <p>You should receive a message like</p>
194 <example>Good signature from user "Martin Kraemer
195 <martin@apache.org>".</example>
197 <p>Depending on the trust relationships contained in your key
198 ring, you may also receive a message saying that the
199 relationship between the key and the signer of the key cannot
200 be verified. This is not a problem if you trust the
201 authenticity of the <code>KEYS</code> file.</p>
205 <section id="extract"><title>Extract</title>
207 <p>Extracting the source from the Apache HTTPD tarball is a
208 simple matter of uncompressing, and then untarring:</p>
211 $ gzip -d httpd-2_0_<em>NN</em>.tar.gz<br />
212 $ tar xvf httpd-2_0_<em>NN</em>.tar
215 <p>This will create a new directory under the current directory
216 containing the source code for the distribution. You should
217 <code>cd</code> into that directory before proceeding with
218 compiling the server.</p>
221 <section id="configure"><title>Configuring the source tree</title>
223 <p>The next step is to configure the Apache source tree for
224 your particular platform and personal requirements. This is
225 done using the script <code>configure</code> included in the
226 root directory of the distribution. (Developers downloading the
227 CVS version of the Apache source tree will need to have
228 <code>autoconf</code> and <code>libtool</code> installed and
229 will need to run <code>buildconf</code> before proceeding with
230 the next steps. This is not necessary for official
233 <p>To configure the source tree using all the default options,
234 simply type <code>./configure</code>. To change the default
235 options, <code>configure</code> accepts a variety of variables
236 and command line options. Environment variables are generally
237 placed before the <code>./configure</code> command, while other
238 options are placed after. The most important option here is the
239 location prefix where Apache is to be installed later, because
240 Apache has to be configured for this location to work
241 correctly. But there are a lot of other options available for
244 <p>For a short impression of what possibilities you have, here
245 is a typical example which compiles Apache for the installation
246 tree <code>/sw/pkg/apache</code> with a particular compiler and flags
247 plus the two additional modules <module>mod_rewrite</module> and
248 <module>mod_speling</module> for
249 later loading through the DSO mechanism:</p>
252 $ CC="pgcc" CFLAGS="-O2" \<br />
253 ./configure --prefix=/sw/pkg/apache \<br />
254 --enable-rewrite=shared \<br />
255 --enable-speling=shared
258 <p>When <code>configure</code> is run it will take several minutes to
259 test for the availability of features on your system and build
260 Makefiles which will later be used to compile the server.</p>
262 <p>The easiest way to find all of the configuration flags for
263 Apache is to run <code>./configure --help</code>. What follows is a
264 brief description of most of the arguments and environment
267 <section id="environment"><title>Environment Variables</title>
269 <p>The <code>autoconf</code> build process uses several environment
270 variables to configure the build environment. In general, these
271 variables change the method used to build Apache, but not the
272 eventual features of the server. These variables can be placed
273 in the environment before invoking <code>configure</code>, but
274 it is usually easier to specify them on the
275 <code>configure</code> command line as demonstrated in the
279 <dt><code>CC=...</code></dt>
281 <dd>The name of the C compiler command.</dd>
283 <dt><code>CPPFLAGS=...</code></dt>
285 <dd>Miscellaneous C preprocessor and compiler options.</dd>
287 <dt><code>CFLAGS=...</code></dt>
289 <dd>Debugging and optimization options for the C
292 <dt><code>LDFLAGS=...</code></dt>
294 <dd>Miscellaneous options to be passed to the linker.</dd>
296 <dt><code>LIBS=...</code></dt>
298 <dd>Library location information ("-L" and "-l" options) to
299 pass to the linker.</dd>
301 <dt><code>INCLUDES=...</code></dt>
303 <dd>Header file search directories ("-I<em>dir</em>").</dd>
305 <dt><code>TARGET=...</code> [Default: apache]</dt>
307 <dd>Name of the executable which will be built.</dd>
309 <dt><code>NOTEST_CPPFLAGS=...</code></dt>
311 <dt><code>NOTEST_CFLAGS=...</code></dt>
313 <dt><code>NOTEST_LDFLAGS=...</code></dt>
315 <dt><code>NOTEST_LIBS=...</code></dt>
317 <dd>These variables share the same function as their
318 non-<code>NOTEST</code> namesakes. However, the variables are
319 applied to the build process only after autoconf has performed its
320 feature testing. This allows the inclusion of flags which
321 will cause problems during feature testing, but must be used
322 for the final compilation.</dd>
324 <dt><code>SHLIB_PATH=...</code></dt>
326 <dd>Options which specify shared library paths for the
327 compiler and linker.</dd>
331 <section id="output"><title>autoconf Output Options</title>
334 <dt><code>--help</code></dt>
336 <dd>Prints the usage message including all available options,
337 but does not actually configure anything.</dd>
339 <dt><code>--quiet</code></dt>
341 <dd>Prevents the printing of the usual "checking..."
344 <dt><code>--verbose</code></dt>
346 <dd>Prints much more information during the configuration
347 process, including the names of all the files examined.</dd>
351 <section id="pathnames"><title>Pathnames</title>
353 <p>There are currently two ways to configure the pathnames
354 under which Apache will install its files. First, you can
355 specify a directory and have Apache install itself under that
356 directory in its default locations.</p>
359 <dt><code>--prefix=<em>PREFIX</em></code> [Default:
360 /usr/local/apache2]</dt>
362 <dd>Specifies the directory under which the Apache files will
366 <p>It is possible to specify that architecture-dependent files
367 should be placed under a different directory.</p>
370 <dt><code>--exec-prefix=<em>EPREFIX</em></code> [Default:
371 <em>PREFIX</em>]</dt>
373 <dd>Specifies the directory under which
374 architecture-dependent files will be placed.</dd>
377 <p>The second, and more flexible way to configure the install
378 path locations for Apache is using the
379 <code>config.layout</code> file. Using this method, it is
380 possible to separately specify the location for each type of
381 file within the Apache installation. The
382 <code>config.layout</code> file contains several example
383 configurations, and you can also create your own custom
384 configuration following the examples. The different layouts in
385 this file are grouped into <code><Layout
386 FOO>...</Layout></code> sections and referred to by
387 name as in <code>FOO</code>.</p>
390 <dt><code>--enable-layout=<em>LAYOUT</em></code></dt>
392 <dd>Use the named layout in the <code>config.layout</code>
393 file to specify the installation paths.</dd>
398 <section id="modules"><title>Modules</title>
400 <p>Apache is a modular server. Only the most basic
401 functionality is included in the core server. Extended features
402 are available in various modules. During the configuration
403 process, you must select which modules to compile for use with
404 your server. You can view a <a
405 href="mod/index.html">list of modules</a> included in
406 the documentation. Those modules with a <a
407 href="mod/module-dict.html#Status">status</a> of "Base" are
408 included by default and must be specifically disabled if you do
409 not want them (e.g. <module>mod_userdir</module>). Modules with any
410 other status must be specifically enabled if you wish to use them
411 (e.g. <module>mod_expires</module>).</p>
413 <p>There are two ways for a module to be compiled and used with
414 Apache. Modules may be <em>statically compiled</em>, which
415 means that they are permanently included in the Apache binary.
416 Alternatively, if your operating system supports Dynamic Shared
417 Objects (DSOs) and <code>autoconf</code> can detect that support, then
418 modules may be <em>dynamically compiled</em>. DSO modules are
419 stored separately from the Apache binary, and may be included
420 or excluded from the server using the run-time configuration
421 directives provided by <module>mod_so</module>.
422 The mod_so is automatically included in the server if any
423 dynamic modules are included in the compilation. If you would
424 like to make your server capable of loading DSOs without
425 actually compiling any dynamic modules, you can explicitly
426 <code>--enable-so</code>.</p>
429 <dt><code>--enable-<em>MODULE</em>[=shared]</code></dt>
431 <dd>Compile and include the module <em>MODULE</em>. The
432 identifier <em>MODULE</em> is the <a
433 href="mod/module-dict.html#ModuleIdentifier">Module
434 Identifier</a> from the module documentation without the
435 "_module" string. To compile the module as a DSO, add the
436 option <code>=shared</code>.</dd>
438 <dt><code>--disable-<em>MODULE</em></code></dt>
440 <dd>Remove the module <em>MODULE</em> which would otherwise
441 be compiled and included.</dd>
443 <dt><code>--enable-modules=<em>MODULE-LIST</em></code></dt>
445 <dd>Compile and include the modules listed in the
446 space-separated <em>MODULE-LIST</em>.</dd>
449 <code>--enable-mods-shared=<em>MODULE-LIST</em></code></dt>
451 <dd>Compile and include the modules in the space-separated
452 <em>MODULE-LIST</em> as dynamically loadable (DSO)
456 <p>The <em>MODULE-LIST</em> in the
457 <code>--enable-modules</code> and
458 <code>--enable-mods-shared</code> options is usually a
459 space-separated list of module identifiers. For example, to
460 enable mod_dav and mod_info, you can either use</p>
462 <example>./configure --enable-dav --enable-info</example>
464 <p>or, equivalently,</p>
466 <example>./configure --enable-modules="dav info"</example>
468 <p>In addition, the special keywords <code>all</code> or
469 <code>most</code> can be used to add all or most of the modules
470 in one step. You can then remove any modules that you do not
471 want with the <code>--disable-<em>MODULE</em></code> option.
472 For example, to include all modules as DSOs with the exception
473 of mod_info, you can use</p>
476 ./configure --enable-mods-shared=all
480 <p>In addition to the standard set of modules, Apache 2.0 also
481 includes a choice of <a href="mpm.html">Multi-Processing
482 Modules</a> (MPMs). One, and only one MPM must be included in
483 the compilation process. The default MPMs for each platform are
484 listed on the <a href="mpm.html">MPM documentation page</a>,
485 but can be overridden on the <code>configure</code> command
489 <dt><code>--with-mpm=<em>NAME</em></code></dt>
491 <dd>Choose the mpm <em>NAME</em>.</dd>
495 <section id="dbm"><title>DBM</title>
497 <p>Several Apache features, including
498 <module>mod_auth_dbm</module> and <module>mod_rewrite</module>'s
499 DBM <directive module="mod_rewrite">RewriteMap</directive> use
500 simple key/value databases for quick lookups of information. Apache
501 includes SDBM with its source-code, so this database is always
502 available. If you would like to use other database types, the
503 following <code>configure</code> options are available:</p>
506 <dt><code>--with-gdbm[=<em>path</em>]</code></dt>
507 <dt><code>--with-ndbm[=<em>path</em>]</code></dt>
508 <dt><code>--with-berkeley-db[=<em>path</em>]</code></dt>
510 <dd>If no <em>path</em> is specified, Apache will search for the
511 include files and libraries in the usual search paths. An explict
512 <em>path</em> will cause Apache to look in
513 <em>path</em><code>/lib</code> and
514 <em>path</em><code>/include</code> for the relevant files. Finally,
515 the <em>path</em> may specify specific include and library paths
516 seperated by a colon.</dd>
521 <section id="suexec"><title>Suexec</title>
523 <p>Apache includes a support program called <a
524 href="suexec.html">suexec</a> which can be used to isolate user
525 CGI programs. However, if suexec is improperly configured, it
526 can cause serious security problems. Therefore, you should
527 carefully read and consider the <a href="suexec.html">suexec
528 documentation</a> before implementing this feature.</p>
532 <section id="compile"><title>Build</title>
534 <p>Now you can build the various parts which form the Apache
535 package by simply running the command:</p>
537 <example>$ make</example>
539 <p>Please be patient here, since a base configuration takes
540 approximately 3 minutes to compile under a Pentium III/Linux
541 2.2 system, but this will vary widely depending on your
542 hardware and the number of modules which you have enabled.</p>
545 <section id="install"><title>Install</title>
547 <p>Now its time to install the package under the configured
548 installation <em>PREFIX</em> (see <code>--prefix</code> option
549 above) by running:</p>
551 <example>$ make install</example>
553 <p>If you are upgrading, the installation will not overwrite
554 your configuration files or documents.</p>
557 <section id="customize"><title>Customize</title>
559 <p>Next, you can customize your Apache HTTP server by editing
560 the <a href="configuring.html">configuration files</a> under
561 <em>PREFIX</em>/conf/.</p>
563 <example>$ vi <em>PREFIX</em>/conf/httpd.conf</example>
565 <p>Have a look at the Apache manual under <a
566 href="./">docs/manual/</a> or <a
567 href="http://httpd.apache.org/docs/">http://httpd.apache.org/docs-2.0/</a>
568 for a complete reference of available <a
569 href="mod/directives.html">configuration directives</a>.</p>
572 <section id="test"><title>Test</title>
574 <p>Now you can <a href="invoking.html">start</a> your Apache
575 HTTP server by immediately running:</p>
577 <example>$ <em>PREFIX</em>/bin/apachectl start</example>
579 <p>and then you should be able to request your first document
580 via URL <code>http://localhost/</code>. The web page you see is located
581 under the <directive module="core">DocumentRoot</directive>
582 which will usually be <code><em>PREFIX</em>/htdocs/</code>.
583 Then <a href="stopping.html">stop</a> the server again by
586 <example>$ <em>PREFIX</em>/bin/apachectl stop</example>