Difference between revisions of "Nginx"

From ArchWiki
Jump to navigation Jump to search
(→‎TLS/SSL: Matches AES256)
Line 329: Line 329:
nginx needs {{ic|/dev/null}}, {{ic|/dev/random}}, and {{ic|/dev/urandom}}. To install these in the chroot create the {{ic|/dev/}} directory and add the devices with ''mknod''. Avoid mounting all of {{ic|/dev/}} to ensure that, even if the chroot is compromised, an attacker must break out of the chroot to access important devices like {{ic|/dev/sda1}}.
nginx needs {{ic|/dev/null}}, {{ic|/dev/random}}, and {{ic|/dev/urandom}}. To install these in the chroot create the {{ic|/dev/}} directory and add the devices with ''mknod''. Avoid mounting all of {{ic|/dev/}} to ensure that, even if the chroot is compromised, an attacker must break out of the chroot to access important devices like {{ic|/dev/sda1}}.
{{Tip|Be sure that {{ic|/src/http}} is mounted without no-dev option}}
{{Tip|See {{ic|man mknod}} and {{ic|<nowiki>ls -l /dev/{null,random,urandom}</nowiki>}} to better understand the ''mknod'' options.}}
{{Tip|See {{ic|man mknod}} and {{ic|<nowiki>ls -l /dev/{null,random,urandom}</nowiki>}} to better understand the ''mknod'' options.}}

Revision as of 12:53, 30 June 2015

zh-CN: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. According to Netcraft's April 2015 Web Server Survey, nginx now hosts 14.48% of all domains worldwide, while Apache hosts about 38.39%. nginx is now well known for its stability, rich feature set, simple configuration, and low resource consumption.


Install the package nginx.

For a Ruby on Rails setup with nginx, see Ruby on Rails#The Perfect Rails Setup.

For a chroot-based installation for additional security, see #Installation in a chroot.


Start/enable nginx.service using systemd.

The default served page at is /usr/share/nginx/html/index.html.


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 http://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.

General configuration

Processes and connections

You should choose a fitting value for worker_processes. This settings ultimately defines how many connection 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, worker_processes 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 max_clients = worker_processes * worker_connections.

Running under different user

By default nginx runs as user nobody. To run it as another user, change the user line in nginx.conf:

user myuser mygroup; # e.g. http

Nginx should now run as user myuser and under group mygroup. 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 server blocks. It may be referred as "VirtualHosts", however this is an Apache term. The usage of server blocks also differs to Apache.

In the example below the server listens for incoming connections for two domains: domainname1.dom and domainname2.dom:

server {
        listen 80;
        server_name domainname1.dom;
        root /usr/share/nginx/domainname1.dom/html;

server {
        listen 80;
        listen 443 ssl; # also listen on HTTPS
        server_name domainname2.dom;
        root /usr/share/nginx/domainname2.dom/html;

Restart the nginx service to apply any changes.

You should configure a DNS-server like BIND or dnsmasq so that these domain names could be resolved for connecting clients.

For now you can just add them manually in /etc/hosts replacing with the actual IP address of server: domainname1.dom domainname2.dom


openssl provides TLS/SSL support and is installed by default on Arch installations.

Tip: You may want to read the ngx_http_ssl_module docs first before configuring SSL

Create a private key and self-signed certificate. This is adequate for most installations that do not require a CSR:

# cd /etc/nginx/
# openssl req -new -x509 -nodes -newkey rsa:4096 -keyout nginx.key -out nginx.crt -days 1095
# chmod 400 nginx.key
# chmod 444 nginx.crt
Note: The -days switch is optional and RSA keysize can be as low as 2048 (default).

If you need to create a CSR, follow these keygen instructions instead of the above:

# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out nginx.key
# chmod 400 nginx.key
# openssl req -new -sha256 -key nginx.key -out nginx.csr
# openssl x509 -req -days 1095 -in nginx.csr -signkey nginx.key -out nginx.crt
Note: For more openssl options, read the man page or peruse openssl's extensive documentation.
Warning: If you plan on implementing SSL/TLS, know that some variations and implementations are still vulnerable to attack. For details on these current vulnerabilities within SSL/TLS and how to apply appropriate changes to nginx, visit http://disablessl3.com/ and https://weakdh.org/sysadmin.html

Example of a nginx.conf using SSL:

http {
        ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL:10m;
        add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        ssl_session_tickets off;
        ssl_stapling on;
        ssl_stapling_verify on;
        resolver valid=300s; # Google DNS Servers
        resolver_timeout 5s;

server {
        #listen 80; # Uncomment to also listen for HTTP requests
        listen 443 ssl;
        server_name localhost;

        ssl_certificate nginx.crt;
        ssl_certificate_key nginx.key;

        root /usr/share/nginx/html;
        location / {
            index  index.html index.htm index.php;
Tip: Mozilla has a useful SSL/TLS article which includes nginx specific configuration guidelines as well as an automated tool to help create a more secure configuration.
Tip: Cipherli.st provides strong SSL implementation examples and tutorial for most modern webservers.

Restart the nginx service to apply any changes.


FastCGI, also FCGI, is a protocol for interfacing interactive programs with a web server. FastCGI is a variation on the earlier CGI (Common Gateway Interface); FastCGI's main aim is to reduce the overhead associated with interfacing the web server and CGI programs, allowing a server to handle more web page requests at once.

FastCGI technology is introduced into nginx to work with many external tools, i.e.: Perl, PHP and Python.

PHP implementation

PHP-FPM is the recommended solution to run as FastCGI server for PHP.

PHP configuration

Install the php and php-fpm packages.

The open_basedir in /etc/php/php.ini has to list base directories which contain PHP files, like /usr/share/nginx/html/ and /usr/share/webapps/:

open_basedir = /usr/share/webapps/:/srv/http/:/usr/share/nginx/html/:/home/:/tmp/:/usr/share/pear/

After that let us configure modules you need. For example to use sqlite3 you should install php-sqlite. Then enable it in /etc/php/php.ini by uncommenting following line:


The main configuration file of PHP-FPM is /etc/php/php-fpm.conf. Enable and start the php-fpm service.

Note: If you run nginx in chrooted environment (chroot is /srv/nginx-jail, web pages are served at /srv/nginx-jail/www), you must modify the file /etc/php/php-fpm.conf to include the chroot /srv/nginx-jail and listen = /srv/nginx-jail/run/php-fpm/php-fpm.sock directives within the pool section (a default one is [www]). Create the directory for the socket file, if missing.

Configure MySQL/MariaDB as described in MariaDB.

Uncomment at least one of the following lines in /etc/php/php.ini:

Warning: As of PHP 5.5, mysql.so is deprecated and will fill up your log files.

You can add minor privileged MySQL users for your web scripts. You might also want to edit /etc/mysql/my.cnf and uncomment the skip-networking line so the MySQL server is only accessible by the localhost. You have to restart MySQL for changes to take effect.

Tip: You may want to install a tool like phpMyAdmin, Adminer or mysql-workbench to work with your databases.
nginx configuration
Adding to main configuration

Inside each server block serving a PHP web application should appear a location block similar to:

location ~ \.php$ {
     fastcgi_pass   unix:/run/php-fpm/php-fpm.sock;
     fastcgi_index  index.php;
     include        fastcgi.conf;

If it is needed to process other extensions with PHP (e.g. .html and .htm):

location ~ \.(php|html|htm)$ {
     fastcgi_pass   unix:/run/php-fpm/php-fpm.sock;
     fastcgi_index  index.php;
     include        fastcgi.conf;

Non .php extension processing in php-fpm should be explicitly added in /etc/php/php-fpm.conf:

security.limit_extensions = .php .html .htm
Note: Pay attention to the fastcgi_pass argument, as it must be the TCP or Unix socket defined by the chosen FastCGI server in its config file. The default (Unix) socket for php-fpm is:
fastcgi_pass unix:/run/php-fpm/php-fpm.sock;

You might use the common TCP socket, not default,

Unix domain sockets should however be faster.

The example shown below is a copy of a working configuration. Notice that in this example the root path in specified directly under server, and not inside location (as it is in the default config).

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    location / {
        index index.html index.htm index.php;

    location ~ \.php$ {
        #fastcgi_pass; (depending on your php-fpm socket configuration)
        fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi.conf;
Managing multiple blocks (optional)

If adding PHP configuration to multiple server blocks, it may be better to use a separate config file for easier management:

location ~ \.php$ {
        fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi.conf;

Include the php-config file under each server block:

 server = {
     include php.conf;
Test configuration

You need to restart the php-fpm and nginx daemons if the configuration has been changed in order to apply changes.

To test the FastCGI implementation, create a new php file inside the document folder containing:


Navigate this file inside a browser and you will see the informational page with the current PHP configuration.

See #Troubleshooting section if you are experiencing problems with your configuration.

CGI implementation

This implementation is needed for CGI applications.


Install the fcgiwrap. The configuration file is /usr/lib/systemd/system/fcgiwrap.socket. Enable and start the fcgiwrap.socket.

Multiple worker threads

If you want to spawn multiple worker threads, it is recommended that you use multiwatchAUR, 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.

Copy the unit file from /usr/lib/systemd/system/fcgiwrap.service to /etc/systemd/system/fcgiwrap.service (and the fcgiwrap.socket unit, if present), and modify the ExecStart line to suit your needs. Here is a unit file that uses multiwatchAUR. Make sure fcgiwrap.socket is not started or enabled, because it will conflict with this unit:

Description=Simple CGI Server

ExecStartPre=/bin/rm -f /run/fcgiwrap.socket
ExecStart=/usr/bin/spawn-fcgi -u http -g http -s /run/fcgiwrap.sock -n -- /usr/bin/multiwatch -f 10 -- /usr/sbin/fcgiwrap
ExecStartPost=/usr/bin/chmod 660 /run/fcgiwrap.sock


Tweak -f 10 to change the number of children that are spawned.

Warning: The 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

Inside each server block serving a CGI web application should appear a location block similar to:

location ~ \.cgi$ {
     root           /path/to/server/cgi-bin;
     fastcgi_pass   unix:/run/fcgiwrap.sock;
     include        fastcgi.conf;

The default socket file for fcgiwrap is /run/fcgiwrap.sock.

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 /usr/bin 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 /srv/http.

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 /dev/null, /dev/random, and /dev/urandom. To install these in the chroot create the /dev/ directory and add the devices with mknod. Avoid mounting all of /dev/ to ensure that, even if the chroot is compromised, an attacker must break out of the chroot to access important devices like /dev/sda1.

Tip: Be sure that /src/http is mounted without no-dev option
Tip: See man mknod 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 /srv/http/www.

# 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
Note: If using a 64 bit kernel you will need to create symbolic links lib64 and usr/lib64 to usr/lib: cd $JAIL; ln -s usr/lib lib64 and cd $JAIL/usr; ln -s lib lib64.

Then mount $JAIL/tmp and $JAIL/run 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 /etc/fstab:

 tmpfs   /srv/http/run   tmpfs   rw,noexec,relatime,size=1024k   0       0
 tmpfs   /srv/http/tmp   tmpfs   rw,noexec,relatime,size=102400k 0       0

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.

$ ldd /usr/bin/nginx
linux-vdso.so.1 (0x00007fffc41fe000)
libpthread.so.0 => /usr/lib/libpthread.so.0 (0x00007f57ec3e8000)
libcrypt.so.1 => /usr/lib/libcrypt.so.1 (0x00007f57ec1b1000)
libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x00007f57ebead000)
libm.so.6 => /usr/lib/libm.so.6 (0x00007f57ebbaf000)
libpcre.so.1 => /usr/lib/libpcre.so.1 (0x00007f57eb94c000)
libssl.so.1.0.0 => /usr/lib/libssl.so.1.0.0 (0x00007f57eb6e0000)
libcrypto.so.1.0.0 => /usr/lib/libcrypto.so.1.0.0 (0x00007f57eb2d6000)
libdl.so.2 => /usr/lib/libdl.so.2 (0x00007f57eb0d2000)
libz.so.1 => /usr/lib/libz.so.1 (0x00007f57eaebc000)
libGeoIP.so.1 => /usr/lib/libGeoIP.so.1 (0x00007f57eac8d000)
libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0x00007f57eaa77000)
libc.so.6 => /usr/lib/libc.so.6 (0x00007f57ea6ca000)
/lib64/ld-linux-x86-64.so.2 (0x00007f57ec604000)
# cp /lib64/ld-linux-x86-64.so.2 $JAIL/lib

For files residing in /usr/lib 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
Note: Do not try to copy linux-vdso.so: it is not a real library and does not exist in /usr/lib. Also ld-linux-x86-64.so will likely be listed in /lib64 for a 64 bit system.

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.

# 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 sudo chmod -rw
# find $JAIL/ -gid 0 -uid 0 -type d -print | xargs sudo chmod +x
# find $JAIL/etc -gid 0 -uid 0 -type f -print | xargs sudo chmod -x
# find $JAIL/usr/bin -type f -print | xargs sudo chmod ug+rx
# find $JAIL/ -group http -user http -print | xargs sudo 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

Before modifying the nginx.service unit file, it may be a good idea to copy it to /etc/systemd/system/ since the unit files there take priority over those in /usr/lib/systemd/system/. This means upgrading nginx would not modify your custom .service file.

# cp /usr/lib/systemd/system/nginx.service /etc/systemd/system/nginx.service

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.

Note: I'm not sure if the pid file needs to be stored in the chroot jail.
 Description=A high performance web server and a reverse proxy server
 After=syslog.target network.target
 ExecStartPre=/usr/bin/chroot --userspec=http:http /srv/http /usr/bin/nginx -t -q -g 'pid /run/nginx.pid; daemon on; master_process on;'
 ExecStart=/usr/bin/chroot --userspec=http:http /srv/http /usr/bin/nginx -g 'pid /run/nginx.pid; daemon on; master_process on;'
 ExecReload=/usr/bin/chroot --userspec=http:http /srv/http /usr/bin/nginx -g 'pid /run/nginx.pid; daemon on; master_process on;' -s reload
 ExecStop=/usr/bin/chroot --userspec=http:http /srv/http /usr/bin/nginx -g 'pid /run/nginx.pid;' -s quit
Note: Upgrading nginx with pacman will not upgrade the chrooted nginx installation. You have to take care of the updates manually by repeating some of the steps above. Do not forget to also update the libraries it links against.

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 /proc/PID/root symmlinks to. If should link to /srv/http instead of /.

# ps -C nginx | awk '{print $1}' | sed 1d | while read -r PID; do ls -l /proc/$PID/root; done


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

Accessing local IP redirects to localhost

Solution from the Arch Linux forum.

In /etc/nginx/nginx.conf locate the server_name localhost line without a # in front of it, and add below:

server_name_in_redirect off;

Default behavior is that nginx redirects any requests to the value given as server_name in the config.

Error: 403 (Permission error)

This is most likely a permission error. Make sure the user configured in the nginx configuration is able to read the correct files.

If you are sure that permissions are as they should be, make sure that your document root directory is not empty. Create an index.html in this folder.

Error: The page you are looking for is temporarily unavailable. Please try again later.

This is because the FastCGI server has not been started, or the socket used has wrong permissions.

Error: No input file specified

1. Most likely you do not have the SCRIPT_FILENAME containing the full path to your scripts. If the configuration of nginx (fastcgi_param SCRIPT_FILENAME) 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 -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 -p 9000 -u www -g www -f /usr/bin/php-cgi

2. Another occasion is that, wrong root argument in the location ~ \.php$ section in nginx.conf. Make sure the root points to the same directory as it in location / in the same server. Or you may just set root as global, do not define it in any location section.

3. Verify that variable open_basedir in /etc/php/php.ini also contains path you specified in root argument in nginx.conf.

4. Also notice that not only php script should have read permission, but also the entire directory structure should have execute permission so that PHP user can traverse the path.

Error: "File not found" in browser or "Primary script unknown" in log file

Ensure you have specified a root and index in your server or location directive:

location ~ \.php$ {
     root           /srv/http/root_dir;
     index          index.php;
     fastcgi_pass   unix:/run/php-fpm/php-fpm.sock;
     include        fastcgi.conf;

Also make sure the requested file exists on the server.

Error: chroot: '/usr/sbin/nginx' No such file or directory

If you encounter this error when running the nginx daemon using chroot, this is likely due to missing 64 bit libraries in the jailed environment.

If you are running chroot in /srv/http you need to add the required 64-bit libraries.

First, set up the directories:

# mkdir /srv/http/usr/lib64
# cd /srv/http; ln -s usr/lib64 lib64

Then copy the required 64 bit libraries listed with ldd /usr/sbin/nginx to /srv/http/usr/lib64.

If run as root, permissions for the libraries should be read and executable for all users, so no modification is required.

Alternative script for systemd

On pure systemd you can get advantages of chroot + systemd. [1] Based on set user group an pid on:

user http;
pid /run/nginx.pid;

the absolute path of file is /srv/http/etc/nginx/nginx.conf.

Description=nginx (Chroot)
After=syslog.target network.target

ExecStartPre=/usr/sbin/nginx -t -c /etc/nginx/nginx.conf
ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf
ExecReload=/usr/sbin/nginx -c /etc/nginx/nginx.conf -s reload
ExecStop=/usr/sbin/nginx -c /etc/nginx/nginx.conf -s stop


It is not necesary to set the default location, nginx loads at default -c /etc/nginx/nginx.conf, but it is a good idea though.

Alternatively you can run only ExecStart as chroot with parameter RootDirectoryStartOnly set as yes [man systemd service] or start it before mount point as effective or a systemd path is available.

Description=nginx (Chroot) path

Enable the created nginx.path and change the WantedBy=default.target to WantedBy=nginx.path in /etc/systemd/system/nginx.service.

The PIDFile in unit file allows systemd to monitor process (absolute path required). If it is undesired, you can change to default one-shoot type, and delete the reference from the unit file.

See also