Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 30 ยท Apache Configuration

Apache httpd Configuration

Learn how Apache httpd is configured: apache2.conf and httpd.conf, directives, Directory, Files and Location containers, merge order, modules and MPMs.

Apache httpd has been configured with plain text files for almost thirty years, and the basic idea has barely changed: a long list of directives (Listen 80, ServerName example.com, LoadModule ...), some of them wrapped in containers that say "only for this directory" or "only for this URL". The tricky part is not the syntax, which you can learn in ten minutes. It is knowing which directive wins when several containers match the same request.

In this lesson you will find the main config file on your system, learn the three kinds of directives, meet the containers (<Directory>, <Files>, <Location>), learn the order in which Apache merges them, switch modules on and off, and choose an MPM. If you have read Nginx Configuration Syntax, you will see many parallels, and a few important differences.

Where the configuration lives

The package layout differs between Linux families. Both start from one main file and pull in many small files with Include.

Debian / Ubuntu RHEL, Fedora, Rocky
Program name apache2 (apache2ctl) httpd (apachectl)
Main file /etc/apache2/apache2.conf /etc/httpd/conf/httpd.conf
Sites sites-available/ and sites-enabled/ conf.d/*.conf
Modules mods-available/ and mods-enabled/ conf.modules.d/*.conf
Extra snippets conf-available/ and conf-enabled/ conf.d/*.conf

Debian splits things into "available" and "enabled" directories. Everything in -enabled is a symlink to a file in -available, and the helper commands create or remove those links for you:

Terminal
sudo a2ensite example.conf     # link sites-available/example.conf into sites-enabled
sudo a2dissite 000-default     # remove a site
sudo a2enmod rewrite headers   # enable modules
sudo a2dismod status           # disable a module
sudo a2enconf security         # enable a snippet from conf-available
sudo apache2ctl configtest     # check the syntax ("Syntax OK")
sudo systemctl reload apache2  # apply the change without dropping connections

On RHEL-family systems you edit files in conf.d/ directly, run sudo apachectl configtest (or httpd -t), and sudo systemctl reload httpd. Either way, test before you reload: a typo in a reload leaves the old configuration running, but a typo found only at restart takes the site down.

This lesson shows real Apache configuration in read-only blocks, because the site cannot run a web server. The interactive examples are small JavaScript stand-ins that reproduce Apache's merge rules so you can experiment with them. They are not Apache itself.

Directives and their contexts

A directive is one line: a name, then arguments. Names are case-insensitive, arguments often are not (paths certainly are).

APACHE
ServerName www.example.com
Listen 80
LoadModule rewrite_module modules/mod_rewrite.so
ErrorLog ${APACHE_LOG_DIR}/error.log

Every directive has a context list in the documentation: where it is allowed. The common ones are:

Put a directive in a context where it is not allowed and configtest refuses the file with a message such as "not allowed here". That is far friendlier than silently ignoring it.

Three small habits keep files readable. Use Include and IncludeOptional (the second does not fail when the pattern matches nothing) to split a large file. Use ${VAR} variables for repeated paths, which Debian fills in from /etc/apache2/envvars. And comment with # at the start of a line, never after a directive on the same line.

Containers: Directory, Files and Location

Containers limit a group of directives to part of a request. There are three families, and the difference between them matters:

Three ways to say "only here"

Directory Matches a path on disk, such as /var/www/site/admin.
Files Matches the file name, such as *.inc or .env.
Location Matches the URL path, such as /api, whatever is on disk.

Disk rules go in Directory. URL rules go in Location.

1 / 2

A realistic block that uses all three:

APACHE
<Directory "/var/www/site">
    Options FollowSymLinks
    Require all granted
</Directory>

<Directory "/var/www/site/private">
    Require all denied
</Directory>

<FilesMatch "\.(inc|bak|sql)$">
    Require all denied
</FilesMatch>

<Location "/status">
    SetHandler server-status
    Require ip 10.0.0.0/8
</Location>

<Directory> takes a real filesystem path and applies to that directory and everything below it. <Files> looks only at the last part of the name. <Location> looks at the URL the client asked for, which is why it is the right tool for things that are not files at all (a status page, a proxied /api). The Apache documentation advises against using <Location> to protect files on disk: the same file can be reached through several URLs (aliases, symlinks, a different vhost), while a <Directory> rule sticks to the file.

The merge order

When a request arrives, Apache works out which containers match, then merges them in a fixed order. For a directive set in more than one matching container, the last one merged wins. The order is:

  1. <Directory> sections (without regex) and .htaccess files, shortest path first. A .htaccess file in a directory is applied right after the <Directory> that covers it, so it overrides it (if AllowOverride permits).
  2. <DirectoryMatch> and regex <Directory ~> sections, in the order they appear in the config.
  3. <Files> and <FilesMatch>, in file order.
  4. <Location> and <LocationMatch>, in file order.

Containers of the same kind that are less specific come first, so <Directory "/var/www"> is overridden by <Directory "/var/www/site/private"> no matter which one you wrote first in the file. For the regex kinds, file order decides, so put your general rule first and the exception later. A <VirtualHost> merges after the main server config, so a vhost can override a global default.

The simulation below implements these four steps. Change the request path or the sections and watch the result move.

JS Stand-in: merging Apache sections

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the second request: the broad /var/www rule grants access, then the deeper private rule denies it again, because longer directory paths are merged later. In the third, the <Files> rule denies config.inc even though the directory is open. Real Apache has more details (for example Require directives from different containers can be combined with <RequireAll>/<RequireAny> rather than simply replaced, and some directives merge by adding rather than replacing), but "later container overrides earlier, in this order" is the model you need for day-to-day debugging.

When a rule seems to be ignored, ask "which container merged after mine?" before anything else. apachectl -S shows how virtual hosts were parsed, and apachectl -t -D DUMP_INCLUDES lists every file that got included.

Modules

Apache itself is small. Almost everything (rewriting, proxying, TLS, compression) lives in modules, loaded with LoadModule:

APACHE
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule headers_module modules/mod_headers.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so

On Debian, a2enmod rewrite writes the equivalent mods-enabled/rewrite.load symlink for you. List what is loaded with apachectl -M (static modules are compiled in, shared ones are loaded from .so files). A directive from a module that is not loaded causes an "Invalid command" error at configtest. If you want a config file to tolerate a missing module, wrap it:

APACHE
<IfModule mod_headers.c>
    Header always set X-Content-Type-Options "nosniff"
</IfModule>

Use IfModule sparingly. It hides mistakes, because a typo in the module name just makes the block silently do nothing. Prefer loading the module explicitly and letting configtest complain when it is missing. Every extra module costs memory and enlarges the attack surface, so disable what you do not use (see Hardening and Security Headers).

Choosing an MPM

The Multi-Processing Module decides how Apache handles connections. Exactly one MPM is active, and it is chosen at module-loading time:

  • prefork: one single-threaded process per connection. Memory hungry, but each request is isolated. Required by old mod_php setups that are not thread-safe.
  • worker: several processes, each with many threads.
  • event: like worker, but idle keep-alive connections are handed to a dedicated listener thread instead of tying up a worker thread. It is the default in Apache 2.4 packages and the right choice for most sites, especially with PHP-FPM.

On Debian you switch with a2dismod mpm_prefork && a2enmod mpm_event; on RHEL you edit conf.modules.d/00-mpm.conf. Tuning knobs such as MaxRequestWorkers are covered in Performance Tuning, and the broader architecture comparison is in Nginx vs Apache.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which container should you use to restrict a file that lives on disk, whatever URL it is reached through?

    Directory and Files match the filesystem, so the rule follows the file no matter which alias or URL leads to it. Location matches the URL text only.
  2. 2. Two <Directory> sections match a request: /var/www and /var/www/site/private. Which one is merged last?

    Plain Directory sections are sorted by path length, shortest first, so the deepest directory has the last word, regardless of the order in the file.
  3. 3. What does a2enmod rewrite do on Debian or Ubuntu?

    The helper links the files from mods-available into mods-enabled. Apache only picks the change up when you reload it.
  4. 4. Why is the event MPM usually preferred over prefork?

    Event does not tie up a worker thread while a connection sits idle, so the same hardware serves many more connections than one process per connection.

Summary

  • Apache reads one main file (apache2.conf or httpd.conf) that includes many smaller files; Debian uses a2ensite, a2enmod and a2enconf to manage symlinks.
  • Directives have allowed contexts; configtest tells you when one is in the wrong place.
  • <Directory> and <Files> match disk locations, <Location> matches URLs; add Match for regular expressions.
  • Sections merge in a fixed order (Directory and .htaccess, then DirectoryMatch, Files, Location) and the last one merged wins.
  • Features come from modules loaded with LoadModule; check with apachectl -M.
  • Pick the event MPM unless you have a specific reason not to.

Next: Apache Virtual Hosts.