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.