Apache HTTPD / Request identity and configuration foundations / Lesson 4

URI space, DocumentRoot, Alias, and filesystem identity

Trace a request path to the selected resource without confusing URL names with disk paths.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish filesystem Directory scope from URL Location scope.
Explain Alias behavior and the separate authorization required for its target.

A URL path is not a filesystem path

A request URI belongs to web space. A static-file mapping can turn its path into a filesystem location under DocumentRoot, while Alias, rewriting, proxying, or another handler can select a different resource. Parcel’s /docs/ route can map outside its main document tree without making that target automatically authorized. Keep query strings separate from path mapping. A URL beginning with / does not refer to the host filesystem root, and a Directory section matches a filesystem scope rather than the literal browser address.

Read the mapping and access decisions separately

The fragment below maps a synthetic URL prefix to a synthetic Unix directory and gives an explicit public-read authorization illustration for that target. It is not loaded, creates no directory, and changes no permissions. mod_alias and mod_authz_core support and a suitable actual configuration would be required. Matching trailing slashes matter to the prefix contract. The example deliberately says nothing about private files elsewhere; it is not a policy to expose arbitrary directories outside DocumentRoot.

apache A non-runnable Alias and target-scope fragment

Alias "/docs/" "/lab/shared/docs/"
<Directory "/lab/shared/docs">
    Require all granted
</Directory>

The paths are declared lab inputs. The fragment does not establish filesystem existence, operating-system access, symbolic-link policy, MIME handling, or safe content. No server or file operation occurs.

Mapping does not settle access or handler behavior

After identifying the effective resource, review applicable authorization, filesystem traversal and read requirements, platform security controls, Options, and handler selection. A mapped file can still be denied or processed dynamically under another configuration. A filesystem path can also be affected by symbolic links and platform case rules. Do not fix a 403 by broadening every directory or making files world-writable. Identify the exact failing operation and policy layer with the owner’s bounded evidence. The correct remedy may be a mapping or scope correction rather than more privilege.

Show one declared prefix transformation

The complete local program below maps one known normalized teaching path through one prefix rule. It is not Apache’s URL decoder, path canonicalizer, traversal defense, alias matcher, or filesystem resolver. The input contains no encoded separators, dot segments, query, or special platform syntax. Real mapping and security behavior must use the supported server contract and actual configuration. The model’s only purpose is showing why the target differs from DocumentRoot and why target-specific policy matters.

python A limited synthetic prefix mapping

uri = "/docs/guide.html"
prefix = "/docs/"
target = "/lab/shared/docs/"
assert uri.startswith(prefix)
mapped = target + uri[len(prefix):]
print(mapped)
print("mapping only; no file access")

Expected output

/lab/shared/docs/guide.html
mapping only; no file access

The code concatenates a declared safe example only and must not be used as a general path-security validator. No file is opened and no URL is requested.

Follow the actual selected path

For missing or wrong content, first establish the selected virtual host and effective mapping rule. Then compare the declared URI, expected target, access scope, and handler with retained evidence. Redirect and internal mapping have different client-visible behavior: a redirect asks the client for another URL, while Alias serves a selected local resource under the original URL. A reverse proxy is another route entirely. Changing DocumentRoot cannot repair an Alias that intentionally bypasses it. Keep mapping decisions narrow and test representative slash and subpath cases in a separately authorized validation process.

Common errors and fixes

A Location section is treated as a filesystem directory rule.

Why it happens: Web space and disk space were confused.
How to fix it: Use the appropriate documented container for the intended resource boundary.
Prevent it next time: Draw URI and filesystem identities separately.

An Alias target is assumed accessible because the URL matches.

Why it happens: Mapping was substituted for authorization and operating-system access.
How to fix it: Review the target’s applicable policy and required read or traversal operation.
Prevent it next time: Keep mapping and access evidence distinct.

String concatenation is reused as a production traversal defense.

Why it happens: A limited teaching example was mistaken for secure URL resolution.
How to fix it: Use supported canonicalization and server policy rather than an ad hoc resolver.
Prevent it next time: State model input restrictions and test actual mapping through an authorized process.

Check your understanding

1. Does changing DocumentRoot necessarily change the target of /docs/ in the shown Alias?

Show worked solution

No. The Alias selects its own target for that prefix under the declared configuration. Review Alias and its target policy separately. A default document-tree change does not automatically rewrite every alternative mapping.

2. Why can a correctly mapped file still return a denial?