Nginx tutorial: getting started with nginx.conf

NGINX tutorial: the basic commands and configurations

In our basic article, we summarised what nginx is, as well as how to install and set it up on your system. In the following tutorial, we provide you with an overview of the basic commands and configuration options of the modern web server software.

Contents

The central control unit: nginx.conf

Nginx is event-based and therefore works differently to Apache. Individual requests are not classified as new work processes (for which all modules have to be loaded), but rather as events. These events are divided into existing work processes, which are maintained by the primary main process. The nginx.conf configuration file defines the number of work processes that ultimately exist, as well as how the server requests (i.e. the events) are divided. You can find them in these files /usr/local/nginx/conf, /etc/nginx or /usr/local/etc/nginx.

Manage processes and adopt new configurations

Nginx starts automatically after installation, but you can initiate it by using the following command:

sudo service nginx start

Once the web server software is running, you can manage it by addressing the processes (primarily the main process) with the –s parameter and a specific signal. The syntax of the corresponding commands is relatively unspectacular:

sudo nginx -s signal

For 'signal', you have the following four possibilities:

stop: nginx is terminated immediately.
quit: nginx is terminated after all active requests have been answered.
reload: the configuration file is reloaded.
reopen: the log-files are restarted.

The reload option, which is used to reload the configuration file, is a good way to make changes without having to terminate the webserver software and subsequently re-start it. In any case, to accept the changes you have to decide whether you want to completely re-start the server or whether you simply want an nginx reload. If you choose the latter option and have carried out the command below, the main process receives the instruction to apply changes to the nginx.conf file:

sudo nginx -s reload

For this purpose, the syntax’s accuracy is first checked. If there’s positive feedback, the new settings enable the main process to start new work processes and simultaneously to stop old processes. If the syntax can’t be validated, the old configuration status is retained. All active workflows are terminated as soon as all active requests have been processed.

In addition, you can also target nginx processes using tools such as kill. All you need is the corresponding process ID, which can be found in the nginx.pid file in the /usr/local/nginx/logs directory or alternatively in the /var/run directory. If, for example, the main process has the ID 1628, it can be terminated with the kill and quit signal in the sequence.

sudo kill -s quit 1628

You can also use the service program, ps, to display a list of all nginx processes that are running:

sudo ps -ax | grep nginx

How to regulate the delivery of static content

You most likely use your web server to deliver files such as images, videos, or static HTML content. In order to be more efficient it’s a good idea to choose different local directories for different content types. Start by creating a sample directory /data/html and place an example HTML document index.html there as well as create a folder /data/images with some sample images.

For the next step, the two directories must be entered into the configuration file by holding both in the server block directive, which in turn is the sub-directive of the HTTP block directive. Various instructions are already set by default, which you can first switch off using (off). Then simply create a separate server block statement:

http {
  server {
  }
}

In this server block, you should specify the two directories that contain images and HTML documents. The corresponding result is as follows:

server {
  location / {
    root /data/html;
  }

  location /images/ {
    root /data;
  }
}

This configuration is a default setting for a server that listens on port 80 and is accessible through the local host. All requests whose URIs start with /images/ will now request files from the /data/images directory. If an appropriate file does not exist, an error message will appear. All nginx events whose URIs do not begin with /images/, are passed to the /data/html directory.

Don’t forget to reload or restart nginx in order to apply the changes.

Setting up a simple nginx proxy server

Nginx is very often used (instead of the actual server) to run a proxy server for receiving incoming requests. It filters them according to various criteria, forwards them, and delivers the respective responses to clients. Cache proxies are particularly popular. They directly deliver locally stored static content and only forward all further requests to the server. Firewall proxies are also very common, which filter out unsafe or unwanted connections. The following is an example of a cache proxy, which retrieves requested images from the local directory and forwards all further requests to the web server.

For the first step, you need to define the main server in the nginx.conf:

server {
  listen 8080;
  root /data/up1;

  location / {
  }
}

In contrast to the previous example, the list directive is used since port 8080 (rather than the standard port) is to be used for incoming requests. You should also create the target directory /data/up1 and file the index.html page there.

Secondly, the proxy server is defined along with its function of being able to deliver image content. This is carried out by using the ProxyPass directive including details of the main server protocol (http), name (localhost), and port (8080):

server {
  location / {
    proxy_pass http://localhost:8080;
  }

  location ~ \.(gif|jpg|png) $ {
    root /data/images;
  }
}

The second location-block instructs the proxy server to answer all the requests itself if their URIs end with typical image files such as .gif, .jpg, and .png by retrieving the corresponding content from the local /data/images directory. All other requests are forwarded to the main server. As with the previous settings, save your image proxy via reload signal to the main process or by restarting nginx. You can find further directives for complex proxy settings in the official nginx online manual.