The nginx alias directive replaces the part of a request URI that matched a location with a filesystem path. It is a concise way to map a URL prefix to a directory. It also requires the location, path, and filesystem permissions to agree about where the mapped file is allowed to come from.
The mapping is explicit
The nginx core module documents alias as a replacement for the specified location. In a location ending with /, the mapping can look like this:
location /assets/ {
alias /srv/www/assets/;
}
The trailing slashes make the prefix relationship visible. When the location is a regular expression, the alias value is a complete file path and usually needs a capture from the expression. When the location matches the last part of the alias value, the documentation recommends using root instead.
That recommendation is a warning about path construction. root appends the URI to a document root. alias replaces the matched location with a different path. A mismatch in slashes or a location that matches more of the URI than the administrator intended can produce a path outside the expected directory.
Match rules come first
nginx selects a location using prefix and regular-expression rules, with the exact order and ^~ behavior defined by the location directive. An alias is only reached after that selection. Review the complete server and location blocks, not the alias line alone.
A short prefix such as location /files can match /files, /files/, and /files-secret depending on the exact configuration. The resulting alias may then use a different suffix than the designer expected. Use a trailing slash where the directory boundary matters, and test with the same URI normalization the application receives.
merge_slashes is on by default and normalizes repeated slashes in a URI. Other modules, upstream proxies, and encoded path handling can change the request before nginx evaluates it. A request that looks harmless in a browser may not be the URI the filesystem layer sees.
Filesystem controls still apply
An alias does not grant the nginx worker access to files that its user cannot read. Keep the served directory owned by a dedicated account and remove secrets, source maps, backups, and configuration files from the document tree. The worker should not run as root.
disable_symlinks can stop nginx from following symbolic links in a location. That setting is useful when users can create links inside a served directory. It is not a complete substitute for directory permissions, and it has performance and operational effects. Test the application's legitimate links before enabling it broadly.
For uploads or generated files, separate the public directory from the application's private storage. Do not use an alias that exposes the application root and rely on hidden-file rules to protect credentials. A future package update can add a new sensitive file below that root.
Test path normalization
Use a staging server and non-sensitive files. Request the intended path, the path with repeated slashes, a path with encoded characters, and a missing suffix. Log the selected location and the resulting file path. A local request with curl --path-as-is helps show whether the client or an intermediary is normalizing the path first.
Inspect the nginx configuration before deployment:
nginx -T
The dump associates the effective alias with its surrounding location. It is more useful than reading a single include file. Pair the configuration review with a filesystem inventory of every directory that an alias can reach.
Monitor the boundary
Log the request URI, the selected server, the response status, and the request length. Do not log authentication secrets or full query strings. Alert on unexpected 200 responses from a location that should serve only a narrow file set. A path traversal attempt may produce 400 or 403 responses, while a misconfiguration can produce a successful read with an ordinary-looking path.
If a path is exposed, preserve logs and file hashes, then correct the location and alias mapping. Rotate any credentials stored below the exposed root. The fix should include a test that demonstrates the intended URI prefix and a denied request outside it.
An alias is a mapping, not a security boundary. The review has to connect the requested URL, the location that matched, the filesystem path that resulted, and the account that can read it.