Deep Analysis of Nginx Permission Errors: Solving stat() failed (13: permission denied)

Problem Background and Error Phenomenon

When setting up Nginx as a static file server, users frequently encounter permission-related errors. According to the provided Q&A data, a typical scenario involves configuring Nginx to serve static files on Ubuntu 12.04 system, but encountering stat() failed (13: Permission denied) error during access.

The error log shows:

2014/09/10 16:55:16 [crit] 10808#0: *2 stat() "/username/test/static/index.html" failed (13: Permission denied), client:, server: localhost, request: "GET /favicon.ico HTTP/1.1", host: "domain"
2014/09/10 16:55:16 [error] 10808#0: *2 rewrite or internal redirection cycle while internally redirecting to "/index.html

The user has attempted basic permission settings, including:

chown -R www-data:www-data /username/test/static
chmod 755 /username/test/static

However, the problem persists, indicating a need for deeper understanding of the Linux file system permission model.

Deep Analysis of Permission Model

Linux file system permission control is based on three entities: user, group, and others, with each file and directory having corresponding read(r), write(w), and execute(x) permissions. For directories, execute permission has special significance: it controls whether entry into that directory is permitted.

The Nginx process typically runs as the www-data user. When Nginx needs to access the /username/test/static/index.html file, it must:

1. Be able to enter the /username directory (requires x permission)
2. Be able to enter the /username/test directory (requires x permission)
3. Be able to enter the /username/test/static directory (requires x permission)
4. Be able to read the target file (requires r permission)

This explains why even if the target directory has correct permissions, Nginx still cannot access the file if any parent directory in the path lacks execute permission.

Diagnostic and Verification Methods

To accurately diagnose permission issues, use the following command to simulate the Nginx process's access behavior:

sudo -u www-data stat /username/test/static

This command executes the stat command as the www-data user. If it returns a permission error, it confirms that Nginx cannot access the path. In the provided case, the issue likely lies with the /username directory, as user home directories typically lack execute permission for other users (including www-data).

Complete Solution

Based on the best answer analysis, the complete solution includes the following steps:

Step 1: Add User to Group

Add the www-data user to the target directory owner's group:

gpasswd -a www-data username

This command adds the www-data user to the username user's group, allowing the Nginx process to access the path through group permissions.

Step 2: Set Directory Execute Permissions

Ensure all directories in the path have execute permission for the group:

chmod g+x /username && chmod g+x /username/test && chmod g+x /username/test/static

These commands add group execute permission to each directory in the path. Note that only execute permission is needed, not read or write permissions, since Nginx only needs to be able to enter these directories.

Step 3: Verify Permission Settings

Re-run the verification command to confirm the issue is resolved:

sudo -u www-data stat /username/test/static

If the command executes successfully and returns directory information, the permission settings are correct.

Step 4: Reload Nginx Configuration

After applying changes, reload the Nginx configuration:

nginx -s reload

Other Related Considerations

Beyond basic file system permissions, other factors may affect Nginx access:

SELinux Security Module

On Red Hat-based systems (like CentOS), SELinux may prevent Nginx from accessing user home directories. As mentioned in the reference article and answer 3, you can temporarily set SELinux to permissive mode for testing:

setenforce permissive

However, in production environments, appropriate SELinux policies should be configured rather than completely disabling it.

AppArmor Profiles

On Ubuntu systems, AppArmor may restrict Nginx's access scope. Check and potentially modify the /etc/apparmor.d/usr.sbin.nginx configuration file.

Best Practice Recommendations

From a security perspective, it's not recommended to set website root directories in user home directories. Better approaches include:

• Using standard web directories like /var/www/html
• Or creating dedicated directories like /srv/www
• Ensuring directory ownership and permissions follow the principle of least privilege

In-depth Technical Principles

Understanding core concepts of the Linux permission model is crucial for solving such problems:

Nature of Directory Execute Permission: Directory execute permission controls whether the cd command can successfully enter that directory. This explains why Nginx needs execute permission for all directories in the path—it's essentially performing a series of directory entry operations.

Behavior of stat() System Call: When Nginx calls the stat() system call to check file information, the kernel checks permissions at each directory level along the path. Lack of execute permission at any level will cause stat() to fail.

User and Group Permission Inheritance: In Linux, a process's effective user ID and group ID determine which resources it can access. By adding www-data to the target user's group, we leverage the group permission mechanism to extend Nginx's access scope.

Conclusion

The Nginx stat() failed (13: Permission denied) error typically stems from lack of execute permission in some directory along the path. Through systematic permission analysis and appropriate permission settings, this problem can be effectively resolved. The key lies in understanding how the Linux permission model works and using the right tools for diagnosis and repair.

In practical operations, it's recommended to follow the principle of least privilege, granting only necessary permissions, while considering additional restrictions that system security configurations (like SELinux or AppArmor) may impose. With the complete solution provided in this article, system administrators should be able to quickly diagnose and fix Nginx permission-related issues.