In an nginx `location` block, what is the difference between the `root` and `alias` directives, and what filesystem path does `location /images/ { alias /data/pics; }` produce for a request to /images/logo.png?

## Two directives, two different mental models Both `root` and `alias` answer "where on disk does this URI live?", but they compose differently with the location that selected them. **`root` = document root.** Nginx takes the directive's value and appends the **full, normalized request path**: ```nginx location /images/ { root /data; # /images/logo.png -> /data/images/logo.png } ``` The `/images/` segment survives, because `root` knows nothing about which location matched. This is why `location /images/ { root /data/images; }` produces `/data/images/images/logo.png` and a puzzling 404 — a mistake made constantly by people who read `root` as "this directory". **`alias` = substitution.** Nginx removes the part of the path that the location matched and appends only what is left: ```nginx location /images/ { alias /data/pics/; # /images/logo.png -> /data/pics/logo.png } ``` Use `alias` when the URL path and the disk path genuinely differ; use `root` when the tail of the disk path repeats the URL prefix. ## The off-by-one that gives the leaf its reputation ```nginx location /images/ { alias /data/pics; # note: no trailing slash } ``` Substitution is textual. Nginx replaces the matched `/images/` with `/data/pics` and appends `logo.png`, yielding `/data/picslogo.png`. There is no error at startup, `nginx -t` passes, and the only symptom is a 404 for files that exist. The error log is the giveaway: it records the *constructed* path, so you see `open() "/data/picslogo.png" failed (2: No such file or directory)` and the bug names itself. The discipline: **the location prefix and the alias value must agree about the trailing slash.** Both with, or both without. ## The version of this bug that is a security problem Now drop the slash on the *location* side instead: ```nginx location /static { alias /var/www/static/; } ``` The prefix `/static` also matches a request for `/static../secrets/db.yml`. Nginx normalizes `.` and `..` only as whole path segments, and `static..` is not one, so the path survives normalization intact. Substitution then yields `/var/www/static/../secrets/db.yml`, which the kernel resolves to `/var/www/secrets/db.yml`. This is the well-known nginx alias traversal misconfiguration, and the fix is the same slash discipline: write `location /static/ { alias /var/www/static/; }`. ## Alias inside a regex location When the location is a regular expression, there is no fixed prefix to strip, so the alias value should be built from captures: ```nginx location ~ ^/users/(?<uid>\d+)/avatar$ { alias /data/avatars/$uid.png; } ``` Without a capture, an alias under a regex location is guesswork. ## Choosing between them - If the last segments of the disk path equal the URL prefix (`/images/` under `/data/images`), use `root /data;` — fewer moving parts and no slash trap. - If they differ (`/images/` served from `/data/pics/`), you need `alias`. - `root` may be set at `http`, `server` or `location` level and inherits downward; `alias` is meaningful only inside a `location`, because its whole definition is "replace what this location matched". ## Diagnosing it in ten seconds Never reason about the path in your head. Read `error_log` at `error` level — nginx prints the exact `open()` path it tried. A doubled segment (`/data/images/images/...`) means `root` where you meant `alias`; a fused segment (`/data/picslogo.png`) means a missing trailing slash on `alias`; a path climbing out of the tree means a missing trailing slash on the `location`.