Precedence of nested Include and IncludeOptional directives

Question

Achieving a repeatable development environment in Apache HTTP Server often requires separating core logic from environment-specific overrides using Include and IncludeOptional directives. This modular approach allows for flexible configuration fragments across different deployment stages.

A challenge arises when managing complex directory structures where configuration files contain nested references or overlap. Since Apache processes directives linearly, the sequence of these statements determines the final state of module settings and server behavior.

When a main configuration file utilizes IncludeOptional to load a directory that contains further nested Include statements, the interaction between optional and mandatory loading can create uncertainty regarding the final precedence of conflicting directives.

Does the linear processing order persist across nested include levels regardless of whether the parent was loaded via IncludeOptional?
  Which directive takes precedence when the same configuration parameter is defined in both a mandatory Include file and an optional override file loaded later in the sequence?

Tasadduq Burney · Answer

Answer to the Questions
1. Does the linear processing order persist across nested include levels regardless of whether the parent was loaded via IncludeOptional?
Yes. Apache processes directives strictly in the order they appear in the configuration file. Nested Include or IncludeOptional directives are parsed after the outer directive, so the innermost file can override settings defined earlier. The fact that the parent was loaded via IncludeOptional only suppresses an error if the file is missing; it does not alter the ordering.
2. Which directive takes precedence when the same configuration parameter is defined in both a mandatory Include file and an optional override file loaded later in the sequence?
The later definition wins. When a parameter is set in multiple included files, the value from the file that is parsed last overrides earlier values. This applies to both Include and IncludeOptional files.
Confirmed Facts

Both Include and IncludeOptional are parsed in the order they appear.
Nested directives inside any context (VirtualHost, Directory, IfModule, etc.) follow the same ordering rule.
The last occurrence of a directive wins, unless a module merges values (e.g., AllowOverride may accumulate).
Apache 2.4.x and later behave this way; earlier 2.2 releases differ in how IncludeOptional is handled.

Practical Verification Steps

Create two fragment files:
# base.conf
ErrorLog /var/log/apache2/error.log

# override.conf
ErrorLog /tmp/overridden.log

In httpd.conf (or the appropriate virtual host file), add:
Include /etc/apache2/conf.d/base.conf
IncludeOptional /etc/apache2/conf.d/override.conf

Reload Apache:
sudo systemctl reload apache2

Trigger an error (e.g., request a non‑existent page) and check which log file receives the entry. It should be /tmp/overridden.log.

Remove override.conf or comment its IncludeOptional line, reload, and verify that errors now go to /var/log/apache2/error.log.

What to Check Next
If you observe unexpected behavior, confirm the following:

Which Apache version are you running? (2.4.x vs 2.2)
Are the conflicting directives inside the same context (e.g., both inside the same <VirtualHost>)?
Does the directive merge values rather than replace them (some modules behave this way)?

Providing one of these details will help narrow down any edge‑case interactions.

Precedence of nested Include and IncludeOptional directives

1 answer

1 question comment

Answer to the Questions

Confirmed Facts

Practical Verification Steps

What to Check Next

Your perspective belongs here.