Working With Nginx

The first two articles in the series have given an overview and also talked about the essential modules for Nginx. This tutorial will help you get started using Nginx by guiding you through some basic techniques on managing configuration files and setting up basic parameters in the configs. 

Splitting Configuration Files

After Nginx is installed, the /etc/nginx/ directory will have the following content:

• 
  nginx.conf: the primary configuration file.


• 
  conf.d: used for things like module loading and for things that are not specific to a single virtual host.


• 
  sites-available: storing all virtual host configurations, even if they're currently not enabled.


• 
  sites-enabled: all the sites that are enabled (symlinks to files in the sites-available folder).


• 
  mime.types: maps filename extensions to MIME types of responses.

This sites-* folder workflow makes things a little more organized. In case of multiple web sites, i.e. virtual hosts, each virtual host gets its own configuration file. sites-available can contain all the virtual host configuration files, while the ones that are enabled can be symlinked from sites-enabled.

This configuration is the default when you install Nginx. You can see how include has allowed the inclusion of external configuration files. If there are errors in any of these included files, Nginx will fail to load.

Multiple Virtual Hosts

Nginx, like any other web server, allows you to configure more than one virtual host.

# sites-enabled/example.com.conf

server {
  listen 80;
  # both address and port, or only address or only port.
  server_name example.com www.example.com;
  # names of a virtual server. Can use wildcard & regular expressions.
  access_log /var/log/nginx/example_com_access.log;
  error_log /var/log/nginx/example_com_error.log;
  
  # sets configuration depending on a request URI.
  location / {
    root /var/www/www.example.com;
    index index.html index.htm;
  }
}

This is done via the server block. The listen directive describes the port on which the web server is listening and the server_name directive lists all server names. Inside location, you can define how the virtual host works.

Reloading Nginx

The process ID of the master Nginx process is written to a file as defined by the pid directive, e.g. pid /var/run/nginx.pid;. This master process supports the following signals:

In order to reload Nginx, you can run kill -HUP <PID nginx master proc>. 

Individual worker processes can also be controlled via signals.

Nginx in Debug Mode

For this, you will need to compile Nginx with the debug flag (--with-debug). After doing that, it is possible to debug connections from specific addresses with the debug_connection directive.

error_log /var/log/nginx/errors;
events {
  debug_connection   192.168.1.18;
}

When asking for help with Nginx, be sure to share the output of nginx -V, full configuration and the debug log.

404 and Other Error Pages

This is achieved with the help of an error_page directive. It defines the resource that will be shown for the error.

# 1
error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

# 2
error_page 404 =200 /empty.gif;
# change the response code to another using the “=response”

error_page 404 =301 https://example.com/notfound.html;
# use redirects for error processing


# 3
# error processing with a named location
location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass https://backend;
}

There is also a directive called recursive_error_pages which enables doing several redirects using the error_page directive. For example:

error_page 400 404 /404.html;

recursive_error_pages on; 

location ~* ^/(404\.html|500\.html|503\.html)$ { 
    log_not_found off;
    # Disables logging of errors about not found files.
    
    error_page 404 = @default; 
} 

location @default { 
    log_not_found on; 
    root /var/www/default; 
}

Auto-Indexing Directory

A request where the index file is not found is routed to this module (ngx_http_autoindex_module). [Example: Local Network sharing]

location / {
    root /var/www/localdropbox;
    autoindex on;
    # Enables or disables the directory listing output.
    
    autoindex_exact_size off;
    # Exact file size vs rounding them to nearest KB, MB, GB.
    
    autoindex_format html;
    # format of a directory listing. XML, JSON, JSONP possible.
    
    autoindex_localtime on;
    # local TZ vs UTC.
  }

Size of File Uploads

"Request entity too Large" (413) is a common error message, when the user is trying to upload a file. This file size is controlled by a Nginx configuration variable:

variable client_max_body_size 10M; # M stands for megabytes.

This sets the maximum size of the client request body, specified in the “Content-Length” request header. To have some user feedback for these uploads, you can also use nginx-upload-progress-module. You need to append an X-Progress-ID, which helps uniquely identify the file being uploaded.

Cookies

Nginx has a very useful and nifty functionality of serving cookies for identifying end users. In a situation in which you don't want to employ external analytics, the ngx_http_userid_module module can fill in by serving cookies.

userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';

By enabling this module, the variables $uid_reset, $uid_got and $uid_set become available. These can help you write even more intricate rewrite rules.

These steps should definitely get you started on your path to using Nginx more productively. 

Additional Resources

1. 
   How nginx processes a request
   
   


2. Nginx Debugging