The Configuration Model: web.config, applicationHost.config & Configuration Inheritance

Web Servers Fundamentals Chapter 3 introduced the shape of IIS's own configuration model — applicationHost.config machine-wide, web.config per-directory — and noted it sits structurally closer to Apache's own .htaccess philosophy than to Nginx's single centralized file. What it didn't cover is how a setting actually gets resolved once more than one web.config exists in the same directory chain, or what stops a subdirectory from overriding something the machine administrator deliberately locked down. That's this chapter.

The Configuration Hierarchy

Every configurable setting in IIS lives somewhere in a layered hierarchy of XML files, read in a fixed order from the most general to the most specific:

A request to /api/admin/users doesn't just read the deepest web.config in isolation — IIS reads every file in the chain above it, starting at applicationHost.config and walking down through each web.config in turn, merging settings as it goes. This is precisely the same directory-context idea Apache In Depth Chapter 3 covers for .htaccess — the deepest applicable file wins for any setting it actually specifies, and any setting it doesn't specify simply falls through to whatever the level above it already resolved to.

How Merging Actually Works: Add, Remove, Clear

For simple scalar settings — a boolean, a numeric limit — a more specific web.config value straightforwardly replaces the less specific one. Collection-based settings (a list of default documents, a list of MIME types, a list of modules) behave differently, because IIS's configuration schema exposes three explicit collection actions rather than silently overwriting the whole list:

<add> appends an item to whatever the collection already inherited from the level above. <remove> takes out one specific inherited item by name, leaving the rest. <clear> discards everything inherited so far and starts the collection fresh at that point in the hierarchy — used here before adding this directory's own two default documents, so this subdirectory's list isn't quietly appended onto whatever the site root or machine level already had configured.

Locking Sections: overrideModeDefault and allowOverride

Inheritance alone doesn't stop a subdirectory from overriding something a machine administrator never wanted overridden at all — that's a separate, deliberate lock, configured at the machine level:

Each configuration section — system.webServer/authentication, system.webServer/defaultDocument, and so on — carries its own overrideModeDefault, set in applicationHost.config's own <sections> declarations. Allow means any web.config further down the hierarchy is free to override that section. Deny means it isn't — a web.config that attempts to set a locked section produces an actual HTTP 500.19 configuration error rather than silently being ignored. Several security-sensitive sections ship Deny by default precisely so that an application deployed by someone without machine-level access can't quietly re-enable something an administrator locked down — system.webServer/authentication among them, which is exactly why Chapter 8's Windows Authentication material has to be configured at a level with the necessary permission, not casually from an arbitrary application's own web.config.

Overriding a Locked Section From the Machine Level: <location>

A locked (Deny) section isn't necessarily fixed identically for every site forever — an administrator with access to applicationHost.config itself can still grant one specific site or path a different value, using a <location> tag:

This is how a locked, Deny-mode section still ends up different for one specific site or subdirectory without unlocking it for every application on the server — the override lives entirely inside applicationHost.config, scoped by path, rather than inside that site's own web.config. The distinction that matters: a <location> block is still machine-level configuration, written by whoever has access to applicationHost.config itself — it is not a loophole an application deployer can reach from their own web.config.

Resolution Order, Put Together

1. IIS Manager or a config tool checks applicationHost.config's section declarations for overrideModeDefault (and any <location> override) — this determines whether a lower-level web.config is even permitted to touch that section
2. Reading proceeds top-down: applicationHost.config, then each web.config from the site root down to the requested directory
3. Scalar settings from a deeper file simply replace shallower ones
4. Collections accumulate via <add>/<remove> unless a <clear /> resets them at that level
5. The final, fully-merged configuration for that specific request path is what IIS actually applies

Hands-On Exercises