Beginner’s Guide
Start, stop, and reload configurationConfiguration file structureServe static contentConfiguring a simple proxy serverConfiguring the FastCGI proxy This
guide provides a basic introduction to nginx and describes some simple tasks that can be performed with it. nginx is assumed to be already installed on the reader machine. If not, see the nginx Installation page. This guide describes how to start and stop nginx, and reload its configuration, explains the structure of the configuration file, and describes how to configure nginx to serve static content, how to configure nginx as a proxy server, and how to connect it with a FastCGI application.
Nginx has a master process and several worker processes. The main purpose of the master process is to read and evaluate the configuration and maintain the worker processes. Workflow processes perform the actual processing of requests. nginx employs an event-based model and operating system-dependent mechanisms to efficiently distribute requests across worker processes. The number of worker processes is defined in the configuration file and can be set for a given configuration or automatically adjusted to the number of available CPU cores (see worker_processes).
The way nginx and its modules work is determined in the configuration file. By default, the configuration file is named nginx.conf and is placed in the /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx directory.
Starting, stopping, and reloading settings
To start nginx, run the executable file. Once nginx is started, it can be controlled by invoking the executable with the -s parameter. Use the following syntax
: signal
Where the signal can be one of the
following: stop —
fast shutdown exit — successful shutdown
reload — reload configuration file reopen
- —
- reopen
log files
For example, to stop nginx processes waiting for worker processes to finish servicing current requests, you can run the following command:
Changes made to the configuration
file will not be applied until the command to reload the configuration is sent to nginx or restarted. To
reload the configuration, run:
Once the master process receives the signal to reload the configuration, it checks the validity of the syntax of the new configuration file and tries to apply the configuration provided in it. If this is successful, the master process starts new worker processes and sends messages to the old worker processes, prompting them to close. Otherwise, the master process rolls back the changes and continues working with the previous configuration. Processes of old workers, who receive a command to shut down, stop accepting new connections and continue to serve current requests until all those requests are met. After that, the old worker processes the output.
A signal can also be sent to nginx processes with the help of Unix tools like the kill utility. In this case, a signal is sent directly to a process with a particular process ID. The process ID of the nginx master process is written, by default, to nginx.pid in the /usr/local/nginx/logs or /var/run directory. For example, if the ID of the master process is 1628, to send the QUIT signal that results in the successful shutdown
of nginx, run: To
get the list of all running nginx processes, the ps utility can be used, for example, as follows:
For more information on sending signals to nginx, see nginx control.
Configuration file structure
nginx consists of modules that are controlled by policies specified in the configuration file. Policies are divided into simple policies and block policies. A simple directive consists of the name and parameters separated by spaces and ends with a semicolon (;). A block directive has the same structure as a simple directive, but instead of the semicolon it ends with a set of additional instructions surrounded by curly braces ({ and }). If a block directive can have other directives inside curly braces, it is called context (examples: events, http, server, and location).
Policies placed in the configuration file outside of any context are considered in the main context. http policies and events reside in the primary context, the server in http, and the location on the server.
The remainder of a line after the # sign is considered a comment.
Serve static content
An important task of the web server is to serve files (such as images or static HTML pages). You will implement an example where, depending on the request, files will be served from different local directories: /data/www (which can contain HTML files) and /data/images (which contains images). This will require editing the configuration file and configuring a server block within the http block with two location blocks.
First, create the /data/www directory and place
an index.html file with any text content in it and create the /data/images directory and put some images in it
.
Then open the configuration file. The default configuration file already includes several examples of the server block, mostly commented out. For now, comment out all of these blocks and start a new server block
:
Generally, the configuration file can include multiple server blocks distinguished by the ports they listen on and by the names of the servers. Once nginx decides which server processes a request, it tests the URI specified in the request header against the location policy parameters defined within the server block.
Add the following location block to the
server block:
This location block specifies the “/” prefix compared to the request URI. For matching requests, the URI will be added to the path specified in the root policy, that is, to /data/www, to form the path to the requested file on the local file system. If there are multiple matching location blocks, nginx selects the one with the longest prefix. The above location block provides the shortest prefix, length one, so only if all other location blocks do not provide a match, will this block be used.
Next, add the second
location block: it
will be a match for requests that start with /images/ (location/ also matches such requests, but has a shorter prefix).
The resulting configuration of the server block should look like this:
This is already a working configuration of a server that listens on standard port 80 and is accessible on the local machine in http://localhost/. In response to requests with URIs that begin with /images/, the server will send files from the /data/images directory. For example, in response to the http://localhost/images/example.png request, nginx will send the file /data/images/example.png. If such a file does not exist, nginx will send a response stating the 404 error. Requests with URIs that do not begin with /images/ will be mapped to the /data/www directory. For example, in response to the http://localhost/some/example.html request, nginx will send the /data/www/some/example.html file.
To apply the new settings, start nginx if it has not yet started or send the reload signal
to the nginx master process, running:
Setting up
a simple proxy server One of the
frequent uses of nginx is to configure it as a proxy server, which means that a server that receives requests, passes them to proxy servers, It retrieves responses from them and sends them to customers.
We’ll set up a basic proxy server, which serves image requests with files from the local directory and sends all other requests to a proxy server. In this example, both servers will be defined in a single nginx instance.
First, define the proxy server by adding one more server block to the nginx configuration file with the following content:
This will be a simple server that listens on port 8080 (previously, the listening policy has not been specified since standard port 80 was used) and maps all requests to the /data/up1 directory on the local file system. Create this directory and place the file .html index in it. Note that the root policy is placed in the context of the server. This root policy is used when the location block selected to serve a request does not include its own root policy.
Then, use the server settings in the previous section and modify them to make them a proxy server configuration. In the first location block, place the proxy_pass directive with the protocol, name, and port of the proxy server specified in the parameter (in our case, it is http://localhost:8080):
We will modify the second location block, which currently assigns requests with the /images/ prefix to files under the /data/images directory, to match requests for images with typical file extensions. The modified location block looks like this:
The parameter is a regular expression that matches all URIs ending in .gif, .jpg, or .png. A regular expression must be preceded by ~. The corresponding requests will be assigned to the /data/images directory.
When nginx selects a location block to serve a request, it first checks the location policies that specify prefixes, remembers the location with the longest prefix, and then checks the regular expressions. If there is a match to a regular expression, nginx chooses this location or else chooses the one that was recalled above.
The resulting configuration of a proxy server will
look like this:
This server will filter requests that end with .gif, .jpg, or .png and map them to the /data/images directory (by adding URIs to the root policy parameter) and pass all other requests to the previously configured proxy server
.
To apply a new configuration, send the recharge signal to nginx as described in the previous sections.
There are many more policies that can be used to further configure a proxy connection.
Configuring FastCGI Proxying nginx
can be used to route requests to FastCGI servers running applications built with various frameworks and programming languages such as PHP
.
The most basic configuration of nginx to work with a FastCGI server includes the use of the fastcgi_pass policy instead of the proxy_pass directive, and fastcgi_param directives to set parameters passed to a FastCGI server. Suppose the FastCGI server is reachable at localhost:9000. Based on the proxy settings in the previous section, replace the proxy_pass policy with the fastcgi_pass policy and change the parameter to localhost:9000. In PHP, the SCRIPT_FILENAME parameter is used to determine the script name and the QUERY_STRING parameter is used to pass the request parameters. The resulting configuration would be
:
This will configure a server that will route all requests except static image requests to the proxy server operating on localhost:9000 via the FastCGI protocol.