Directory listing (autoindex) in Nginx - Step-by-Step Execution

Process Flow - Directory listing (autoindex)

Client sends HTTP request

↓

nginx receives request

↓

Check if request targets a directory

Yes / No↓

autoindex on?

↓

Return file or error

↓

Generate directory listing HTML

↓

Send directory listing to client

↓

Client sees directory contents in browser

When nginx gets a request for a directory, it checks if autoindex is enabled. If yes, it creates and sends a list of files in that directory as an HTML page.

Execution Sample

Nginx

location /files/ {
    autoindex on;
    root /var/www/html;
}

This config enables directory listing for /files/ URL, showing contents of /var/www/html/files/ folder.

Process Table

Step	Action	Request URL	Check Directory?	autoindex Enabled?	Response Sent
1	Client sends request	/files/	Yes (is directory)	Yes	Generate directory listing HTML
2	nginx generates listing	/files/	Yes	Yes	Directory listing HTML with file names
3	nginx sends response	/files/	Yes	Yes	Directory listing HTML sent to client
4	Client receives response	/files/	Yes	Yes	Browser shows directory contents
5	Client requests file	/files/image.png	No (is file)	N/A	Serve file image.png
6	Client requests unknown	/files/missing.txt	No (file missing)	N/A	Return 404 Not Found

💡 Execution stops after sending response to client for each request.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
Request URL	N/A	/files/	/files/	/files/	/files/
Is Directory?	N/A	True	True	True	True
autoindex Enabled?	N/A	True	True	True	True
Response Content	N/A	None	Directory listing HTML	Directory listing HTML	Directory listing HTML

Key Moments - 3 Insights

Why does nginx show a directory listing instead of a file?

Because the request URL points to a directory and autoindex is enabled, nginx generates and sends the directory listing HTML (see execution_table rows 1-3).

What happens if autoindex is off and the URL is a directory?

nginx will try to serve an index file like index.html. If none exists, it returns 403 Forbidden or 404 Not Found instead of listing files (not shown in this trace).

Why does nginx serve the file directly when the URL points to a file?

Because the request is not for a directory, nginx skips autoindex and serves the file content directly (see execution_table row 5).

Visual Quiz - 3 Questions

Look at the execution table, what response does nginx send when the client requests '/files/'?

A File content of index.html

B 404 Not Found error

C Directory listing HTML with file names

D 403 Forbidden error

💡 Hint

Check execution_table row 2 and 3 where the response is generated and sent.

At which step does nginx determine that the request URL is a directory?

A Step 1

B Step 2

C Step 4

D Step 5

💡 Hint

Look at execution_table column 'Check Directory?' to see when this check happens.

If autoindex was turned off, how would the response change for '/files/'?

A nginx would serve the file image.png

B nginx would try to serve an index file or return an error

C nginx would still send directory listing HTML

D nginx would redirect to another URL

💡 Hint

Refer to key_moments explanation about autoindex off behavior.

Concept Snapshot

nginx Directory Listing (autoindex):
- Enable with 'autoindex on;' inside location block
- When URL targets a directory, nginx lists files as HTML
- If autoindex off, nginx serves index files or errors
- Useful for browsing files on a web server
- Remember to secure directories to avoid unwanted exposure

Full Transcript

This visual trace shows how nginx handles directory listing using autoindex. When a client requests a URL that points to a directory, nginx checks if autoindex is enabled. If yes, it generates an HTML page listing the directory contents and sends it back. If the URL points to a file, nginx serves the file directly. If the file or directory does not exist, nginx returns an error like 404. This helps users browse files on the server when enabled.

Practice

1. What does the autoindex on; directive do in an nginx server block?

easy

A. It enables directory listing so users can see files in a folder via browser.

B. It disables access to all files in the directory.

C. It compresses files before sending to the client.

D. It redirects requests to another server.

Solution

1. Step 1: Understand the purpose of autoindex

   The autoindex directive controls whether nginx shows a list of files in a directory when no index file is found.

2. Step 2: Effect of autoindex on;

   Setting it to on enables directory listing, allowing users to browse files via a web browser.

3. Final Answer:

   It enables directory listing so users can see files in a folder via browser. -> Option A

4. Quick Check:

   autoindex on = directory listing enabled [OK]

Hint: autoindex on means show files in folder via browser [OK]

Common Mistakes:

• Thinking autoindex disables access
• Confusing autoindex with compression
• Assuming autoindex redirects requests

2. Which of the following is the correct syntax to enable directory listing in nginx?

easy

A. autoindex enable;

B. autoindex on;

C. autoindex true;

D. autoindex yes;

Solution

1. Step 1: Recall nginx directive syntax

   nginx directives use specific keywords; for enabling autoindex, the keyword is on.

2. Step 2: Identify correct keyword

   Only autoindex on; is valid syntax. Others like enable, true, or yes are invalid.

3. Final Answer:

   autoindex on; -> Option B

4. Quick Check:

   Correct syntax = autoindex on; [OK]

Hint: Use 'on' to enable autoindex, not 'enable' or 'yes' [OK]

Common Mistakes:

• Using 'enable' instead of 'on'
• Using 'yes' or 'true' which are invalid
• Missing semicolon at end

3. Given this nginx config snippet inside a server block:

location /files/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
}

What will the directory listing show regarding file sizes and timestamps?

medium

A. File sizes in human-readable format and timestamps in local time.

B. File sizes in bytes and timestamps in UTC time.

C. File sizes hidden and timestamps not shown.

D. File sizes in human-readable format and timestamps in UTC time.

Solution

1. Step 1: Understand autoindex_exact_size off;

   This setting shows file sizes in human-readable format (e.g., KB, MB) instead of bytes.

2. Step 2: Understand autoindex_localtime on;

   This setting shows file timestamps in the server's local time zone, not UTC.

3. Final Answer:

   File sizes in human-readable format and timestamps in local time. -> Option A

4. Quick Check:

   autoindex_exact_size off + autoindex_localtime on = human sizes + local time [OK]

Hint: Exact size off = human sizes; localtime on = local timestamps [OK]

Common Mistakes:

• Assuming sizes always show in bytes
• Thinking timestamps are always UTC
• Confusing off/on meaning for these directives

4. You enabled autoindex on; but directory listing still does not show. Which is the most likely cause?

medium

A. The server block is missing the listen directive.

B. The autoindex directive is misspelled as autoindx.

C. The directory has an index.html file present.

D. The autoindex directive must be inside http block only.

Solution

1. Step 1: Check nginx directory listing behavior

   nginx shows directory listing only if no index file (like index.html) exists in the directory.

2. Step 2: Identify why listing is not shown

   If an index file is present, nginx serves it instead of showing directory listing, even if autoindex on; is set.

3. Final Answer:

   The directory has an index.html file present. -> Option C

4. Quick Check:

   Index file present blocks directory listing [OK]

Hint: Index files override autoindex directory listing [OK]

Common Mistakes:

• Assuming misspelling causes no effect (it causes error)
• Thinking autoindex must be in http block only
• Ignoring presence of index files

5. You want to allow users to browse files in /var/www/public via nginx with directory listing enabled, showing file sizes in human-readable format and timestamps in local time. Which configuration snippet inside the server block is correct?

hard

A. location /public/ {
root /var/www/public;
autoindex on;
autoindex_exact_size on;
autoindex_localtime off;
}

B. location /public/ {
root /var/www;
autoindex off;
autoindex_exact_size off;
autoindex_localtime on;
}

C. location /public/ {
alias /var/www/public;
autoindex off;
autoindex_exact_size off;
autoindex_localtime on;
}

D. location /public/ {
root /var/www;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}

Solution

1. Step 1: Choose correct root and enable autoindex

   Using root /var/www; with location /public/ serves files from /var/www/public. autoindex on; enables directory listing.

2. Step 2: Set human-readable sizes and local timestamps

   autoindex_exact_size off; shows sizes in human-readable format, and autoindex_localtime on; shows timestamps in local time.

3. Final Answer:

   location /public/ { root /var/www; autoindex on; autoindex_exact_size off; autoindex_localtime on; } -> Option D

4. Quick Check:

   Correct root + autoindex on + human sizes + local time = location /public/ { root /var/www; autoindex on; autoindex_exact_size off; autoindex_localtime on; } [OK]

Hint: Use root with path prefix; autoindex on + exact_size off + localtime on [OK]

Common Mistakes:

• Using alias incorrectly with root paths
• Turning autoindex off disables listing
• Setting exact_size on shows bytes, not human sizes