Before we begin, whenever you run into some kind of problem with Nginx, you should make sure to follow the recommendations given in the following sections, as they are generally a good source of solutions.
A lot of errors that Nginx administrators are faced with are caused by invalid access permissions. At two stages, you are offered to specify a user and group for the Nginx worker processes to run:
When configuring the build with the
configurecommand, you are allowed to specify a user and group that will be used by default (refer to Chapter 1, Downloading and Installing Nginx).In the configuration file, the
userdirective allows you to specify a user and group. This directive overrides the value that you may have defined during theconfigurestep.
If Nginx is supposed to access files that do not have the correct permissions, in other words, which cannot be read (and by extension cannot be written, for directories that hold temporary files for example) by the specified user and group, Nginx will not be able to serve files correctly.
A common mistake is often made by administrators showing a little too much self-confidence. After having modified the configuration file (often without a backup), they reload Nginx to apply the new configuration. If the configuration file contains syntax or semantic errors, the application will refuse to reload. Even worse, if Nginx is stopped (for example, after a complete server reboot) it will refuse to start at all. In all of those cases, remember to follow these recommendations:
Always keep a backup of your working configuration files in case something goes wrong
Before reloading or restarting Nginx, test your configuration with a simple command—
nginx -tto test your current configuration files or runnginx -t -c /path/to/config/file.confReload your server instead of restarting it—preferring
service nginx reloadoverservice nginx restart(nginx -s reloadinstead ofnginx -s stop && nginx), as it will keep existing connections alive and thus won't interrupt ongoing file downloads
You would be surprised to learn how often this happens: the most complicated situations have the simplest solutions. Before tearing your hair out, before rushing to the forums or IRC asking for help, start with the most simple of verifications.
You just spent two hours creating your virtual host configuration. You've saved the files properly and fired up your web browser to check the results. But did you remember that one additional step? Nginx, unlike Apache, does not support on-the-fly configuration changes in .htaccess files or similar. So take a moment to make sure you did reload Nginx with service nginx reload, /etc/init.d/nginx reload or /usr/local/nginx/sbin/nginx -s reload without forgetting to test your configuration beforehand!
There is usually no need to look for the answer to your problems on the Internet. Chances are the answer is already given to you by Nginx in the logfiles. There are two variations of log files you may want to check. First, check the access logs. These contain information about requests themselves: the request method and URI, the HTTP response code issued by Nginx, and more, depending on the log format you defined.
More importantly for troubleshooting, the error log is a goldmine of information. Depending on the level you defined (see error_log and debug_connection directives for more details), Nginx will provide details on its inner functioning. For example, you will be able to see request URI translated to actual file system path. This can be a great help for debugging rewrite rules. The error log should be located in the /logs/ directory of your Nginx setup, by default /usr/local/nginx/logs.