]> granicus.if.org Git - apache/blob
1564065
[apache] /
1
2   A P A C H E   I N S T A L L A T I O N
3
4   NOTE: Windows users please read the documents README.NT and
5         http://www.apache.org/docs/windows.html, (or the
6         htdocs/manual/windows.html file included with Apache). 
7         The following applies only to Unix users.
8
9   Introduction
10   ============
11
12   Like all good things, there are two ways to configure, compile, and install
13   Apache.  You can go for the 3-minute installation process using the APACI
14   process described below; or, you can opt for the same mechanism used in
15   previous versions of Apache, as described in the file 'src/INSTALL'.  Each
16   mechanism has its benefits and drawbacks - APACI is newer and a little more
17   raw, but it gets you up and running the least amount of time, whereas the
18   "Configuration.tmpl" mechanism may be more familiar and give you some more
19   flexibility to the power user.  We'd be very interested in your comments and
20   feedback regarding each approach.
21
22
23   Installing the Apache 1.3 HTTP server with APACI
24   ================================================
25
26   1. Overview for the impatient
27      --------------------------
28
29      $ ./configure --prefix=PREFIX
30      $ make
31      $ make install
32      $ PREFIX/sbin/apachectl start
33
34      NOTE: PREFIX is not the string "PREFIX". Instead use the Unix
35            filesystem path under which Apache should be installed. For
36            instance use "/usr/local/apache" for PREFIX above.
37
38   2. Requirements
39      ------------
40
41      The following requirements exist for building Apache:
42
43      o  Disk Space: 
44
45         Make sure you have approximately 12 MB of temporary free disk space
46         available.  After installation Apache occupies approximately 3 MB of
47         disk space (the actual required disk space depends on the amount of
48         compiled in third party modules, etc).
49
50      o  ANSI-C Compiler: 
51
52         Make sure you have an ANSI-C compiler installed. The GNU C compiler
53         (GCC) from the Free Software Foundation (FSF) is recommended (version
54         2.7.2 is fine). If you don't have GCC then at least make sure your
55         vendors compiler is ANSI compliant. You can find the homepage of GNU
56         at http://www.gnu.ai.mit.edu/ and the GCC distribution under
57         http://www.gnu.ai.mit.edu/order/ftp.html .
58
59      o  Perl 5 Interpreter [OPTIONAL]:
60
61         For some of the support scripts like `apxs' or `dbmmanage' (which are
62         written in Perl) the Perl 5 interpreter is required (versions 5.003
63         and 5.004 are fine). If no such interpreter is found by APACI's
64         `configure' script this is no harm.  Of course, you still can build
65         and install Apache 1.3. Only those support scripts cannot be used. If
66         you have multiple Perl interpreters installed (perhaps a Perl 4 from
67         the vendor and a Perl 5 from your own), then it is recommended to use
68         the --with-perl option (see below) to make sure the correct one is
69         selected by APACI.
70
71      o  Dynamic Shared Object (DSO) support [OPTIONAL]:
72
73         To provide maximum flexibility Apache now is able to load modules
74         under runtime via the DSO mechanism by using the pragmatic
75         dlopen()/dlsym() system calls. These system calls are not available
76         under all operating systems therefore you cannot use the DSO mechanism
77         on all platforms. And Apache currently has only limited built-in
78         knowledge on how to compile shared objects because this is heavily
79         platform-dependend. The current state is this:
80
81         o Out-of-the-box supported platforms are:
82            - Linux     - IRIX
83            - FreeBSD   - HPUX
84            - OpenBSD   - OSF1
85            - NetBSD    - UnixWare
86            - SunOS     - AIX
87            - Solaris 
88
89         o Entirely unsupported platforms are:
90            - Ultrix
91
92         If your system is not on these lists but has the dlopen-style
93         interface, you either have to provide the appropriate compiler and
94         linker flags (see CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT
95         below) manually or at least make sure a Perl 5 interpreter is
96         installed from which Apache can guess the options.
97
98         For more in-depth information about DSO support in Apache 1.3 please
99         read the document htdocs/manual/dso.html carefully. Especially the
100         section entitled "Advantages & Disadvantages" because using the DSO
101         mechanism can have strange side-effects if you are not carefully. BE
102         WARNED!
103
104   3. Configuring the source tree
105      ---------------------------
106
107      NOTE: Although we'll often advise you to read the src/Configuration.tmpl
108            file parts to better understand the various options in this
109            section, there is _AT NO TIME_ any need to _EDIT_ this file. The
110            _COMPLETE_ configuration takes place via command line arguments and
111            local shell variables for the ./configure script. The
112            src/Configuration.tmpl file is just a _READ-ONLY_ resource, here.
113
114      Introduction:
115
116      The next step is to configure the Apache source tree for your particular
117      platform and personal requirements. The most important setup here is the
118      location prefix where Apache is to be installed later, because Apache has
119      to be configured for this location to work correctly. But there are a lot
120      of other options available for your pleasure.
121
122      For a short impression of what possibilities you have, here is a typical
123      example which compiles Apache for the installation tree /sw/pkg/apache
124      with a particular compiler and flags plus the two additional modules
125      mod_rewrite and mod_proxy for later loading through the DSO mechanism: 
126
127      $ CC="pgcc" OPTIM="-O2" \
128        ./configure --prefix=/sw/pkg/apache \
129                    --enable-module=rewrite --enable-shared=rewrite \
130                    --enable-module=proxy   --enable-shared=proxy
131
132      The complete reference of all configuration possibilities follows. For
133      more real-life configuration examples please check out the file
134      README.configure.
135
136      Reference:
137
138      $ [CC=...]        [CFLAGS_SHLIB=...]         
139        [OPTIM=...]     [LD_SHLIB=...]
140        [CFLAGS=...]    [LDFLAGS_SHLIB=...]        
141        [INCLUDES=...]  [LDFLAGS_SHLIB_EXPORT=...] 
142        [LDFLAGS=...]   [RANLIB=...]  
143        [LIBS=...] 
144        ./configure [--quiet]   [--prefix=DIR]         [--enable-rule=NAME]    
145                    [--verbose] [--exec-prefix=PREFIX] [--disable-rule=NAME]   
146                    [--shadow]  [--bindir=EPREFIX]     [--add-module=FILE]     
147                    [--help]    [--sbindir=DIR]        [--activate-module=FILE]
148                    [--layout]  [--libexecdir=DIR]     [--enable-module=NAME]  
149                                [--mandir=DIR]         [--disable-module=NAME] 
150                                [--sysconfdir=DIR]     [--enable-shared=NAME]  
151                                [--datadir=DIR]        [--disable-shared=NAME] 
152                                [--includedir=DIR]     
153                                [--localstatedir=DIR]  [--enable-suexec]     
154                                [--runtimedir=DIR]     [--suexec-caller=UID] 
155                                [--logfiledir=DIR]     [--suexec-userdir=DIR]
156                                [--proxycachedir=DIR]  [--suexec-uidmin=UID]
157                                [--compat]             [--suexec-gidmin=GID]
158                                                       [--suexec-safepath=PATH] 
159
160                                                       [--with-perl=FILE]   
161                                                       [--without-support]  
162                                                       [--without-confadjust]
163
164      Use the CC, OPTIM, CFLAGS, INCLUDES, LDFLAGS, LIBS, CFLAGS_SHLIB,
165      LD_SHLIB, LDFLAGS_SHLIB, LDFLAGS_SHLIB_EXPORT and RANLIB environment
166      variables to override the corresponding default entries in the
167      src/Configuration.tmpl file (see there for more information about their
168      usage).
169
170          Note: The syntax ``KEY=VALUE ./configure ...'' (one single line!) is
171                the GNU Autoconf compatible way of specifying defines and can
172                be used with Bourne shell compatible shells only (sh, bash,
173                ksh). If you use a different type of shell either use ``env
174                KEY=VALUE ./configure ...'' when the `env' command is available
175                on your system or use ``setenv KEY VALUE; ./configure ...'' if
176                you use one of the C-shell variants (csh, tcsh).
177
178          Note: The above parameter names are the canonical ones used in
179                Autoconf-style interfaces. But because src/Configuration.tmpl
180                uses the prefix EXTRA_ for some variables (e.g. EXTRA_CFLAGS)
181                these variants are accepted for backward-compatibility reasons,
182                too. But please use the canonical Autoconf-style names and
183                don't rely on this.
184
185      Use the --prefix=PREFIX and --exec-prefix=EPREFIX options to configure
186      Apache to use a particular installation prefix. The default is
187      PREFIX=/usr/local/apache and EPREFIX=PREFIX.
188
189      Use the --bindir=DIR, --sbindir=DIR, --libexecdir=DIR, --mandir=DIR,
190      --sysconfdir=DIR, --datadir=DIR, --includedir=DIR, --localstatedir=DIR,
191      --runtimedir=DIR, --logfiledir=DIR and proxycachedir=DIR option to change
192      the paths for particular subdirectories of the installation tree.
193      Defaults are bindir=EPREFIX/bin, sbindir=EPREFIX/sbin,
194      libexecdir=EPREFIX/libexec, mandir=PREFIX/man, sysconfdir=PREFIX/etc,
195      datadir=PREFIX/share, includedir=PREFIX/include,
196      localstatedir=PREFIX/var, runtimedir=PREFIX/var/run,
197      logfiledir=PREFIX/var/log and proxycachedir=PREFIX/var/proxy.
198
199      Use the --compat option to install Apache into a installation tree which
200      has a similar layout than the one used with Apache 1.2.
201  
202      Use the --layout option to check the final installation path layout while
203      fiddling with the options above.
204  
205      Use the --enable-rule=NAME and --disable-rule=NAME options to enable or
206      disable a particular Rule from the Apache src/Configuration.tmpl file. The
207      defaults (yes=enabled, no=disabled) can either be seen when running
208      `./configure --help' or manually looked up in the src/Configuration.tmpl
209      file.
210  
211      Use the --add-module=FILE option to copy a module source file to the
212      Apache src/modules/extra/ directory and on-the-fly add an entry for it in
213      the configuration file. FILE has to be a valid path to a C source file
214      outside the Apache source tree, for instance /path/to/mod_foo.c. The added
215      module this is way is automatically activated and enabled. Use this option
216      to automatically include a simple third-party module to the Apache build
217      process.
218  
219      Use the --activate-module=FILE option to on-the-fly add an entry for an
220      existing module source file in the configuration file. FILE has to be a
221      valid path under src/modules/ of the Apache source tree, i.e. it already
222      has to be copied to this location before.  The module is automatically
223      enabled. Use this option to automatically include a complex third-party
224      module to the Apache build process where, for instance a module like
225      mod_perl or mod_php3 consisting of more than one file which are created by
226      a third-party configuration scheme.
227  
228      Use the --enable-module=NAME and --disable-module=NAME options to enable
229      or disable a particular already distributed module from the Apache
230      src/Configuration.tmpl file. The correct module names (no `mod_' prefix!)
231      and defaults (yes=enabled, no=disabled) can be seen when running
232      `./configure --help'.  There are two special NAME variants: "all" for
233      enabling or disabling all modules and "most" for enabling or disabling
234      only these modules which are useable on all platforms (currently this is
235      "all" minus the modules auth_db, log_agent, log_referer, example, so and
236      mmap_static).
237  
238      Use the --enable-shared=NAME and --disable-shared=NAME options to enable
239      or disable the shared object support for a particular module from the
240      Apache src/Configuration.tmpl file. The defaults (yes=enabled,
241      no=disabled) can be seen when running `./configure --help'. There are two
242      special NAME variants: "max" for enabling or disabling all modules except
243      the bootstrapping "so" module and "remain" for enabling or disabling only
244      these modules which are still not enabled. 
245      
246          Note 1: The --enable-shared option DOES NOT AUTOMATICALLY enable the
247                  module because there are variants like `--enable-shared=all'
248                  which should not imply `--enable-module=all'.  
249
250          Note 2: Per default the DSO mechanism is globally disabled, i.e. no
251                  modules are build as shared objects.
252
253          Note 3: The usage of any --enable-shared option automatically implies
254                  a --enable-module=so option because the bootstrapping module
255                  mod_so is always needed for DSO support.
256
257          Note 4: When you later want to extend your Apache installation via
258                  third-party modules through the DSO+APXS mechanism make sure
259                  that you at least compile with mod_so included, even when no
260                  distributed modules are build as shared objects. This can be
261                  achieved by explicitly using --enable-module=so.
262
263      Use the --with-perl=FILE option to select a particular Perl interpreter
264      executable to be used with Apache. Per default APACI tries to find it
265      automatically. But if multiple Perl instances exist on your system you
266      have to select the correct one manually.
267  
268      Use the --without-support option to explicitly disable the build and
269      installation of support tools from the src/support/ area. This can be
270      useful when you have compilation problems with one or more of these not
271      programs on your platform or if you just don't need them.
272
273      Use the --without-confadjust option to explicitly disable some built
274      user/situation dependent adjustments to the config files (Group, Port,
275      ServerAdmin, ServerName, etc.).  This is usually only interesting for
276      vendor package maintainers who wants to force the keeping of defaults.
277  
278      Use the --enable-suexec option to enable the suEXEC feature by building
279      and installing the "suexec" support program. Use --suexec-caller=UID to
280      set the allowed caller user id, the --suexec-userdir=DIR to set the user
281      subdirectory, the --suexec-uidmin=UID/--suexec-gidmin=GID to set the
282      minimal allowed UID/GID and --suexec-safepath=PATH to set the safe shell
283      PATH for the suEXEC feature. At least one --suexec-xxxxx option has
284      to be provided together with --enable-suexec option to let APACI accept
285      your request for using the suEXEC feature.
286
287      CAUTION: FOR DETAILS ABOUT THE SUEXEC FEATURE WE HIGHLY RECOMMEND YOU TO
288               FIRST READ THE DOCUMENT htdocs/manual/suexec.html BEFORE USING
289               THE ABOVE OPTIONS.
290      
291               USING THE SUEXEC FEATURE PROPERLY CAN REDUCE CONSIDERABLY THE
292               SECURITY RISKS INVOLVED WITH ALLOWING USERS TO DEVELOP AND RUN
293               PRIVATE CGI OR SSI PROGRAMS. HOWEVER, IF SUEXEC IS IMPROPERLY
294               CONFIGURED, IT CAN CAUSE ANY NUMBER OF PROBLEMS AND POSSIBLY
295               CREATE NEW HOLES IN YOUR COMPUTER'S SECURITY.  IF YOU AREN'T
296               FAMILIAR WITH MANAGING SETUID ROOT PROGRAMS AND THE SECURITY
297               ISSUES THEY PRESENT, WE HIGHLY RECOMMEND THAT YOU NOT CONSIDER
298               USING SUEXEC AND KEEP AWAY FROM THESE OPTIONS!
299
300      Use the --shadow option to let APACI create a shadow source tree of the
301      sources for building. This is useful when you want to build for different
302      platforms in parallel (usually through a NFS, AFS or DFS mounted
303      filesystem).
304  
305      Use the --quiet option to disable all configuration verbose messages.
306  
307      Use the --verbose option to enable additional verbose messages.
308      
309   4. Building the package
310      --------------------
311      
312      Now you can build the various parts which form the Apache package by
313      simply running the command
314  
315         $ make 
316  
317      Please be patient here, this takes approximately 2 minutes to complete
318      under a Pentium-166/FreeBSD-2.2 system, dependend on the amount of
319      modules you have enabled. 
320  
321   5. Installing the package
322      ----------------------
323      
324      Now its time to install the package under the configured installation
325      PREFIX (see --prefix option above) by running:
326  
327         $ make install
328  
329      For the paranoid hackers under us: The above command really installs under
330      prefix _only_, i.e. no other stuff from your system is touched. Even if
331      you upgrade an existing installation your configuration files in
332      PREFIX/etc/ are preserved.
333
334      Note for package authors:
335
336      To simplify rolling a package tarball from the installed files APACI
337      provides a way to override the installation root for the install step.
338      Additionally you can get rid of the user message at the end of the
339      installation process by using the `install-quiet' target. Example:
340
341          $ make install-quiet root=/tmp/apache-root
342  
343   6. Testing the package
344      -------------------
345  
346      Now you can fire up your Apache HTTP server by immediately running
347  
348         $ PREFIX/sbin/apachectl start
349  
350      and then you should be able to request your first document via URL
351      http://localhost/. Then stop the server again by running:
352   
353         $ PREFIX/sbin/apachectl stop
354  
355   7. Customizing the package
356      -----------------------
357  
358      Finally you can customize your Apache HTTP server by editing the
359      configuration files under PREFIX/etc/.
360  
361         $ vi PREFIX/etc/httpd.conf
362         $ vi PREFIX/etc/access.conf
363         $ vi PREFIX/etc/srm.conf
364  
365      Have a look at the Apache manual under http://localhost/manual/ or
366      http://www.apache.org/docs/ for a complete reference of available
367      configuration directives.
368
369   8. Preparing the system
370      --------------------
371
372      Proper operation of a public HTTP server requires at least the following:
373
374      1. A correctly working TCP/IP layer, since HTTP is implemented on top of
375         TCP/IP. Although modern Unix platforms have good networking layers,
376         always make sure you have all official vendor patches referring to the
377         network layer applied.
378
379      2. Accurate time keeping, since elements of the HTTP protocol are
380         expressed as the time of day.  So, it's time to investigate setting
381         some time synchronization facility on your system. Usually the ntpdate
382         or xntpd programs are used for this purpose which are based on the
383         Network Time Protocol (NTP). See the Usenet newsgroup
384         comp.protocols.time.ntp and the NTP homepage at
385         http://www.eecis.udel.edu/~ntp/ for more details about NTP software
386         and public time servers.
387
388   9. Contacts
389      --------
390
391      o If you want to be informed about new code releases, bug fixes, 
392        security fixes, general news and information about the Apache server
393        subscribe to the apache-announce mailing list as described under
394        http://www.apache.org/announcelist.html
395
396      o If you want freely available support for running Apache please join the
397        Apache user community by subscribing at least to the following USENET
398        newsgroup:
399        comp.infosystems.www.servers.unix
400
401      o If you want commercial support for running Apache please contact
402        one of the companies and contractors which are listed at
403        http://www.apache.org/info/support.cgi
404
405      o If you have a concrete bug report for Apache please go to the
406        Apache Group Bug Database and submit your report:
407        http://www.apache.org/bug_report.html
408
409      o If you want to participate in actively developing Apache please
410        subscribe to the `new-httpd' mailing list as described at
411        http://dev.apache.org/mailing-lists
412
413      Thanks for running Apache.
414                                           The Apache Group
415                                           http://www.apache.org/
416