Beginner’s Guide
This guide gives a basic introduction to nginx and describes some simple tasks that can be done with it. It is supposed that nginx is already installed on the reader’s machine.If it is not, see the Installing nginx 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 set up nginx to serve out static content, how to configure nginx as a proxy server, and how to connect it with a FastCGI application.
nginx has one master process and several worker processes. The main purpose of the master process is to read and evaluate configuration,and maintain worker processes.Worker processes do actual processing of requests. nginx employs event-based model and OS-dependent mechanisms to efficiently distribute requests among worker processes. The number of worker processes is defined in the configuration file and may be fixed 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 placed in the directory /usr/local/nginx/conf,/etc/nginx, or/usr/local/etc/nginx.
Starting, Stopping, and Reloading Configuration
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:
nginx -s signal
Where signal may be one of the following:
stop— fast shutdownquit— graceful shutdownreload— reloading the configuration filereopen— reopening the log files
For example, to stop nginx processes with waiting for the worker processes to finish serving current requests, the following command can be executed:
nginx -s quit
This command should be executed under the same user that started nginx.
Changes made in the configuration file will not be applied until the command to reload configuration is sent to nginx or it is restarted. To reload configuration, execute:
nginx -s reload
Once the master process receives the signal to reload configuration, it checks the syntax validity of the new configuration file and tries to apply the configuration provided in it. If this is a success, the master process starts new worker processes and sends messages to old worker processes, requesting them to shut down. Otherwise, the master process rolls back the changes and continues to work with the old configuration. Old worker processes, receiving a command to shut down, stop accepting new connections and continue to service current requests until all such requests are serviced. After that, the old worker processes exit.
A signal may also be sent to nginx processes with the help of Unix tools such as thekill utility. In this case a signal is sent directly to a process with a given process ID.The process ID of the nginx master process is written, by default, to thenginx.pid in the directory/usr/local/nginx/logs or/var/run. For example, if the master process ID is 1628, to send the QUIT signal resulting in nginx’s graceful shutdown, execute:
kill -s QUIT 1628
For getting the list of all running nginx processes, theps utility may be used, for example, in the following way:
ps -ax | grep nginx
For more information on sending signals to nginx, seeControlling nginx.
Configuration File’s Structure
nginx consists of modules which are controlled by directives specified in the configuration file. Directives are divided into simple directives and block directives. 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 braces ({ and}). If a block directive can have other directives inside braces, it is called a context (examples:events,http,server, and location).
Directives placed in the configuration file outside of any contexts are considered to be in th emain context. The events and http directives reside in the main context,server in http, and location inserver.
The rest of a line after the# sign is considered a comment.
Serving Static Content
An important web server task is serving out 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 may contain HTML files) and /data/images(containing images). This will require editing of the configuration file and setting up of a server block inside the http block with two location blocks.
First, create the/data/www directory and put an index.html file with any text content into it and create the/data/images directory and place some images in it.
Next, open the configuration file. The default configuration file already includes several examples of theserver block, mostly commented out. For now comment out all such blocks and start a newserver block:
http {
server {
}
}
Generally, the configuration file may include severalserver blocksdistinguished by ports on which they listen to and by server names. Once nginx decides which server processes a request, it tests the URI specified in the request’s header against the parameters of thelocation directives defined inside theserver block.
Add the following location block to theserver block:
location / {
root /data/www;
}
This location block specifies the "/" prefix compared with the URI from the request. For matching requests, the URI will be added to the path specified in the root directive, that is, to /data/www, to form the path to the requested file on the local file system.If there are several matching location blocks nginx selects the one with the longest prefix. The location block above provides the shortest prefix, of length one, and so only if all otherlocation blocks fail to provide a match, this block will be used.
Next, add the second location block:
location /images/ {
root /data;
}
It will be a match for requests starting with/images/(location / also matches such requests, but has shorter prefix).
The resulting configuration of theserver block should look like this:
server {
location / {
root /data/www;
}
location /images/ {
root /data;
}
}
This is already a working configuration of a server that listens on the standard port 80 and is accessible on the local machine athttp:.In response to requests with URIs starting with//localhost//images/, the server will send files from the/data/images directory. For example, in response to thehttp://localhost/images/example.png request nginx will send the/data/images/example.png file. If such file does not exist, nginx will send a response indicating the 404 error. Requests with URIs not starting with/images/ will be mapped onto the/data/www directory. For example, in response to thehttp://localhost/some/example.html request nginx will send the/data/www/some/example.html file.
To apply the new configuration, start nginx if it is not yet started or send thereload signal to the nginx’s master process, by executing:
nginx -s reload
In case something does not work as expected, you may try to find out the reason inaccess.loganderror.logfiles in the directory/usr/local/nginx/logsor/var/log/nginx.
Setting Up a Simple Proxy Server
One of the frequent uses of nginx is setting it up as a proxy server, which means a server that receives requests, passes them to the proxied servers, retrieves responses from them, and sends them to the clients.
We will configure a basic proxy server, which serves requests of images with files from the local directory and sends all other requests to a proxied server. In this example, both servers will be defined on a single nginx instance.
First, define the proxied server by adding one more server block to the nginx’s configuration file with the following contents:
server {
listen 8080;
root /data/up1;
location / {
}
}
This will be a simple server that listens on the port 8080(previously, the listen directive has not been specified since the standard port 80 was used) and maps all requests to the/data/up1 directory on the local file system. Create this directory and put the index.html file into it. Note that theroot directive is placed in theserver context. Suchroot directive is used when the location block selected for serving a request does not include ownroot directive.
Next, use the server configuration from the previous section and modify it to make it a proxy server configuration. In the firstlocation block, put the proxy_pass directive with the protocol, name and port of the proxied server specified in the parameter (in our case, it ishttp://localhost:8080):
server {
location / {
proxy_pass http://localhost:8080;
}
location /images/ {
root /data;
}
}
We will modify the secondlocation block, which currently maps requests with the/images/ prefix to the files under the/data/images directory, to make it match the requests of images with typical file extensions. The modified location block looks like this:
location ~ \.(gif|jpg|png)$ {
root /data/images;
}
The parameter is a regular expression matching all URIs ending with .gif, .jpg, or .png. A regular expression should be preceded with~. The corresponding requests will be mapped to the/data/images directory.
When nginx selects a location block to serve a request it first checkslocation directives that specify prefixes, remembering location with the longest prefix, and then checks regular expressions. If there is a match with a regular expression, nginx picks this location or, otherwise, it picks the one remembered earlier.
The resulting configuration of a proxy server will look like this:
server {
location / {
proxy_pass http://localhost:8080/;
}
location ~ \.(gif|jpg|png)$ {
root /data/images;
}
}
This server will filter requests ending with .gif, .jpg, or.png and map them to the/data/images directory (by adding URI to theroot directive’s parameter) and pass all other requests to the proxied server configured above.
To apply new configuration, send thereload signal to nginx as described in the previous sections.
There are many more directives that may be used to further configure a proxy connection.
Setting Up FastCGI Proxying
nginx can be used to route requests to FastCGI servers which run applications built with various frameworks and programming languages such as PHP.
The most basic nginx configuration to work with a FastCGI server includes using thefastcgi_pass directive instead of theproxy_pass directive, and fastcgi_param directives to set parameters passed to a FastCGI server. Suppose the FastCGI server is accessible on localhost:9000. Taking the proxy configuration from the previous section as a basis, replace theproxy_pass directive with the fastcgi_pass directive and change the parameter to localhost:9000. In PHP, theSCRIPT_FILENAME parameter is used for determining the script name, and the QUERY_STRING parameter is used to pass request parameters. The resulting configuration would be:
server {
location / {
fastcgi_pass localhost:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
}
location ~ \.(gif|jpg|png)$ {
root /data/images;
}
}
This will set up a server that will route all requests except for requests for static images to the proxied server operating on localhost:9000 through the FastCGI protocol.
Controlling nginx
nginx can be controlled with signals. The process ID of the master process is written to the file/usr/local/nginx/logs/nginx.pid by default. This name may be changed at configuration time, or in nginx.conf using thepid directive. The master process supports the following signals:
TERM, INT fast shutdown QUIT graceful shutdown HUP changing configuration, keeping up with a changed time zone (only for FreeBSD and Linux), starting new worker processes with a new configuration, graceful shutdown of old worker processes USR1 re-opening log files USR2 upgrading an executable file WINCH graceful shutdown of worker processes
Individual worker processes can be controlled with signals as well, though it is not required. The supported signals are:
TERM, INT fast shutdown QUIT graceful shutdown USR1 re-opening log files WINCH abnormal termination for debugging(requiresdebug_points to be enabled)
Changing Configuration
In order for nginx to re-read the configuration file, a HUP signal should be sent to the master process.The master process first checks the syntax validity, then tries to apply new configuration, that is, to open log files and new listen sockets. If this fails, it rolls back changes and continues to work with old configuration. If this succeeds, it starts new worker processes, and sends messages to old worker processes requesting them to shut down gracefully. Old worker processes close listen sockets and continue to service old clients. After all clients are serviced, old worker processes are shut down.
Let’s illustrate this by example. Imagine that nginx is run on FreeBSD 4.x and the command
ps axw -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)'
produces the following output:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
33127 33126 nobody 0.0 1380 kqread nginx: worker process (nginx)
33128 33126 nobody 0.0 1364 kqread nginx: worker process (nginx)
33129 33126 nobody 0.0 1364 kqread nginx: worker process (nginx)
If HUP is sent to the master process, the output becomes:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
33129 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx)
33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
One of the old worker processes with PID 33129 still continues to work. After some time it exits:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
Rotating Log-files
In order to rotate log files, they need to be renamed first. After that USR1 signal should be sent to the master process. The master process will then re-open all currently open log files and assign them an unprivileged user under which the worker processes are running, as an owner. After successful re-opening, the master process closes all open files and sends the message to worker process to ask them to re-open files. Worker processes also open new files and close old files right away. As a result, old files are almost immediately available for post processing, such as compression.
Upgrading Executable on the Fly
In order to upgrade the server executable, the new executable file should be put in place of an old file first. After that USR2 signal should be sent to the master process.The master process first renames its file with the process ID to a new file with the.oldbin suffix, e.g./usr/local/nginx/logs/nginx.pid.oldbin, then starts a new executable file that in turn starts new worker processes:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
33135 33126 nobody 0.0 1380 kqread nginx: worker process (nginx)
33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx)
36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
After that all worker processes (old and new ones) continue to accept requests. If the WINCH signal is sent to the first master process, it will send messages to its worker processes, requesting them to shutdown gracefully, and they will start to exit:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
33135 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx)
36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
When using the “rtsig” method on Linux, the new processes may not accept connections even after the old master process was sent the WINCH signal. If that is the case, the USR1 signal should be sent to the new master process continuously, until the new processes start to accept connections.
After some time, only the new worker processes will process requests:
PID PPID USER %CPU VSZ WCHAN COMMAND
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx
36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
It should be noted that the old master process does not close its listen sockets, and it can be managed to start its worker processes again if needed. If for some reason the new executable file works unacceptably, one of the following can be done:
-
Send the HUP signal to the old master process. The old master process will start new worker processes without re-reading the configuration. After that, all new processes can be shut down gracefully, by sending the QUIT signal to the new master process.
-
Send the TERM signal to the new master process. It will then send a message to its worker processes requesting them to exit immediately, and they will all exit almost immediately. (If new processes do not exit for some reason, the KILL signal should be sent to them to force them to exit.) When the new master process exits, the old master process will start new worker processes automatically.
If the new master process exits then the old master process discards the.oldbin suffix from the file name with the process ID.
If upgrade was successful, then the old master process should be sent the QUIT signal, and only new processes will stay:
PID PPID USER %CPU VSZ WCHAN COMMAND
36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx)
Connection processing methods
nginx supports a variety of connection processing methods. The availability of a particular method depends on the platform used. On platforms that support several methods nginx will normally select the most efficient method automatically. However, if needed, a connection processing method can be selected explicitly with the use directive.
The following connection processing methods are supported:
-
select— standard method. The supporting module is built automatically on platforms that lack more efficient methods. The--with-select_moduleand--without-select_moduleconfiguration parameters can be used to forcibly enable or disable the build of this module. -
poll— standard method. The supporting module is built automatically on platforms that lack more efficient methods. The--with-poll_moduleand--without-poll_moduleconfiguration parameters can be used to forcibly enable or disable the build of this module. -
kqueue— efficient method used on FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0, and Mac OS X. -
epoll— efficient method used onLinux 2.6+.Some older distributions like SuSE 8.2 provide patches that add epoll support to 2.4 kernels.
-
rtsig— real time signals, efficient method used on Linux 2.2.19+. By default, the system-wide event queue is limited by 1024 signals.On loaded servers it may become necessary to increase this limit by changing the/proc/sys/kernel/rtsig-maxkernel parameter. However, in Linux 2.6.6-mm2 this parameter is gone, and each process now has its own event queue. The size of each queue is limited byRLIMIT_SIGPENDINGand can be changed with worker_rlimit_sigpending.On queue overflow, nginx discards the queue and falls back to
pollconnection processing method until the situation gets back to normal. -
/dev/poll— efficient method used on Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+. -
eventport— event ports, efficient methodused on Solaris 10.
Setting up hashes
To quickly process static sets of data such as server names,map directive’s values, MIME types, names of request header strings, nginx uses hash tables.During the start and each re-configuration nginx selects the minimum possible sizes of hash tables such that the bucket size that stores keys with identical hash values does not exceed the configured parameter (hash bucket size). The size of a table is expressed in buckets. The adjustment is continued until the table size exceeds the hash max size parameter. Most hashes have the corresponding directives that allow changing these parameters, for example, for the server names hash they areserver_names_hash_max_size andserver_names_hash_bucket_size.The hash bucket size parameter is aligned to the size that is a multiple of the processor’s cache line size. This speeds up key search in a hash on modern processors by reducing the number of memory accesses. If hash bucket size is equal to one processor’s cache line size then the number of memory accesses during the key search will be two in the worst case — first to compute the bucket address, and second during the key search inside the bucket. Therefore, if nginx emits the message requesting to increase either hash max size or hash bucket size then the first parameter should first be increased.
Original: http://nginx.org/en/docs/