Building Apache

This chapter is from the book

Apache Desktop Reference

Learn More Buy

This chapter is from the book

This chapter is from the book 

Apache Desktop Reference

Learn More Buy

3.2 Configuration Reference

The following is a complete reference to the APACI command line. The various APACI command-line variables and options enable you to adjust the way Apache is built and installed. The command line has the following general structure:

$  env [VARIABLE=value ...] ./configure [--option=value ...]
   

3.2.1 Configuration Variables

The following VARIABLEs are taken from the APACI environment:

• CC C Compiler Program

  Example: CC="egcc"

  Specifies the C compiler program to use when building the Apache object files and executables. The default is platform-dependent— Apache selects the best choice when more than one compiler is installed on the platform. You can also use this variable to force the usage of a particular compiler, however.

• CFLAGS C Compiler Standard Flags

  Example: CFLAGS="-Wall -pendantic"

  To squeeze out the maximum on a Pentium platform, compile with "CC=pgcc CFLAGS='-06 -mpentium'" when the Pentium optimized GNU C compiler is available. This option speeds up at least number-crunching tasks such as regex matching.

  Specifies standard flags for the C compiler. These flags will be used on the CC command lines. The exception is "-I", which (for historical reasons) should be specified with INCLUDES.

• OPTIM C Compiler Optimization Flags

  Example: OPTIM="-pipe -02"

  Specifies the C compiler optimization flags. These flags can also be specified via CFLAGS, but for historical reasons they have their own variable.

• INCLUDES C Compiler Include Flags

  Example: INCLUDES="-I/usr/local/include"

  Specifies additional include flags for the C compiler ("-Idirectory"). These flags can also be specified via CFLAGS, but for historical reasons they have their own variable.

• LDFLAGS Linker Standard Flags

  Example: LDFLAGS="-L/usr/local/lib"

  Specifies additional standard flags for the linker command. These flags are usually "-Ldirectory" flags intended to help the linker find third-party libraries.

• LIBS Linker Library Flags

  Example: LIBS="-ldb"

  Specifies additional library flags for the linker command. These flags are usually just "-lname" flags for linking Apache with third-party libraries.

• CFLAGS_SHLIB Additional CFLAGS for DSO Building

  Example: CFLAGS_SHLIB="-fPIC"

  Special flags for the C compiler that are used in addition to CFLAGS when DSOs are compiled. Usually, they specify which flags are required to force the generation of position-independent code (PIC).

• LD_SHLIB Linker for DSO Building

  Example: LD_SHLIB="ld"

  In most cases, you do not need to specify DSO building details manually. Apache already knows how to use DSO on all major UNIX platforms.

  Specifies the linker used for building DSOs. The default is platform-dependent and is usually either the value of CC or directly "Id"

• LDFLAGS-SHLIB Additional LDFLAGS for DSO Building

  Example: LDFLAGS_SHLIB="-Bshareable"

  Special flags for the DSO linker command (LD_SHLIB) that are used in addition to LDFLAGS when DSOs are built. Usually, they specify which flags are required to force the generation of shared objects instead of standard objects (executables).

• LDFLAGS_SHLIB_EXPORT Add. LDFLAGS for Program Building under DSO

  Example: LDFLAGS_SHLIB_EXPORT="-rdynamic"

  Special flags for the linker command (CC) that are used in addition to LDFLAGS when the Apache executable is built. Usually, they specify which flags are required to force the export of API symbols for use by DSO-based modules.

• RANLIB Archive Indexing Tool

  Example: RANLIB="/bin/true"

  Used to override the "ranlib" command if the local platform doesn't require it. This command is rarely needed, because Apache automatically knows whether it is required.

• DEPS Additional Makefile Dependency

  Example: DEPS="..."

  For developers only. This command can be used to add a Make dependency to src/Makefile.

• TARGET Name of the Target Program

  Example: TARGET="apache"

  Equivalent to the option --target. (See this option for details.)

• EAPL_MM Path to MM Library (mod_ssl only)

  Example: EAPI_MM="SYSTEM"

  Sets the path to the MM library source or installation tree. This library is used in conjunction with the Extended API (EAPI) facility. The argument "SYSTEM" can be specified to indicate that APACI should search for the MM library in standard system locations.

• SSL_BASE Path to OpenSSL Toolkit (mod_ssl only)

  Example: SSL_BASE="SYSTEM"

  mod_ssl extends APACI; that's why additional configuration variables are available.

  Sets the path to the OpenSSL toolkit source or installation tree. This toolkit is used in conjunction with mod_ssl. The string "SYSTEM" can be specified as the argument to indicate that APACI should search for the OpenSSL toolkit in standard system locations.

• RSA_BASE Path to RSAref Library (mod_ssl only)

  Example: RSA_BASE="SYSTEM"

  Sets the path to the RSAref library source or installation tree. This library is used by U.S. residents (only) in conjunction with mod_ssl. The string "SYSTEM" can be specified as the argument to indicate that APACI should search for the RSAref library in standard system locations.

3.2.2 General Options

The following general options are available on the APACI command line:

• --quiet Quiet Configuration

  Example: --quiet

  Forces APACI to suppress the display of all output while configuring the source tree. This option can be useful for running APACI in batch mode— for instance, from a vendor packaging facility like RPM.

• --verbose Verbose Configuration

  Example: --verbose

  Use --shadow for building Apache on multiple architectures in parallel.

  Forces APACI to display additional output while configuring the Apache source tree. This option can be useful for testing the results of various configuration options.

• --shadow[=Dir] Create a Shadow Source Tree

  Example: --shadow=/tmp/apache

  Creates a shadow tree of the Apache source tree under the specified directory Dir before configuration. A shadow tree consists of all directories of the original tree, with all files inside those directories being replaced by symbolic links to the original files. This option is useful when the original Apache source tree stays on a read-only medium (typically, a CD-ROM) or when one compiles Apache in parallel for multiple platforms. Details about this facility are found in section 3.3.1.

3.2.3 Stand-alone Options

The following options stand alone. That is, they stop the configuration process and instead perform a special action only.

• --help Display Usage Summary

  Example: --help

  Displays a short usage summary page listing all APACI command-line options. Use this option when you have forgotten an option and want to identify it.

• --show-layout Display Installation Path Layout

  Example: --show-layout

  Displays the resulting installation path layout. By default, this option displays the "Apache" layout from the file config.layout. It is also useful in combination with the --with-layout option and the other installation layout options (see section 3.2.4) for easily checking the results of those options without having to configure, build, and install the package.

3.2.4 Installation Layout Options

The following options are used for configuring the general installation path layout:

• --with-layout=[File:]Name Installation Path Layout

  Example: --with-layout=GNU

  The --with-layout option allows you to load custom installation path layouts from a file.

  Selects the predefined installation path layout named Name from the file config.layout. This file includes several popular layout ingredients, and you can set all of their paths at once with this single option. The default is the historical "Apache" layout. The most typical layout is "GNU," which resembles the installation paths of typical GNU Autoconf-based packages. When the Name argument is prefixed with "File:", Name is loaded from File instead of config.layout. Use this option for easy loading your own custom layouts.

• --target=Name Installation Target Name

  Example: --target=apache

  Sets the name of the target program to Name. The default is the historical "httpd". This name affects both the name of the installed executable and the error messages.

• --prefix=Prefix Installation Path Prefix

  Example: --prefix=/usr/local/apache

  The only mandatory APACI is --prefix.

  As with original GNU Autoconf "configure" scripts, this option is the most important choice. It sets the installation path prefix— that is, the root of the installation tree. Because most other installation path-related options are, by default, subdirectories of this path, this option implicitly changes the value of these options unless you configure them manually. The default for Prefix is /usr/local/apache. In most cases, this option is all you need to force the installation to take place in a different file system area.

• --exec-prefix=ExecPrefix Installation Path Prefix for Executables

  Example: --exec-prefix=/usr/local/apache.'uname -m'

  Similar to --prefix, but configures only the prefixes for executables— or, more correctly, for architecture-dependent files. The default for ExecPrefix is Prefix; that is, by default APACI doesn't distinguish between the various types of files. This option is useful primarily when you install Apache for multiple architectures into the same installation area.

• --datadir=DataDir Installation Path Prefix for Shared Data

  Example: --datadir=/usr/local/apache/share

  By default, APACI uses a three-step path dependency hierarchy: --with-layout at the top, then a few options like --datadir that group related files, and finally specialized options like --bindir for fine-tuning.

  Sets the installation path prefix for the static, read-only data files used by Apache (such as hypertext documents, and CGI scripts). The default depends on the installation path layout (see the discussion of the --with-layout option), but DataDir usually defaults to Prefix; that is, this directory is usually a path prefix for other paths.

• --localstatedir=StateDir Inst. Path Prefix for Dynamic Data

  Example: --localstatedir=/usr/local/apache/var

  Sets the installation path prefix for the various dynamic/writable data files used by Apache (such as log files). The default depends on the installation path layout (see the discussion of the --with-layout option), but StateDir usually defaults to Prefix; that is, this directory is usually a path prefix for other paths.

The following options are used for fine-tuning the installation path layout:

• --bindir=Dir Installation Path for User Binaries

  Example: --bindir=/usr/local/apache/bin

  Sets the installation path for user binaries— that is, executables that will be run by the end user. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to ExecPrefix/bin.

• --sbindir=Dir Installation Path for System Binaries

  Example: --sbindir=/usr/local/apache/bin

  Sets the installation path for system binaries— that is, executables that will be run by system administrators only. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to ExecPrefix/bin.

• --libexecdir=Dir Installation Path for Internal Binaries

  Example: --libexecdir=/usr/local/apache/libexec

  Sets the installation path for internal binaries— that is, executables and DSOs that will be loaded and run by Apache itself. The default depends on the installation path layout (see the discussion of the --with--layout option), but Dir usually defaults to ExecPrefix/libexec.

• --mandir=Dir Installation Path for Manual Pages

  Example: --mandir=/usr/local/apache/man

  Sets the installation path for the UNIX manual pages. The default depends on the installation path layout (see the discussion of the --with--layout option), but Dir usually defaults to Prefix/man.

• --sysconfdir=Dir Installation Path for Configuration

  Example: --sysconfdir=/usr/local/apache/etc

  Most of the APACI options are similar in name to the ones specified by the GNU standards.

  Sets the installation path for the various configuration files. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to Prefix/conf.

• --includedir=Dir Installation Path for C Include Files

  Example: --includedir=/usr/local/apache/include

  Sets the installation path for the C language include files (also known as "header files"), which are used by the APXS facility. The default depends on the installation path layout (see the discussion of the --with--layout option), but Dir usually defaults to Prefix/include.

• --iconsdir=Dir Installation Path for Icons

  Example: --iconsdir=/usr/local/apache/share/icons

  Sets the installation path for icon images. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to DataDir/icons.

• --htdocsdir=Dir Installation Path for Hypertext Documents

  Example: --htdocsdir=/usr/local/apache/share/htdocs

  Sets the installation path for hypertext documents. The default depends on the installation path layout (see the discussion of the --with--layout option), but Dir usually defaults to DataDir/htdocs.

• --cgidir=Dir Installation Path for CGI Scripts

  Example: --htdocsdir=/usr/local/apache/share/cgi-bin

  Sets the installation path for CGI scripts. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to DateDir/cgi-bin.

• --runtimedir=Dir Installation Path for Runtime Data

  Example: --runtimedir=/usr/local/apache/var

  Sets the installation path for the runtime data of Apache (scoreboard, PID file, and so on). The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to StateDir/logs.

• --logfiledir=Dir Installation Path for Log Files

  Example: --logfiledir=/usr/local/apache/var

  This sets the installation path for the log files. The default depends on the installation path layout (see the discussion of the --with-layout option), but Dir usually defaults to StateDir/logs.

• --proxycachedir=Dir Installation Path for Proxy Cache

  Example: --proxycachedir=/usr/local/apache/var

  Sets the installation path for the proxy module's cache. The default depends on the installation path layout (see the discussion of the --with--layout option), but Dir usually defaults to StateDir/proxy.

3.2.5 Build Options

The following options are used for configuring the various build parameters:

For configuring special details of Apache, some configuration rules exist. Some of them were added to APACI by mod_ssl.

• --enable-rule=Name Enable a Configuration Rule

  Example: --enable-rule=WANTHSREGEX

  Used to enable various configuration rules. The following rule Names are available:

  • SHARED_CORE Configures the Apache core to be built into a shared library.

  • SHARED_CHAIN Configures the linking of module DSOs against possibly existing shared libraries.

  • SOCKS4 Builds Apache with the SOCKS version 4 toolkit. When it is enabled, you must add the SOCKS library location to LIBS, otherwise, "-L/usr/local/lib -lsocks" will be assumed.

  • SOCKS5 Builds Apache with the SOCKS version 5 toolkit. When it is enabled, you must add the SOCKS library location to LIBS, otherwise, "-L/usr/local/lib -lsocks5" will be assumed.

  • IRIXNIS Takes effect only if you are configuring on SGI IRIX. Read the src/Configuration.tmpl file for more details.

  • IRIXN32 Takes effect only if you are configuring on SGI IRIX. Read the src/Configuration.tmpl file for more details.

  • PARANOID During the configuration, modules can run pre-programmed shell commands in the same environment in which APACI runs. This rule allows modules to control how APACI works. Normally, APACI will simply note that a module is performing this function. If you use this rule, it will also print out the code that the modules execute.

  • EXPAT Includes James Clark's Expat package (an XML/1.0 parsing library) into Apache, for use by the modules. By default, this rule is already enabled.

    If you have a broken vendor regex library (for instance, if you observe core dumps on RewriteRule directives), use --enable-rule=-WANTHSREGEX.

  • WANTHSREGEX Apache requires a POSIX-compliant regular expression library. Henry Spencer's excellent Regex package is included with Apache and is used automatically when the underlying operating system has no equivalent library. By default, this rule is enabled unless it is overruled by operating system specifics.

  • EAPI(mod_ssl only) Enables EAPI, which provides a generic, low-level, function-calling mechanism, a generic data structure context mechanism; and shared memory support.

  • SSL_COMPAT (mod_ssl only) Enables mod_ssl to be built with backward-compatible code for Apache-SSL 1.x, mod_ssl 2.0.x, Sioux 1.x, and Stronghold 2.x. By default, it is already enabled.

    If you have a broken vendor NDBM library (for instance, if you observe core dumps on HTTPS requests), use --enable-rule=-SSL_SDBM.

  • SSL_SDBM (mod_ssl only) Controls whether the built-in SDBM library should be used for mod_ssl instead of a custom-defined or vendor-supplied DBM library. The default is to use a vendor NDBM library.

  • SSL_EXPERIMENTAL (mod_ss1 only) Can be used to enable experimental code inside mod_ssl. These new features typically need more testing before they can be considered stable.

  • SSL_VENDOR (mod_ssl only) Can be used to enable code inside mod-_ssl that product vendors can use to extend mod_ssl itself via EAPI hooks without patching the source.

• --disable-rule=Name Disable a Configuration Rule

  Example: --disable-rule=WANTHSREGEX

  Disables a rule.

• --add-module=Name Import a Third-Party Module

  Example: —add-module=/tmp/mod_foo.c

  Imports and activates a third-party module File into the Apache source tree under src/modules/extra/. See Section 3.3.2 for more details.

• --activate-module=File Activate Third-Party Module

  Example: --activate-module=src/modules/extra/mod_foo.o

  Activates a manually imported third-party module File, which must stay under src/modules/. See Section 3.3.2 for more details.

• --permute-module=Name1:Name2 Permute Module Order

  Example: --permute-module=rewrite:alias

  An expert option that can be used to permute the order of modules. See Section 3.3.3 for more details.

• --enable-module=Name Enable a Module for Building

  Example: --enable-module=rewrite

  Use the powerful --enable-module and --disable-module options to assemble your individual Apache functionality.

  Enables a module "mod_Name" for building. The following modules are available (a "*" indicates that it is enabled by default):

   http_core *     mod_dir *              mod_asis * 
   mod_so          mod_actions *          mod_autoindex *
   mod_alias *     mod_negotiation *      mod_status *
   mod_rewrite     mod_env *              mod_info 
   mod_userdir *   mod_setenvif *         mod_log_config *
   mod_imap *      mod_unique_id          mod_log_agent
   mod_speling     mod_cgi *              mod_log_referer
   mod_access *    mod_include *          mod_usertrack
   mod_auth *      mod_mime *             mod_mmap_static
   mod_auth_anon   mod_mime_magic         mod_example
   mod_auth_dbm    mod_expires            mod_proxy
   mod_auth_db     mod_headers            mod_perl
   mod_digest      mod_cern_meta          mod_ssl
  

  Two special variants of Name exist: "all" enables all existing modules and "most" enables only those modules known to be usable on all platforms without problems.

• --disable-module=Name Disable a Module for Building

  Example: --disable-module=alias

  Disables an enabled (by default or manually) module from building.

• --enable-Shared=Name Enable a Module for DSO

  Example: --enable-shared=rewrite

  Enables a module "mod_Name" for building as a DSO. In addition to the standard module names, two special variants of Name exist: "max" enables DSO for all modules except for the bootstrapping modules (http_core and mod_so), and "remain" first enables all still-disabled modules, then enables them for building as DSO.

• --disable-Shared=Name Disable a Module for DSO

  Example: --disable-shared=rewrite

  Disables a module "mod_Name" for building as a DSO.

• --with-perl=File Sets the Perl Interpreter

  Example: --with-perl=/usr/local/bin/per1

  Sets the path to the Perl interpreter executable to File. By default, APACI searches for "perl" and "perl5" in $PATH for the latest interpreter version. Use this option when more than one Perl interpreter is installed on your system or you want to use a Perl interpreter found in a nonstandard file system location.

• --without-support Build without Support Tools

  Example: --without-support

  Forces APACI to not build the support tools under src/support/. By default, these tools are built. Use this option when these tools are unnecessary cause portability problems.

• --without-confadjust No Configuration Adjustments

  Example: --without-confadjust

  Vendor package maintainers should keep --without--confadjust in mind.

  Forces APACI to not adjust the configuration files on installation. By default, APACI recognizes, for instance, that when you build as non-root (UID ≠ 0), it might be reasonable to pre-configure Apache for port 8080 instead of 80 (because non-root users cannot run Apache on port 80). Sometimes these adjustments are confusing, especially for vendor package maintainers. In such a case, you can disable the adjustments with this option.

• --without-execstrip No Executable Stripping

  Example: --without-execstrip

  Forces APACI to not "strip" (remove debugging symbols) the executa-bles when installing them. This option can be either useful for debugging purposes or required on esoteric platforms where the DSO facility works only when the Apache executable is not "stripped."

3.2.6 suEXEC Options

The following options for configuring the suEXEC facility are available on the APACI command line:

• --enable-suexec Enables suexec Facility

  Example: --enable-suexec

  Enables the suEXEC facility, which can be used to run CGI scripts under particular UIDs.

• --suexec-caller=Name suexec Caller UID Example: --suexec-caller=www

  The suEXEC facility allows CGI scripts to be executed under the UID/GID of the script owner instead of the runtime UID/GID of the Apache server processes.

  Sets the user name of the suEXEC calling process to Name— that is, the UID under which Apache runs (when Apache is started as root, so that UID = 0, the Name can be a configured custom UID; see the User directive). The suEXEC then runs only CGI scripts when the calling process has this user name.

• --suexec-docroot=Dir suEXEC Document Root

  Example: --suexec-docroot=/usr/local/apache/share/htdocs

  Sets the path for the suEXEC document root to Dir.

• --suexec-logfile=File suEXEC Log File Path

  Example: --suexec-logfile=/usr/local/apache/var/suexec.log

  Sets the path for the dedicated suEXEC log file to File.

• --suexec-userdir=SubDir suEXEC User Home Subdirectory

  Example: --suexec-userdir=.public-html

  Sets SubDir as the subdirectory of the user's "homedirs," where CGI scripts must reside to be executed through suEXEC.

• --suexec-uidmin=UlD suEXEC Minimum UID

  Example: --suexec-uidmin=1024

  Sets the minimum UNIX user ID to UID; the suEXEC facility can then switch to it.

• --suexec-gidmin=GID suEXEC Minimum GID

  Example: --suexec-gidmin=1024

  Sets the minimum UNIX group ID to GID; the suEXEC facility can then switch to it.

• --suexec-safepath=Path suEXEC Safe PATH variable

  Example: --suexec-safepath=/bin: /usr/bin

  Enforces the colon-separated $PATH variable to Path for use under the suEXEC facility.