Understanding Apache web server configuration files

Editing the wrong Apache configuration file is a fast way to waste an afternoon and a slower way to ship a misconfigured server. Identifying the active configuration file set makes it easier to change virtual hosts, enable modules, and troubleshoot directives that appear to be ignored.

Apache loads configuration from a primary file and then pulls in additional files using Include and IncludeOptional directives. The primary file path varies by distribution and build, and the rest of the configuration often lives in “split” directories (modules, virtual hosts, conf.d-style drop-ins) that are included in a specific order. Relative paths inside configuration are typically resolved against ServerRoot, so the same directive can point to different real locations depending on the build and packaging.

Configuration is read when Apache starts and when it reloads, so edits do not apply until a restart or reload occurs. Wrapper and binary names differ across platforms (apachectl, apache2ctl, httpd, apache2), and many platforms ship sane defaults that are later overridden by included files. Treat the include chain as the source of truth, especially when a setting seems “already changed” but the running server disagrees.

1. Print the compiled configuration paths from the installed Apache binary.

   $ apachectl -V
   Server version: Apache/2.4.41 (Unix)
   Server built:   Nov  9 2019 07:53:54
   Server's Module Magic Number: 20120211:88
   Server loaded:  APR 1.5.2, APR-UTIL 1.5.4
   Compiled using: APR 1.5.2, APR-UTIL 1.5.4
   Architecture:   64-bit
   Server MPM:     prefork
     threaded:     no
       forked:     yes (variable process count)
   Server compiled with....
    -D APR_HAS_SENDFILE
    -D APR_HAS_MMAP
    -D APR_HAVE_IPV6 (IPv4-mapped addresses enabled)
    -D APR_USE_FLOCK_SERIALIZE
    -D APR_USE_PTHREAD_SERIALIZE
    -D SINGLE_LISTEN_UNSERIALIZED_ACCEPT
    -D APR_HAS_OTHER_CHILD
    -D AP_HAVE_RELIABLE_PIPED_LOGS
    -D DYNAMIC_MODULE_LIMIT=256
    -D HTTPD_ROOT="/usr"
    -D SUEXEC_BIN="/usr/bin/suexec"
    -D DEFAULT_PIDLOG="/private/var/run/httpd.pid"
    -D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
    -D DEFAULT_ERRORLOG="logs/error_log"
    -D AP_TYPES_CONFIG_FILE="/private/etc/apache2/mime.types"
    -D SERVER_CONFIG_FILE="/private/etc/apache2/httpd.conf"

2. Use the control wrapper shipped by the platform when apachectl is not present.

   Debian and Ubuntu commonly use apache2ctl, and Fedora, CentOS, and RHEL commonly use httpd for direct binary queries such as httpd -V.

3. Locate the HTTPD_ROOT line in the output.
4. Locate the SERVER_CONFIG_FILE line in the output.
5. Combine HTTPD_ROOT and SERVER_CONFIG_FILE when SERVER_CONFIG_FILE is not an absolute path.

   A relative SERVER_CONFIG_FILE such as conf/httpd.conf resolves under HTTPD_ROOT, producing an absolute path such as /etc/httpd/conf/httpd.conf on many Fedora-family layouts.

6. List the configuration include chain resolved from Include directives.

   $ sudo apachectl -t -D DUMP_INCLUDES
   Included configuration files:
     /private/etc/apache2/httpd.conf
   ##### snipped #####
   Syntax OK

   IncludeOptional entries are shown when the glob matches one or more files.

7. Dump the active run-time configuration to confirm ServerRoot and DocumentRoot values.

   $ sudo apachectl -t -D DUMP_RUN_CFG
   ServerRoot: "/usr"
   Main DocumentRoot: "/Library/WebServer/Documents"
   ##### snipped #####
   Syntax OK

8. Dump the active virtual host map to identify the VirtualHost file sources.

   $ sudo apachectl -S
   VirtualHost configuration:
   ##### snipped #####
   ServerRoot: "/usr"
   ##### snipped #####

9. Validate configuration syntax after locating and editing the correct files.

   $ sudo apachectl -t
   Syntax OK

   Related: How to test your Apache configuration

The location of Apache's main configuration file is different for most distributions, and the configuration is split differently between packaging styles. The table below describes where common configuration concerns are typically declared (not the final effective values), which helps narrow the search once the Include chain is known.

Apart from using different locations for the main configuration file, different distributions also ship different default values for common Apache configuration options. The table below lists typical defaults, which are often overridden by included files, virtual host definitions, or environment-specific drop-ins.