nginx
nginx (pronounced "engine X"), is a free, open-source, high-performance HTTP server and reverse proxy, as well as an IMAP/POP3 proxy server, written by Igor Sysoev in 2005. nginx is well known for its stability, rich feature set, simple configuration, and low resource consumption.
This article describes how to set up nginx and how to optionally integrate it with PHP via #FastCGI.
Installation
Install the package nginx-mainline (mainline branch: new features, updates, bugfixes) or nginx (stable branch: major bugfixes only).
Using the mainline branch is recommended. The main reason to use the stable branch is that you are concerned about possible impacts of new features, such as incompatibility with third-party modules or the inadvertent introduction of bugs in new features.
For a chroot-based installation for additional security, see #Installation in a chroot.
Running
Start/enable nginx.service.
The default page served at http://127.0.0.1 is /usr/share/nginx/html/index.html.
Configuration
First steps with nginx are described in the Beginner’s Guide. You can modify the configuration by editing the files in /etc/nginx/ The main configuration file is located at /etc/nginx/nginx.conf.
More details and examples can be found in https://wiki.nginx.org/Configuration and the official documentation.
The examples below cover the most common use cases. It is assumed that you use the default location for documents (/usr/share/nginx/html). If that is not the case, substitute your path instead.
Configuration example
/etc/nginx/nginx.conf
user http;
worker_processes auto;
worker_cpu_affinity auto;
events {
multi_accept on;
worker_connections 1024;
}
http {
charset utf-8;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
server_tokens off;
log_not_found off;
types_hash_max_size 4096;
client_max_body_size 16M;
# MIME
include mime.types;
default_type application/octet-stream;
# logging
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log warn;
# load configs
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}
Processes and connections
You should choose a fitting value for . This setting ultimately defines how many connections nginx will accept and how many processors it will be able to make use of. Generally, making it the number of hardware threads in your system is a good start. Alternatively, accepts the auto value since versions 1.3.8 and 1.2.5, which will try to autodetect the optimal value (source).
The maximum connections nginx will accept is given by .
Running under different user
By default, nginx runs the master process as and worker processes as user http. To run worker processes as another user, change the directive in :
If the group is omitted, a group whose name equals that of user is used.
Server blocks
It is possible to serve multiple domains using blocks. These are comparable to "VirtualHosts" in Apache HTTP Server. Also see the upstream examples.
In the example below the server listens for incoming connections on IPv4 and IPv6 ports 80 for two domains, domainname1.dom and :
Restart nginx.service to apply any changes.
Managing server entries
It is possible to put different blocks in different files. This allows you to easily enable or disable certain sites.
Create the following directories:
# mkdir /etc/nginx/sites-available # mkdir /etc/nginx/sites-enabled
Create a file inside the directory that contains one or more server blocks:
Append include sites-enabled/*; to the end of the http block:
To enable a site, simply create a symlink:
# ln -s /etc/nginx/sites-available/example.conf /etc/nginx/sites-enabled/example.conf
To disable a site, unlink the active symlink:
# unlink /etc/nginx/sites-enabled/example.conf
Reload/restart nginx.service to enable changes to the sites configuration.
TLS
OpenSSL provides TLS support and is installed by default on Arch installations.
Create a private key and self-signed certificate. This is adequate for most installations that do not require a CSR:
# mkdir /etc/nginx/ssl # cd /etc/nginx/ssl # openssl req -new -x509 -nodes -newkey rsa:4096 -keyout server.key -out server.crt -days 1095 # chmod 400 server.key # chmod 444 server.crt
If you need to create a CSR, follow these instructions instead of the above:
# mkdir /etc/nginx/ssl # cd /etc/nginx/ssl # openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out server.key # chmod 400 server.key # openssl req -new -sha256 -key server.key -out server.csr # openssl x509 -req -days 1095 -in server.csr -signkey server.key -out server.crt
A starting point for a /etc/nginx/nginx.conf with TLS is Mozilla's SSL Configuration Generator.
Restart nginx.service to apply any changes.
Per-user directories
To replicate Apache-style URLs to users' ~/public_html directories, try the following. (Note: if both rules are used, below, the more-specific PHP rule must come first.)
See #PHP implementation for more information on PHP configuration with .
Restart nginx.service to enable the new configuration.
FastCGI
FastCGI, also FCGI, is a protocol for interfacing interactive programs with a web server. FastCGI is a variation on the earlier Common Gateway Interface (CGI); FastCGI's main aim is to reduce the overhead associated with interfacing the web server and CGI programs, allowing servers to handle more web page requests at once.
FastCGI technology is introduced into nginx to work with many external tools, e.g. Perl, PHP and Python.
PHP implementation
PHP-FPM is the recommended solution to run as FastCGI server for PHP.
Install and make sure PHP has been installed and configured correctly. The main configuration file of PHP-FPM is /etc/php/php-fpm.conf. For basic usage the default configuration should be sufficient.
nginx configuration
When serving a PHP web-application, a for PHP-FPM should to be included in each server block , e.g.:
If it is needed to process other extensions with PHP (e.g. .html and .htm):
location ~ [^/]\.(php|html|htm)(/|$) {
...
}
Non .php extension processing in PHP-FPM should also be explicitly added in :
security.limit_extensions = .php .html .htm
server blocks using the same PHP-FPM configuration, a php_fastcgi.conf configuration file may be used to ease management:
/etc/nginx/php_fastcgi.conf
location ~ \.php$ {
# 404
try_files $fastcgi_script_name =404;
# default fastcgi_params
include fastcgi_params;
# fastcgi settings
...
}
To enable PHP support for a particular server, simply include the php_fastcgi.conf configuration file:
/etc/nginx/sites-available/example.conf
server {
server_name example.com;
...
include /etc/nginx/php_fastcgi.conf;
}
Test configuration
You need to restart the and nginx.service units if the configuration has been changed in order to apply changes.
To test the FastCGI implementation, create a new PHP file inside the folder containing:
<?php phpinfo(); ?>
Navigate this file inside a browser and you should see the informational page with the current PHP configuration.
CGI implementation
This implementation is needed for CGI applications.
Multiple worker threads
If you want to spawn multiple worker threads, it is recommended that you use , which will take care of restarting crashed children. You will need to use spawn-fcgi to create the unix socket, as multiwatch seems unable to handle the systemd-created socket, even though fcgiwrap itself does not have any trouble if invoked directly in the unit file.
Override the unit (and the unit, if present), and modify the line to suit your needs. Here is a unit file that uses . Make sure is not started or enabled, because it will conflict with this unit:
Tweak to change the number of children that are spawned.
ExecStartPost line is required because of strange behaviour I'm seeing when I use the -M 660 option for spawn-fcgi. The wrong mode is set. This may be a bug?nginx configuration
In , copy the file to . In , comment or delete the lines which set and .
Inside each block serving a CGI web application should appear a block similar to:
location ~ \.cgi$ {
include fcgiwrap_params;
fastcgi_param DOCUMENT_ROOT /srv/www/cgi-bin/;
fastcgi_param SCRIPT_NAME myscript.cgi;
fastcgi_pass unix:/run/fcgiwrap.sock;
}
The default socket file for is /run/fcgiwrap.sock.
Using is a shortcut alternative to setting and . If you use , you also will not need to copy to and comment out the and lines.
If you keep getting a error, you should check if your CGI-application first announces the mime-type of the following content. For html this needs to be .
If you get 403 errors, make sure that the CGI executable is readable and executable by the http user and that every parent folder is readable by the http user.
Installation in a chroot
Installing nginx in a chroot adds an additional layer of security. For maximum security the chroot should include only the files needed to run the nginx server and all files should have the most restrictive permissions possible, e.g., as much as possible should be owned by root, directories such as should be unreadable and unwriteable, etc.
Arch comes with an http user and group by default which will run the server. The chroot will be in .
A perl script to create this jail is available at jail.pl gist. You can either use that or follow the instructions in this article. It expects to be run as root. You will need to uncomment a line before it makes any changes.
Create necessary devices
nginx needs , , and /dev/urandom. To install these in the chroot create the directory and add the devices with mknod. Avoid mounting all of to ensure that, even if the chroot is compromised, an attacker must break out of the chroot to access important devices like .
- Be sure that
/srv/httpis mounted without the nodev option - See mknod(1) and
ls -l /dev/{null,random,urandom}to better understand the mknod options.
# export JAIL=/srv/http # mkdir $JAIL/dev # mknod -m 0666 $JAIL/dev/null c 1 3 # mknod -m 0666 $JAIL/dev/random c 1 8 # mknod -m 0444 $JAIL/dev/urandom c 1 9
Create necessary directories
nginx requires a bunch of files to run properly. Before copying them over, create the folders to store them. This assumes your nginx document root will be .
# mkdir -p $JAIL/etc/nginx/logs
# mkdir -p $JAIL/usr/{lib,bin}
# mkdir -p $JAIL/usr/share/nginx
# mkdir -p $JAIL/var/{log,lib}/nginx
# mkdir -p $JAIL/www/cgi-bin
# mkdir -p $JAIL/{run,tmp}
# cd $JAIL; ln -s usr/lib lib
# cd $JAIL; ln -s usr/lib lib64
# cd $JAIL/usr; ln -s lib lib64
Then mount and as tmpfs's. The size should be limited to ensure an attacker cannot eat all the RAM.
# mount -t tmpfs none $JAIL/run -o 'noexec,size=1M' # mount -t tmpfs none $JAIL/tmp -o 'noexec,size=100M'
In order to preserve the mounts across reboots, the following entries should be added to :
Populate the chroot
First copy over the easy files.
# cp -r /usr/share/nginx/* $JAIL/usr/share/nginx # cp -r /usr/share/nginx/html/* $JAIL/www # cp /usr/bin/nginx $JAIL/usr/bin/ # cp -r /var/lib/nginx $JAIL/var/lib/nginx
Now copy over required libraries. Use ldd to list them and then copy them all to the correct location. Copying is preferred over hardlinks to ensure that even if an attacker gains write access to the files they cannot destroy or alter the true system files.
For files residing in you may try the following one-liner:
# cp $(ldd /usr/bin/nginx | grep /usr/lib/ | sed -sre 's/(.+)(\/usr\/lib\/\S+).+/\2/g') $JAIL/usr/lib
And the following for ld-linux-x86-64.so:
# cp /lib64/ld-linux-x86-64.so.2 $JAIL/lib
Copy over some miscellaneous but necessary libraries and system files.
# cp /usr/lib/libnss_* $JAIL/usr/lib
# cp -rfvL /etc/{services,localtime,nsswitch.conf,nscd.conf,protocols,hosts,ld.so.cache,ld.so.conf,resolv.conf,host.conf,nginx} $JAIL/etc
Create restricted user/group files for the chroot. This way only the users needed for the chroot to function exist as far as the chroot knows, and none of the system users/groups are leaked to attackers should they gain access to the chroot.
$JAIL/etc/shadow
http:x:14871:::::: nobody:x:14871::::::
# touch $JAIL/etc/shells # touch $JAIL/run/nginx.pid
Finally make set very restrictive permissions. As much as possible should be owned by root and set unwritable.
# chown -R root:root $JAIL/
# chown -R http:http $JAIL/www
# chown -R http:http $JAIL/etc/nginx
# chown -R http:http $JAIL/var/{log,lib}/nginx
# chown http:http $JAIL/run/nginx.pid
# find $JAIL/ -gid 0 -uid 0 -type d -print | xargs chmod -rw
# find $JAIL/ -gid 0 -uid 0 -type d -print | xargs chmod +x
# find $JAIL/etc -gid 0 -uid 0 -type f -print | xargs chmod -x
# find $JAIL/usr/bin -type f -print | xargs chmod ug+rx
# find $JAIL/ -group http -user http -print | xargs chmod o-rwx
# chmod +rw $JAIL/tmp
# chmod +rw $JAIL/run
If your server will bind port 80 (or any other port in range [1-1023]), give the chrooted executable permission to bind these ports without root.
# setcap 'cap_net_bind_service=+ep' $JAIL/usr/bin/nginx
Modify nginx.service to start chroot
Override the unit nginx.service. Upgrading nginx will not modify your custom .service file.
The systemd unit must be changed to start up nginx in the chroot, as the http user, and store the pid file in the chroot.
You can now safely get rid of the non-chrooted nginx installation.
# pacman -Rsc nginx
If you do not remove the non-chrooted nginx installation, you may want to make sure that the running nginx process is in fact the chrooted one. You can do so by checking where symmlinks to. It should link to instead of /.
# ps -C nginx | awk '{print $1}' | sed 1d | while read -r PID; do ls -l /proc/$PID/root; done
Tips and tricks
Running unprivileged using systemd
Use a drop-in unit file for nginx.service and set the and optionally options under :
We can harden the service against ever elevating privileges:
Then we need to ensure that has access to everything it needs. Follow the subsections below and then start nginx.
Port
Linux does not permit non- processes to bind to ports below 1024 by default. A port above 1024 can be used:
Or you may grant the nginx process the CAP_NET_BIND_SERVICE capability which will allow it to bind to ports below 1024:
Alternatively, you can use systemd socket activation. In this case, systemd will listen on the ports and, when a connection is made, spawn nginx passing the socket as a file descriptor. This means nginx requires no special capabilities as the socket already exists when it is started. This relies on an internal environment variable that nginx uses for passing sockets and is therefore not officially supported. Instead of setting CapabilityBoundingSet and , edit the service override to set the environment variable to tell nginx which file descriptors the sockets will be passed as:
There will be one socket per listening port starting at file descriptor 3, so in this example we are telling nginx to expect two sockets. Now create a unit specifying what ports to listen on:
The sockets will be passed in the order defined in this unit, so port 80 will be file descriptor 3 and port 443 will be file descriptor 4. If you previously enabled or started the service, you should now stop it, and enable instead. When your system starts, nginx will not be running, but will be started when you access the website in a browser. With this you can harden the service further; for example, in many cases you can now set in the service file, blocking nginx from the external network, since the socket created by systemd is sufficient to serve the website over. Note that this will print a warning in the logs of the nginx service:
PID file
nginx uses /run/nginx.pid by default. We can create a directory that user has write access to and place our PID file in there. An example using systemd-tmpfiles:
Run the configuration:
# systemd-tmpfiles --create
Edit the PID values based on the original nginx.service:
/var/lib/nginx/*
Some directories under /var/lib/nginx need to be bootstrapped by nginx running as . It is not necessary to start the whole server to do that, nginx will do it on a simple configuration test. So just run one of those and you are good to go.
Log file and directory permissions
The step of running a configuration test will create a dangling -owned log. Remove logs in to start fresh.
The nginx service user needs write permission to . This may require changing permission and/or ownership of this directory on your system.
Alternative script for systemd
On pure systemd you can get advantages of chroot + systemd. Based on set user group and pid with:
the absolute path of the file is .
It is not necessary to set the default location, nginx loads at default , but it is a good idea.
Alternatively you can run only as chroot with parameter set as (see systemd.service(5)) or start it before mount point as effective or a systemd path (see ) is available.
/etc/systemd/system/nginx.path
[Unit] Description=nginx (Chroot) path [Path] PathExists=/srv/http/site/Public_html [Install] WantedBy=default.target
Enable the created and change the to in .
The in unit file allows systemd to monitor process (absolute path required). If it is undesired, you can change to default one-shot type, and delete the reference from the unit file.
Nginx beautifier
is a commandline tool used to beautify and format nginx configuration files.
Better headers management
Nginx has a rather unintuitive header management system where headers can only be defined in one context, any other headers are ignored. To remedy this we can install the headers-more-nginx module.
Install the package package. This will install the module to directory.
To load the module add the following to the top of your main nginx configuration file.
/etc/nginx/nginx.conf
load_module "/usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so"; ...
Compiling with additional modules
There are some nginx modules (such as this module) that do not have associated packages in the official repositories or the AUR. Therefore, it is sometimes necessary to compile nginx yourself. Install the packages and nginx, and then change directories to the downloaded source code . As explained in the official documentation, the configure script should be run to determine which modules are compiled. However, the default configuration does not match the arch linux nginx defaults. Run to find the default configuration arguments, and then append any required configuration arguments to compile the desired modules.
# configure <default_configuration_arguments> <additional_configuration_arguments> # make # make install
Troubleshooting
Configuration validation
# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful
Error: The page you are looking for is temporarily unavailable. Please try again later. (502 Bad Gateway)
This is because the FastCGI server has not been started, or the socket used has wrong permissions.
Try out this answer to fix the 502 error.
In Arch Linux, the configuration file mentioned in above link is /etc/php/php-fpm.conf.
Error: No input file specified
1. Verify that variable in contains the correct path specified as argument in (usually ). When using PHP-FPM as FastCGI server for PHP, you may add in the block which aims for processing php file in .
2. Another occasion is that, wrong argument in the location ~ \.php$ section in . Make sure the points to the same directory as it in in the same server. Or you may just set root as global, do not define it in any location section.
3. Check permissions: e.g. http for user/group, for directories and for files. Remember the entire path to the html directory should have the correct permissions. See File permissions and attributes#Bulk chmod to bulk modify a directory tree.
4. You do not have the containing the full path to your scripts. If the configuration of nginx () is correct, this kind of error means php failed to load the requested script. Usually it is simply a permissions issue, you can just run php-cgi as root:
# spawn-fcgi -a 127.0.0.1 -p 9000 -f /usr/bin/php-cgi
or you should create a group and user to start the php-cgi:
# groupadd www # useradd -g www www # chmod +w /srv/www/nginx/html # chown -R www:www /srv/www/nginx/html # spawn-fcgi -a 127.0.0.1 -p 9000 -u www -g www -f /usr/bin/php-cgi
5. If you are running php-fpm with chrooted nginx ensure is set correctly within (or if working on older version)
Warning: Could not build optimal types_hash
When starting the nginx.service, the process might log the message:
[warn] 18872#18872: could not build optimal types_hash, you should increase either types_hash_max_size: 1024 or types_hash_bucket_size: 64; ignoring types_hash_bucket_size
To fix this warning, increase the values for these keys inside the http block :
Cannot assign requested address
The full error from nginx.service unit status is
[emerg] 460#460: bind() to A.B.C.D:443 failed (99: Cannot assign requested address)
Even if your nginx unit-file is configured to run after network.target with systemd, nginx may attempt to listen at an address that is configured but not added to any interface yet. Verify that this the case by manually running start for nginx (thereby showing the IP address is configured properly). Configuring nginx to listen to any address will resolve this issue. Now if your use case requires listening to a specific address, one possible solution is to reconfigure systemd.
To start nginx after all configured network devices are up and assigned an IP address, append to within nginx.service and start/enable .