Difference between revisions of "Nginx"

From ArchWiki
Jump to: navigation, search
m (Add alternative startup script on troubleshoting)
m (style)
 
(283 intermediate revisions by 78 users not shown)
Line 1: Line 1:
[[Category:Web Server]]
+
{{Lowercase title}}
 +
[[Category:Web server]]
 
[[de:Nginx]]
 
[[de:Nginx]]
 
[[ja:Nginx]]
 
[[ja:Nginx]]
 
[[ru:Nginx]]
 
[[ru:Nginx]]
[[zh-CN:Nginx]]
+
[[zh-hans:Nginx]]
'''Nginx''' (pronounced "engine X") written by Igor Sysoev (Russia) in 2005, is a free, open-source, high-performance HTTP server and reverse proxy, as well as an IMAP/POP3 proxy server. According to Netcraft's [http://news.netcraft.com/archives/2013/03/01/march-2013-web-server-survey.html March 2013 Web Server Survey], Nginx now hosts 13.53% of all domains worldwide, while [[Apache]] hosts about 54.68%. Nginx is now well known for its stability, rich feature set, simple configuration, and low resource consumption.
+
 
 +
[[Wikipedia: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 [http://news.netcraft.com/archives/2015/04/20/april-2015-web-server-survey.html 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.
 +
 
 +
Nginx is often used together with a scripting language such as [[PHP]] and database such as [[MySQL]]. This combination is often referred to as a LEMP stack (Linux, EngineX, MySQL, PHP).
  
 
== Installation ==
 
== Installation ==
  
[[Pacman|Install]] package {{Pkg|nginx}} in the [[Official Repositories|official repositories]].
+
[[Install]] the package {{Pkg|nginx-mainline}} (mainline branch: new features, updates, bugfixes) or {{Pkg|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 [https://www.nginx.com/blog/nginx-1-6-1-7-released/].
 +
 
 +
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]].
 +
 
 +
== Running ==
 +
 
 +
[[Start/enable]] {{ic|nginx.service}}.
 +
 
 +
The default page served at http://127.0.0.1 is {{ic|/usr/share/nginx/html/index.html}}.
 +
 
 +
== Configuration ==
 +
 
 +
First steps with nginx are described in the [http://nginx.org/en/docs/beginners_guide.html Beginner’s Guide]. You can modify the configuration by editing the files in {{ic|/etc/nginx/}} The main configuration file is located at {{ic|/etc/nginx/nginx.conf}}.
 +
 
 +
More details and examples can be found in http://wiki.nginx.org/Configuration and the [http://nginx.org/en/docs/ official documentation].
 +
 
 +
The examples below cover the most common use cases. It is assumed that you use the default location for documents ({{ic|/usr/share/nginx/html}}). If that is not the case, substitute your path instead.
 +
 
 +
=== Configuration example ===
 +
{{hc|/etc/nginx/nginx.conf|<nowiki>
 +
user http;
 +
worker_processes auto;
 +
worker_cpu_affinity auto;
 +
pcre_jit on;
 +
 
 +
events {
 +
    worker_connections 2048;
 +
}
 +
 
 +
 
 +
http {
 +
    include mime.types;
 +
    default_type application/octet-stream;
 +
    sendfile on;
 +
    tcp_nopush on;
 +
    aio threads;
 +
    server_tokens off; # Security: Disables nginx version in error messages and in the “Server” response header field.
 +
    charset utf-8; # Force usage of UTF-8
 +
    index index.php index.html index.htm;
 +
    # include sites-enabled/*; # See Server blocks
 +
}
 +
</nowiki>}}
 +
 
 +
=== General configuration ===
 +
 
 +
==== Processes and connections ====
 +
 
 +
You should choose a fitting value for {{ic|worker_processes}}. 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, {{ic|worker_processes}} accepts the {{ic|auto}} value since versions 1.3.8 and 1.2.5, which will try to autodetect the optimal value ([http://nginx.org/en/docs/ngx_core_module.html#worker_processes source]).
 +
 
 +
The maximum connections nginx will accept is given by {{ic|1=max_clients = worker_processes * worker_connections}}.
 +
 
 +
==== Running under different user ====
 +
 
 +
By default, {{Pkg|nginx}} runs the master process as {{ic|root}} and worker processes as user {{ic|http}}. To run worker processes as another user, change the {{ic|user}} directive in {{ic|nginx.conf}}:
 +
 
 +
{{hc|/etc/nginx/nginx.conf|
 +
user ''user'' [''group''];
 +
}}
 +
 
 +
If the group is omitted, a group whose name equals that of ''user'' is used.
 +
 
 +
{{Tip|1=It is also possible to run nginx without anything running as {{ic|root}} using [[systemd]]. See [[#Running unprivileged using systemd]].}}
 +
 
 +
==== Server blocks ====
 +
 
 +
It is possible to serve multiple domains using {{ic|server}} blocks. It may be referred as "VirtualHosts", however this is an [[Apache]] term. The usage of {{ic|server}} blocks also differs from [http://wiki.nginx.org/ServerBlockExample Apache].
 +
 
 +
In the example below the server listens for incoming connections for two domains: {{ic|domainname1.dom}} and {{ic|domainname2.dom}}:
 +
 
 +
{{hc|/etc/nginx/nginx.conf|<nowiki>
 +
...
 +
server {
 +
        listen 80;
 +
        server_name domainname1.dom;
 +
        root /usr/share/nginx/domainname1.dom/html;
 +
        location / {
 +
          index index.php index.html index.htm;
 +
        }
 +
}
 +
 
 +
server {
 +
        listen 80;
 +
        server_name domainname2.dom;
 +
        root /usr/share/nginx/domainname2.dom/html;
 +
        ...
 +
}
 +
...
 +
</nowiki>}}
 +
 
 +
[[Restart]] {{ic|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 {{ic|/etc/hosts}} replacing {{ic|192.168.0.101}} with the actual IP address of server:
 +
 
 +
192.168.0.101 domainname1.dom
 +
192.168.0.101 domainname2.dom
 +
 
 +
=====Managing server entries=====
 +
 
 +
It may be easier to use an [[Apache]] like [[Apache#Managing_many_virtual_hosts|Virtual hosts]] system.
 +
 
 +
Create the following directories:
 +
 
 +
# mkdir /etc/nginx/sites-available
 +
# mkdir /etc/nginx/sites-enabled
 +
 
 +
Create a file inside the {{ic|sites-available}} directory that contains one or more server blocks:
 +
 
 +
{{hc|/etc/nginx/sites-available/example|<nowiki>
 +
server {
 +
    ..
 +
}
 +
</nowiki>}}
 +
 
 +
Append the following line at the end of the {{ic|http}} block in /etc/nginx/nginx.conf:
 +
 
 +
include sites-enabled/*;
 +
 
 +
To enable a {{ic|server}}, simple create a symlink:
 +
 
 +
# ln -s /etc/nginx/sites-available/example /etc/nginx/sites-enabled/example
 +
 
 +
To remove a {{ic|server}}, delete the symlink:
 +
 
 +
# unlink /etc/nginx/sites-enabled/example
 +
 
 +
Reload or restart {{ic|nginx.service}} to enable the new configuration.
 +
 
 +
==== TLS/SSL ====
 +
 
 +
[[OpenSSL]] provides TLS/SSL support and is installed by default on Arch installations.
 +
 
 +
{{Tip|
 +
* You may want to read the [http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate ngx_http_ssl_module] docs first before configuring SSL.
 +
* [[Let’s Encrypt]] is a free, automated, and open certificate authority. A plugin is available to request valid SSL certificates straight from the command line and automatic configuration.
 +
* Mozilla has a useful [https://wiki.mozilla.org/Security/Server_Side_TLS SSL/TLS article] which includes [https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx nginx specific] configuration guidelines as well as an [https://mozilla.github.io/server-side-tls/ssl-config-generator/ automated tool] to help create a more secure configuration.
 +
* [https://cipherli.st Cipherli.st] provides strong SSL implementation examples and tutorial for most modern webservers.
 +
}}
 +
 
 +
{{Warning|If you plan on implementing SSL/TLS, know that some variations and implementations are [https://weakdh.org/#affected still] [[wikipedia:Transport_Layer_Security#Attacks_against_TLS.2FSSL|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}}
 +
 
 +
Create a private key and self-signed certificate. This is adequate for most installations that do not require a [[OpenSSL#Making_requests|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
 +
 
 +
{{Note|The {{ic|-days}} switch is optional and RSA keysize can be as low as 2048 (default).}}
 +
 
 +
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
 +
 
 +
{{Note|For more ''openssl'' options, read its [https://www.openssl.org/docs/apps/openssl.html man page] or peruse its [https://www.openssl.org/docs/ extensive documentation].}}
 +
 
 +
Example of a {{ic|nginx.conf}} using SSL:
 +
 
 +
{{hc|/etc/nginx/nginx.conf|<nowiki>
 +
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 8.8.8.8 8.8.4.4 valid=300s; # Google DNS Servers
 +
        resolver_timeout 5s;
 +
 
 +
# Redirect to HTTPS
 +
server {
 +
        listen 80;
 +
        server_name localhost;
 +
        return 301 https://$server_name$request_uri;
 +
}
 +
 
 +
server {
 +
        #listen 80; # Uncomment to also listen for HTTP requests
 +
        listen 443 ssl http2; # HTTP/2 is only possible when using SSL
 +
        server_name localhost;
 +
 
 +
        ssl_certificate ssl/server.crt;
 +
        ssl_certificate_key ssl/server.key;
 +
 
 +
        root /usr/share/nginx/html;
 +
        location / {
 +
            index index.html index.htm;
 +
        }
 +
}
 +
}
 +
</nowiki>}}
 +
 
 +
[[Restart]] {{ic|nginx.service}} to apply any changes.
 +
 
 +
==== Per-User Directories ====
 +
 
 +
To replicate Apache-style {{ic|~user}} URLs to users' {{ic|~/public_html}} directories, try the following. (Note: if both rules are used, below, the more-specific PHP rule must come first.)
 +
 
 +
{{hc|/etc/nginx/nginx.conf|<nowiki>
 +
...
 +
server {
 +
    ...
 +
    # PHP in user directories, e.g. http://example.com/~user/test.php
 +
    location ~ ^/~(.+?)(/.+\.php)$ {
 +
        alias          /home/$1/public_html$2;
 +
        fastcgi_pass  unix:/run/php-fpm/php-fpm.sock;
 +
        fastcgi_index  index.php;
 +
        include        fastcgi.conf;
 +
    }
 +
 
 +
    # User directories, e.g. http://example.com/~user/
 +
    location ~ ^/~(.+?)(/.*)?$ {
 +
        alias    /home/$1/public_html$2;
 +
        index    index.html index.htm;
 +
        autoindex on;
 +
    }
 +
    ...
 +
}
 +
...
 +
</nowiki>}}
 +
 
 +
See [[#PHP implementation]] for more information on PHP configuration with {{ic|nginx}}.
 +
 
 +
Restart {{ic|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 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 ====
 +
 
 +
[http://php-fpm.org/ PHP-FPM] is the recommended solution to run as FastCGI server for PHP. [[Install]] the {{Pkg|php}} and {{Pkg|php-fpm}} packages and configure PHP as described on the [[PHP]] page.
 +
 
 +
The main configuration file of PHP-FPM is {{ic|/etc/php/php-fpm.conf}}, then [[enable]] and [[start]] the systemd unit {{ic|php-fpm.service}}.
 +
 
 +
{{Note|
 +
* If you [[#Running_under_different_user|run nginx under different user]], make sure that the PHP-FPM socket file is accessible by this user, or use a TCP socket.
 +
* If you run nginx in chrooted environment (chroot is {{ic|/srv/nginx-jail}}, web pages are served at {{ic|/srv/nginx-jail/www}}), you must modify the file {{ic|/etc/php/php-fpm.conf}} to include the {{ic|chroot /srv/nginx-jail}} and {{ic|1=listen = /srv/nginx-jail/run/php-fpm/php-fpm.sock}} directives within the pool section (a default one is {{ic|[www]}}). Create the directory for the socket file, if missing.
 +
}}
 +
 
 +
===== nginx configuration =====
 +
 
 +
====== Adding to main configuration ======
 +
 
 +
Inside each {{ic|server}} block serving a PHP web application should appear a {{ic|location}} block similar to:
 +
 
 +
location ~ \.php$ {
 +
      try_files $uri $document_root$fastcgi_script_name =404;
 +
      fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
 +
      fastcgi_index index.php;
 +
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
 +
      include fastcgi.conf;
 +
}
 +
 
 +
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 be explicitly added in {{ic|/etc/php/php-fpm.d/www.conf}}:
 +
 
 +
security.limit_extensions = .php .html .htm
 +
 
 +
{{Note|Pay attention to the {{ic|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 {{ic|php-fpm}} is:
 +
 
 +
fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
 +
 
 +
You might use the common TCP socket, '''not default''',
 +
 
 +
fastcgi_pass 127.0.0.1:9000;
 +
 
 +
Unix domain sockets should however be faster.}}
 +
 
 +
======PHP configuration file======
 +
If using multiple {{ic|server}} blocks with enabled PHP support, it might be easier to create a PHP config file instead:
 +
{{hc|/etc/nginx/php.conf|<nowiki>
 +
location ~ \.php$ {
 +
    ...
 +
}
 +
</nowiki>}}
 +
 
 +
To enable PHP support for a particular server, simple include {{ic|php.conf}}:
 +
{{hc|/etc/nginx/nginx.conf|<nowiki>
 +
server {
 +
    server_name example.com;
 +
    ...
 +
    include php.conf;
 +
}
 +
</nowiki>}}
 +
 
 +
===== Test configuration =====
 +
 
 +
You need to [[restart]] the {{ic|php-fpm.service}} and {{ic|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 {{ic|root}} folder containing:
 +
 
 +
<?php phpinfo();
 +
 
 +
Navigate this file inside a browser and you will see the informational page with the current PHP configuration.
 +
 
 +
==== CGI implementation ====
 +
 
 +
This implementation is needed for CGI applications.
 +
 
 +
===== fcgiwrap =====
 +
 
 +
[[Install]] {{Pkg|fcgiwrap}}. The configuration file is {{ic|/usr/lib/systemd/system/fcgiwrap.socket}}. [[Enable]] and [[start]] {{ic|fcgiwrap.socket}}.
 +
 
 +
====== Multiple worker threads ======
 +
 
 +
If you want to spawn multiple worker threads, it is recommended that you use {{AUR|multiwatch}}, which will take care of restarting crashed children. You will need to use {{ic|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 {{ic|/usr/lib/systemd/system/fcgiwrap.service}} to {{ic|/etc/systemd/system/fcgiwrap.service}} (and the {{ic|fcgiwrap.socket}} unit, if present), and modify the {{ic|ExecStart}} line to suit your needs. Here is a unit file that uses {{AUR|multiwatch}}. Make sure {{ic|fcgiwrap.socket}} is not started or enabled, because it will conflict with this unit:
 +
 
 +
{{hc|/etc/systemd/system/fcgiwrap.service|2=
 +
[Unit]
 +
Description=Simple CGI Server
 +
After=nss-user-lookup.target
 +
 
 +
[Service]
 +
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
 +
PrivateTmp=true
 +
Restart=on-failure
 +
 
 +
[Install]
 +
WantedBy=multi-user.target
 +
}}
 +
 
 +
Tweak {{ic|-f 10}} to change the number of children that are spawned.
 +
 
 +
{{Warning|The {{ic|ExecStartPost}} line is required because of strange behaviour I'm seeing when I use the {{ic|-M 660}} option for {{ic|spawn-fcgi}}. The wrong mode is set. This may be a bug?}}
 +
 
 +
===== nginx configuration =====
 +
 
 +
Inside each {{ic|server}} block serving a CGI web application should appear a {{ic|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 {{ic|fcgiwrap}} is {{ic|/run/fcgiwrap.sock}}.
  
For a '''Ruby on Rails''' oriented installation, see [[RubyOnRails#Option_C:_The_Perfect_Rails_Setup|The Perfect Rails Setup]].
+
If you keep getting a {{ic|502 - bad Gateway}} error, you should check if your CGI-application first announces the mime-type of the following content. For html this needs to be {{ic|Content-type: text/html}}.
  
 
== Installation in a chroot ==
 
== Installation in a chroot ==
  
Installing Nginx in a chroot adds an additional layer of security. For
+
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 {{ic|/usr/bin}} should be unreadable and unwriteable, etc.
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 {{ic|/usr/bin}} should be unreadable and unwriteable,
 
etc.  
 
  
Arch comes with an {{ic|http}} user and group by default which will run the
+
Arch comes with an {{ic|http}} user and group by default which will run the server. The chroot will be in {{ic|/srv/http}}.
server. The chroot will be in {{ic|/srv/http}}.
 
  
A perl script to create this jail is available at
+
A perl script to create this jail is available at [https://gist.github.com/4365696 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.
[https://gist.github.com/4365696 jail.pl gist]. It expects to be run
 
as root. You will need to uncomment a line before it makes any changes.
 
  
=== Create Necessary Devices ===
+
=== Create necessary devices ===
  
Nginx needs {{ic|/dev/null}}, {{ic|/dev/random}}, and
+
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}}.
{{ic|/dev/urandom}}. To install these in the chroot we create the
 
{{ic|/dev/}} folder and add the devices with mknod. We 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|See {{ic|man mknod}} and {{ic|<nowiki>ls -l
+
{{Tip|Be sure that {{ic|/srv/http}} is mounted without no-dev option}}
/dev/{null,random,urandom}</nowiki>}} to better
+
{{Tip|See {{man|1|mknod}} and {{ic|<nowiki>ls -l /dev/{null,random,urandom}</nowiki>}} to better understand the ''mknod'' options.}}
understand the argument to mknod.}}
 
  
 
  # export JAIL=/srv/http
 
  # export JAIL=/srv/http
Line 47: Line 400:
 
  # mknod -m 0444 $JAIL/dev/urandom c 1 9
 
  # mknod -m 0444 $JAIL/dev/urandom c 1 9
  
=== Create Necessary Folders ===
+
=== Create necessary directories ===
  
Nginx requires a bunch of files to run properly. Before copying them
+
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 {{ic|/srv/http/www}}.
over, create the folders to store them. This assumes your Nginx document
 
root will be {{ic|/srv/http/www}}.
 
  
 
  # mkdir -p $JAIL/etc/nginx/logs
 
  # mkdir -p $JAIL/etc/nginx/logs
Line 59: Line 410:
 
  # mkdir -p $JAIL/www/cgi-bin
 
  # mkdir -p $JAIL/www/cgi-bin
 
  # mkdir -p $JAIL/{run,tmp}
 
  # mkdir -p $JAIL/{run,tmp}
  # cd $JAIL; ln -s usr/lib lib  
+
  # 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 ; ln -s usr/lib usr/lib64.}}
+
{{Note|If using a 64 bit kernel you will need to create symbolic links {{ic|lib64}} and {{ic|usr/lib64}} to {{ic|usr/lib}}: {{ic|cd $JAIL; ln -s usr/lib lib64}} and {{ic|cd $JAIL/usr; ln -s lib lib64}}.}}
  
Then mount {{ic|$JAIL/tmp}} and {{ic|$JAIL/run}} as tmpfs's. The size
+
Then mount {{ic|$JAIL/tmp}} and {{ic|$JAIL/run}} as tmpfs's. The size should be limited to ensure an attacker cannot eat all the RAM.
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/run -o 'noexec,size=1M'
 
  # mount -t tmpfs none $JAIL/tmp -o 'noexec,size=100M'
 
  # 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:
+
In order to preserve the mounts across reboots, the following entries should be added to {{ic|/etc/fstab}}:
  
 
{{hc|/etc/fstab|<nowiki>
 
{{hc|/etc/fstab|<nowiki>
Line 75: Line 425:
 
  tmpfs  /srv/http/tmp  tmpfs  rw,noexec,relatime,size=102400k 0      0
 
  tmpfs  /srv/http/tmp  tmpfs  rw,noexec,relatime,size=102400k 0      0
 
</nowiki>}}
 
</nowiki>}}
 
  
 
=== Populate the chroot ===
 
=== Populate the chroot ===
Line 86: Line 435:
 
  # cp -r /var/lib/nginx $JAIL/var/lib/nginx
 
  # cp -r /var/lib/nginx $JAIL/var/lib/nginx
  
Now copy over required libraries. Use ldd to list them and then copy
+
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.
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.
 
  
{{hc|$ ldd /usr/bin/nginx|<nowiki>
+
{{hc|$ ldd /usr/bin/nginx|<nowiki>
  linux-vdso.so.1 (0x00007fffc41fe000)
+
linux-vdso.so.1 (0x00007fffc41fe000)
  libpthread.so.0 => /usr/lib/libpthread.so.0 (0x00007f57ec3e8000)
+
libpthread.so.0 => /usr/lib/libpthread.so.0 (0x00007f57ec3e8000)
  libcrypt.so.1 => /usr/lib/libcrypt.so.1 (0x00007f57ec1b1000)
+
libcrypt.so.1 => /usr/lib/libcrypt.so.1 (0x00007f57ec1b1000)
  libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x00007f57ebead000)
+
libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x00007f57ebead000)
  libm.so.6 => /usr/lib/libm.so.6 (0x00007f57ebbaf000)
+
libm.so.6 => /usr/lib/libm.so.6 (0x00007f57ebbaf000)
  libpcre.so.1 => /usr/lib/libpcre.so.1 (0x00007f57eb94c000)
+
libpcre.so.1 => /usr/lib/libpcre.so.1 (0x00007f57eb94c000)
  libssl.so.1.0.0 => /usr/lib/libssl.so.1.0.0 (0x00007f57eb6e0000)
+
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)
+
libcrypto.so.1.0.0 => /usr/lib/libcrypto.so.1.0.0 (0x00007f57eb2d6000)
  libdl.so.2 => /usr/lib/libdl.so.2 (0x00007f57eb0d2000)
+
libdl.so.2 => /usr/lib/libdl.so.2 (0x00007f57eb0d2000)
  libz.so.1 => /usr/lib/libz.so.1 (0x00007f57eaebc000)
+
libz.so.1 => /usr/lib/libz.so.1 (0x00007f57eaebc000)
  libGeoIP.so.1 => /usr/lib/libGeoIP.so.1 (0x00007f57eac8d000)
+
libGeoIP.so.1 => /usr/lib/libGeoIP.so.1 (0x00007f57eac8d000)
  libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0x00007f57eaa77000)
+
libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0x00007f57eaa77000)
  libc.so.6 => /usr/lib/libc.so.6 (0x00007f57ea6ca000)
+
libc.so.6 => /usr/lib/libc.so.6 (0x00007f57ea6ca000)
  /lib64/ld-linux-x86-64.so.2 (0x00007f57ec604000)</nowiki>}}
+
/lib64/ld-linux-x86-64.so.2 (0x00007f57ec604000)</nowiki>}}
  
 
  # cp /lib64/ld-linux-x86-64.so.2 $JAIL/lib
 
  # cp /lib64/ld-linux-x86-64.so.2 $JAIL/lib
  
 
For files residing in {{ic|/usr/lib}} you may try the following one-liner:
 
For files residing in {{ic|/usr/lib}} you may try the following one-liner:
{{bc|<nowiki># cp $(ldd /usr/bin/nginx | grep /usr/lib | sed -sre 's/(.+)(\/usr\/lib\/\S+).+/\2/g') $JAIL/usr/lib</nowiki>}}
 
  
{{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.}}
+
# 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 {{ic|linux-vdso.so}}: it is not a real library and does not exist in {{ic|/usr/lib}}. Also {{ic|ld-linux-x86-64.so}} will likely be listed in {{ic|/lib64}} for a 64 bit system.}}
 +
 
 +
Copy over some miscellaneous but necessary libraries and system files.
  
Copy over some misc. 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
  
{{bc|# cp /usr/lib/libnss_* $JAIL/usr/lib
+
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.
# 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.
 
  
 
{{hc|$JAIL/etc/group|
 
{{hc|$JAIL/etc/group|
Line 133: Line 477:
 
nobody:x:99:99:nobody:/:/bin/false
 
nobody:x:99:99:nobody:/:/bin/false
 
}}
 
}}
 
+
 
 
{{hc|$JAIL/etc/shadow|
 
{{hc|$JAIL/etc/shadow|
 
http:x:14871::::::
 
http:x:14871::::::
 
nobody:x:14871::::::
 
nobody:x:14871::::::
 
}}
 
}}
 
+
 
 
{{hc|$JAIL/etc/gshadow|
 
{{hc|$JAIL/etc/gshadow|
 
http:::
 
http:::
 
nobody:::
 
nobody:::
 
}}
 
}}
 
+
 
 
  # touch $JAIL/etc/shells
 
  # touch $JAIL/etc/shells
 
  # touch $JAIL/run/nginx.pid
 
  # touch $JAIL/run/nginx.pid
  
Finally make set very restrictive permissions. As much as possible
+
Finally make set very restrictive permissions. As much as possible should be owned by root and set unwritable.
should be owned by root and set unwritable.
 
  
 
  # chown -R root:root $JAIL/
 
  # chown -R root:root $JAIL/
 
+
 
  # chown -R http:http $JAIL/www
 
  # chown -R http:http $JAIL/www
 
  # chown -R http:http $JAIL/etc/nginx
 
  # chown -R http:http $JAIL/etc/nginx
 
  # chown -R http:http $JAIL/var/{log,lib}/nginx
 
  # chown -R http:http $JAIL/var/{log,lib}/nginx
 
  # chown http:http $JAIL/run/nginx.pid
 
  # 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 -rw
 
  # find $JAIL/ -gid 0 -uid 0 -type d -print | xargs chmod +x
 
  # find $JAIL/ -gid 0 -uid 0 -type d -print | xargs chmod +x
Line 165: Line 508:
 
  # chmod +rw $JAIL/run
 
  # chmod +rw $JAIL/run
  
If your server will bind port 80 (or any port 0-1024), give the
+
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.
chrooted executable permission to bind these ports without root.
 
  
 
  # setcap 'cap_net_bind_service=+ep' $JAIL/usr/bin/nginx
 
  # setcap 'cap_net_bind_service=+ep' $JAIL/usr/bin/nginx
Line 172: Line 514:
 
=== Modify nginx.service to start chroot ===
 
=== Modify nginx.service to start chroot ===
  
Before modifying the nginx.service unit file, it may be a good idea to copy it to
+
Before modifying the {{ic|nginx.service}} unit file, it may be a good idea to copy it to {{ic|/etc/systemd/system/}} since the unit files there take priority over those in {{ic|/usr/lib/systemd/system/}}. This means upgrading nginx would not modify your custom ''.service'' file.
{{ic|/etc/systemd/system/}} since the unit files there take priority over those in {{ic|/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
 
  # 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 systemd unit must be changed to start up nginx in the chroot, as the http user, and store the pid file in the chroot.
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.}}
 
{{Note|I'm not sure if the pid file needs to be stored in the chroot jail.}}
  
Line 197: Line 538:
 
  WantedBy=multi-user.target</nowiki>}}
 
  WantedBy=multi-user.target</nowiki>}}
  
{{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. }}
+
{{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.
  
You can now safely get rid of the non-chrooted nginx installation.
 
 
  # pacman -Rsc nginx
 
  # 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 {{ic|/proc/{PID}/root}} symmlinks to. If should link to {{ic|/srv/http}} instead of {{ic|/}}.  
+
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 {{ic|/proc/''PID''/root}} symmlinks to. If should link to {{ic|/srv/http}} instead of {{ic|/}}.
 +
 
 
  # ps -C nginx | awk '{print $1}' | sed 1d | while read -r PID; do ls -l /proc/$PID/root; done
 
  # ps -C nginx | awk '{print $1}' | sed 1d | while read -r PID; do ls -l /proc/$PID/root; done
  
== Starting Service ==
+
== Tips and tricks ==
  
To enable the Nginx service by default at start-up, run:
 
# systemctl enable nginx
 
  
To start the Nginx service, run:
+
==== Running unprivileged using [[systemd]] ====
# systemctl start nginx
 
  
The default served page at http://127.0.0.1 is:  
+
[[systemd#Editing_provided_units|Edit nginx.service]] and set the {{ic|User}} and optionally {{ic|Group}} options under {{ic|[Service]}}:
/usr/share/nginx/html/index.html
+
{{hc|/etc/systemd/system/nginx.service.d/user.conf|2=
 +
[Service]
 +
User=''user''
 +
Group=''group''
 +
}}
  
== Configuring ==
+
We can harden the service against ever elevating privileges:
 +
{{hc|/etc/systemd/system/nginx.service.d/user.conf|2=
 +
[Service]
 +
...
 +
NoNewPrivileges=yes
 +
}}
  
You can modify the configuration by editing the files in {{ic|/etc/nginx/}}. The main configuration file is located at {{ic|/etc/nginx/nginx.conf}}.
+
{{Tip|1=See [http://www.freedesktop.org/software/systemd/man/systemd.exec.html#User= systemd.exec(5)] for more options of confinement.}}
  
More details can be found here: [http://wiki.nginx.org/NginxConfiguration Nginx Configuration Examples].
+
Then we need to ensure that {{ic|''user''}} has access to everything it needs:
  
=== FastCGI ===
+
<dl>
 +
<dt>Port</dt>
 +
<dd>
 +
Linux does not permit non-{{ic|root}} processes to bind to ports below 1024 by default. A port above 1024 can be used:
  
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 a server to handle more web page requests at once.
+
{{hc|/etc/nginx/nginx.conf|
 +
server {
 +
        listen 8080;
 +
}
 +
}}
  
FastCGI technology is introduced into Nginx to work with many external tools, i.e.: Perl, [[PHP]] and [[Python]]. So, you cannot use these unless a FastCGI server has been started.
+
{{Tip|1=If you want nginx accessible on port 80 or 443, configure your [[firewall]] to redirect requests from 80 or 443 to the ports nginx listens to.}}
 +
</dd>
 +
<dd>
 +
Or you may grant the nginx process the CAP_NET_BIND_SERVICE capability which will allow it to bind to ports below 1024:
  
==== PHP implementation ====
+
{{hc|/etc/systemd/system/nginx.service.d/user.conf|2=
 +
[Service]
 +
...
 +
CapabilityBoundingSet=
 +
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
 +
AmbientCapabilities=
 +
AmbientCapabilities=CAP_NET_BIND_SERVICE
 +
}}
 +
</dd>
  
There are different ways to run a FastCGI server for PHP. We cover '''php-fpm''', a recommended solution.
+
<dt>PID file</dt>
 +
<dd>
 +
{{Pkg|nginx}} uses {{ic|/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#Temporary_files|systemd-tmpfiles]]:
  
===== Step 1: PHP configuration =====
+
{{hc|/etc/tmpfiles.d/nginx.conf|2=
 
+
d /run/nginx 0775 root ''group'' - -
The {{Ic|open_basedir}} in {{ic|/etc/php/php.ini}} has to list base directories which contain PHP files, like {{ic|/srv/http/}} and {{ic|/usr/share/webapps/}}:
+
}}
open_basedir = /usr/share/webapps/:/srv/http/:/home/:/tmp/:/usr/share/pear/
 
 
 
===== Step 2: php-fpm =====
 
 
 
* http://php-fpm.org
 
 
 
Install {{Pkg|php-fpm}}.
 
The configuration file is {{ic|/etc/php/php-fpm.conf}}.
 
Enable and start the [[systemd]] ''php-fpm.service''.
 
 
 
===== Step 3: Nginx configuration =====
 
 
 
Inside each {{Ic|server}} block serving a PHP web application should appear a {{Ic|location}} block similar to:
 
  location ~ \.php$ {
 
      fastcgi_pass  unix:/run/php-fpm/php-fpm.sock;
 
      fastcgi_index  index.php;
 
      include        fastcgi.conf;
 
  }
 
 
 
You could create {{Ic|/etc/nginx/php.conf}} and save this configuration there, then when needed just include this file into the {{Ic|server}} block.
 
  server = {
 
      ...
 
      include  php.conf;
 
      ...
 
  }
 
 
If you are going to process .html and .htm files with PHP, you should have something like this:
 
  location ~ \.(php|html|htm)$ {
 
      fastcgi_pass  unix:/var/run/php-fpm/php-fpm.sock;
 
      fastcgi_index  index.php;
 
      include        fastcgi.conf;
 
  }
 
 
 
Non .php files processing in php-fpm should be explicitly enabled in
 
{{Ic|/etc/php/php-fpm.conf}}:
 
  security.limit_extensions = .php .html .htm
 
 
 
You need to restart the php-fpm daemon if you changed the configuration.
 
# systemctl restart php-fpm
 
 
 
'''Pay attention''' to the {{Ic|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 {{Ic|php-fpm}} is
 
fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
 
You might use the common TCP socket, '''not default''',
 
fastcgi_pass 127.0.0.1:9000;
 
Unix domain sockets are however faster.
 
 
 
{{Ic|fastcgi.conf}} or {{Ic|fastcgi_params}} are usually included because they hold FastCGI settings for Nginx; the use of the latter is deprecated, though. They come within the Nginx installation.
 
 
 
Finally, if Nginx has been working, run:
 
# systemctl restart nginx
 
 
 
If you would like to test the FastCGI implementation, create {{ic|/usr/share/nginx/html/index.php}} with content
 
<?php
 
  phpinfo();
 
?>
 
and visit the URL http://127.0.0.1/index.php with your browser.
 
 
 
==== CGI implementation ====
 
 
 
This implementation is needed for CGI applications.
 
 
 
===== Step 1: fcgiwrap =====
 
 
 
Install {{Pkg|fcgiwrap}}.
 
The configuration file is {{ic|/usr/lib/systemd/system/fcgiwrap.socket}}.
 
Enable and start the [[systemd]] ''fcgiwrap.socket''.
 
 
 
The systemd unit file is currently being discussed on [https://bugs.archlinux.org/task/31696 this ArchLinux task page].  You may want to examine the unit file yourself to ensure it will work the way you want.
 
  
====== Multiple worker threads ======
+
Run the configuration:
  
If you want to spawn multiple worker threads, it's recommended that you use {{aur|multiwatch}}, which will take care of restarting crashed children. You will need to use {{ic|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.
+
# systemd-tmpfiles --create
  
Copy the unit file from {{ic|/usr/lib/systemd/system/fcgiwrap.service}} to {{ic|/etc/systemd/system/fcgiwrap.service}} (and the {{ic|fcgiwrap.socket}} unit, if present), and modify the {{ic|ExecStart}} line to suit your needs. Here is a unit file that uses {{aur|multiwatch}}. Make sure {{ic|fcgiwrap.socket}} is not started or enabled, because it will conflict with this unit:
+
[[systemd#Editing_provided_units|Edit nginx.service]]:
 
 
{{hc|/etc/systemd/system/fcgiwrap.service|2=
 
[Unit]
 
Description=Simple CGI Server
 
After=nss-user-lookup.target
 
  
 +
{{hc|/etc/systemd/system/nginx.service.d/user.conf|2=
 
[Service]
 
[Service]
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
+
PIDFile=/run/nginx/nginx.pid
PrivateTmp=true
+
ExecStart=
Restart=on-failure
+
ExecStart=/usr/bin/nginx -g 'pid /run/nginx/nginx.pid; error_log stderr;' # copied from nginx.service
 
 
[Install]
 
WantedBy=multi-user.target
 
 
}}
 
}}
 +
</dd>
  
Tweak {{ic|-f 10}} to change the number of children that are spawned.
+
<dt>{{ic|/var/lib/nginx/*}}</dt>
 +
<dd>
 +
Some directories under {{ic|/var/lib/nginx}} need to be bootstrapped by nginx running as {{ic|root}}. It is not necessary to start the whole server to do that, nginx will do it on a simple [[#Configuration_validation|configuration test]]. So just run one of those and you're good to go.
 +
</dd>
  
{{Warning|The ExecStartPost line is required because of strange behaviour I'm seeing when I use the {{ic|-M 660}} option for {{ic|spawn-fcgi}}. The wrong mode is set.  This may be a bug?}}
+
<dt>Remove logs</dt>
 +
<dd>
 +
The step of running a configuration test will create a dangling {{ic|root}}-owned log. Remove logs in {{ic|/var/log/nginx}} to start fresh.
 +
</dl>
  
===== Step 2: Nginx configuration =====
+
Now we should be good to go. Go ahead and [[start]] nginx, and enjoy your completely rootless nginx.
  
Inside each {{Ic|server}} block serving a CGI web application should appear a {{Ic|location}} block similar to:
+
{{Tip|The same setup may be desirable for your [[#FastCGI|FastCGI server]] as well.}}
  
  location ~ \.cgi$ {
+
==== Nginx Beautifier ====
      fastcgi_pass  unix:/run/fcgiwrap.sock;
 
      include        fastcgi.conf;
 
  }
 
  
The '''default''' (Unix) socket for {{Ic|fcgiwrap}} is ''/run/fcgiwrap.sock''.
+
{{AUR|nginxbeautifier}} is a commandline tool used to beautify and format nginx configuration files.
  
 
== Troubleshooting ==
 
== Troubleshooting ==
  
=== Accessing local IP redirects to localhost ===
+
=== Configuration validation ===
  
Solution from the Arch Linux [https://bbs.archlinux.org/viewtopic.php?pid=780561#p780561 forum].
+
# nginx -t
  
Edit {{ic|/etc/nginx/nginx.conf}} and locate the "server_name localhost" line without a # infront of it, and add below:
+
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
  server_name_in_redirect off;
+
  nginx: configuration file /etc/nginx/nginx.conf test is successful
  
Default behavior is that nginx redirects any requests to the value given as server_name in the config.
+
=== Accessing local IP redirects to localhost ===
  
=== Error: 403 (Permission error) ===
+
Solution from the Arch Linux [https://bbs.archlinux.org/viewtopic.php?pid=780561#p780561 forum].
  
This is most likely a permission error. Are you sure whatever user configured in the Nginx configuration is able to read the correct files?
+
In {{ic|/etc/nginx/nginx.conf}} locate the {{ic|server_name localhost}} line without a {{ic|#}} in front of it, and add below:
  
If the files are located within a home directory, (e.g. {{ic|/home/arch/public/webapp}}) and you are sure the user running Nginx has the right permissions (you can temporarily chmod all the files to 777 in order to determine this), {{ic|/home/arch}} might be '''chmod 750''', simply {{Ic|chmod}} it to ''751'', and it should work.
+
server_name_in_redirect off;
  
'''If you have changed your document root'''
+
Default behavior is that nginx redirects any requests to the value given as {{ic|server_name}} in the config.
  
If you are sure that permissions are as they should be, make sure that your document root directory is not empty. Try creating index.html in there.
+
=== Error: The page you are looking for is temporarily unavailable. Please try again later. (502 Bad Gateway) ===
  
=== Error: 404 (Pathinfo error) ===
+
This is because the FastCGI server has not been started, or the socket used has wrong permissions.
  
In some framework (like thinkphp, cakephp) or CMS, they need the pathinfo function.  
+
Try [https://stackoverflow.com/questions/4252368/nginx-502-bad-gateway/16497957#16497957 out this answer] to fix the 502 error.
  
1. Edit the file {{ic|/etc/php/php.ini}}, make sure
+
In Archlinux, the configuration file mentioned in above link is {{ic|/etc/php/php-fpm.conf}}.
cgi.fix_pathinfo=1
 
2. Edit {{ic|/etc/nginx/conf/nginx.conf}}, comment
 
  
location ~ \.php$ {
+
=== Error: No input file specified ===
...
 
}
 
  
to
+
1. Verify that variable {{ic|open_basedir}} in {{ic|/etc/php/php.ini}} contains the correct path specified as {{ic|root}} argument in {{ic|nginx.conf}} (usually {{ic|/usr/share/nginx/}}). When using [http://php-fpm.org/ PHP-FPM] as FastCGI server for PHP, you may add {{ic|<nowiki>fastcgi_param PHP_ADMIN_VALUE "open_basedir=$document_root/:/tmp/:/proc/"</nowiki>;}} in the {{ic|location}} block which aims for processing php file in {{ic|nginx.conf}}.
  
#location ~ \.php$ {
+
2. Another occasion is that, wrong {{ic|root}} argument in the {{ic|location ~ \.php$}} section in {{ic|nginx.conf}}. Make sure the {{ic|root}} points to the same directory as it in {{ic|location /}} in the same server. Or you may just set root as global, do not define it in any location section.
#...
 
#}
 
  
Then add the follows,
+
3. Check permissions: e.g. {{ic|http}} for user/group, {{ic|755}} for directories and {{ic|644}} for files. Remember the entire path to the {{ic|html}} directory should have the correct permissions. See [[File permissions and attributes#Bulk chmod]] to bulk modify a directory tree.  
location ~ ^(.+\.php)(.*)$ {
 
  root  /srv/http/nginx;
 
  fastcgi_pass  unix:/var/run/php-fpm/php-fpm.sock;
 
  #fastcgi_pass  127.0.0.1:9000; #Un-comment this and comment "fastcgi_pass  unix:/var/run/php-fpm/php-fpm.sock;" if you are not using php-fpm.
 
  fastcgi_index index.php;
 
  set $document_root2 $document_root;
 
  if ($document_root2 ~ "^(.*\\\\).*?[\\\\|\/]\.\.\/(.*)$") { set $document_root2 $1$2; }
 
  if ($document_root2 ~ "^(.*\\\\).*?[\\\\|\/]\.\.\/(.*)$") { set $document_root2 $1$2; }
 
  if ($document_root2 ~ "^(.*\\\\).*?[\\\\|\/]\.\.\/(.*)$") { set $document_root2 $1$2; }
 
  if ($document_root2 ~ "^(.*\\\\).*?[\\\\|\/]\.\.\/(.*)$") { set $document_root2 $1$2; }
 
  if ($document_root2 ~ "^(.*\\\\).*?[\\\\|\/]\.\.\/(.*)$") { set $document_root2 $1$2; }
 
  fastcgi_split_path_info ^(.+\.php)(.*)$;
 
  fastcgi_param SCRIPT_FILENAME $document_root2$fastcgi_script_name;
 
  fastcgi_param PATH_INFO $fastcgi_path_info;
 
  fastcgi_param PATH_TRANSLATED $document_root2$fastcgi_path_info;
 
  include fastcgi_params;
 
  fastcgi_param  DOCUMENT_ROOT      $document_root2;
 
}
 
  
=== Error: The page you are looking for is temporarily unavailable. Please try again later. ===
+
4. You do not have the {{ic|SCRIPT_FILENAME}} containing the full path to your scripts. If the configuration of nginx ({{ic|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:
  
This is because the FastCGI server has not been started, or the socket used has wrong permissions.
+
# spawn-fcgi -a 127.0.0.1 -p 9000 -f /usr/bin/php-cgi
  
=== Error: No input file specified ===
+
or you should create a group and user to start the php-cgi:
  
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 127.0.0.1 -p 9000 -f /usr/bin/php-cgi
 
or you should create a group and user to start the php-cgi. For example:
 
 
  # groupadd www
 
  # groupadd www
 
  # useradd -g www www
 
  # useradd -g www www
Line 415: Line 685:
 
  # spawn-fcgi -a 127.0.0.1 -p 9000 -u www -g www -f /usr/bin/php-cgi
 
  # spawn-fcgi -a 127.0.0.1 -p 9000 -u www -g www -f /usr/bin/php-cgi
  
Another occasion is that, wrong "root" argument in the "location ~ \.php$" section in {{ic|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.
+
5. If you are running php-fpm with chrooted nginx ensure {{ic|chroot}} is set correctly within {{ic|/etc/php-fpm/php-fpm.d/www.conf}} (or {{ic|/etc/php-fpm/php-fpm.conf}} if working on older version)
 
 
Also keep in mind that your php script path was defined as {{ic|/srv/http}} by default using the variable "open_basedir" in {{ic|/etc/php/php.ini}}; you can change them if you need.
 
 
 
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: chroot: '/usr/sbin/nginx' No such file or directory ===
 
  
If you encounter this error when running the daemon of nginx using chroot, this is likely due to missing 64 bit libraries in the jailed environment.
+
=== Alternative script for systemd ===
  
If you are running chroot in {{ic|/srv/http}} you need to add the required 64 bit libraries.
+
{{Style|Does not belong into a "troubleshooting" section.}}
  
First, set up the directories (these commands will need to be run as root)
+
On pure systemd you can get advantages of chroot + systemd. [http://0pointer.de/blog/projects/changing-roots.html] Based on set [http://wiki.nginx.org/CoreModule#user user group] an pid on:
  
# mkdir /srv/http/usr/lib64
 
# cd /srv/http; ln -s usr/lib64 lib64
 
 
Then copy the required 64 bit libraries found using {{ic|ldd /usr/sbin/nginx}} to {{ic|/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 -> [http://0pointer.de/blog/projects/changing-roots.html  Systemd for Administrators, Part VI ]
 
Based on set [http://wiki.nginx.org/CoreModule#user user group] an pid on:
 
 
{{hc|/etc/nginx/nginx.conf|2=
 
{{hc|/etc/nginx/nginx.conf|2=
 
user http;
 
user http;
 
pid /run/nginx.pid;
 
pid /run/nginx.pid;
 
}}
 
}}
the absolute path of file is {{ic|/srv/http/etc/nginx/nginx.conf}}
+
 
 +
the absolute path of file is {{ic|/srv/http/etc/nginx/nginx.conf}}.
 +
 
 
{{hc|/etc/systemd/system/nginx.service|2=
 
{{hc|/etc/systemd/system/nginx.service|2=
 
[Unit]
 
[Unit]
Description=Nginx (Chroot)
+
Description=nginx (Chroot)
 
After=syslog.target network.target
 
After=syslog.target network.target
  
Line 462: Line 717:
 
WantedBy=multi-user.target
 
WantedBy=multi-user.target
 
}}
 
}}
Is not necesary set the default location, nginx loads at default {{ic| -c /etc/nginx/nginx.conf}}, but is a good idea set it. 
 
  
Alternatively can run '''only''' ExecStart as chroot whit parameter {{ic|RootDirectoryStartOnly}} set as yes [[http://www.freedesktop.org/software/systemd/man/systemd.service.html man systemd service]] or start it before mount point as efective or a [http://www.freedesktop.org/software/systemd/man/systemd.path.html systemd path] is available.
+
It is not necesary to set the default location, nginx loads at default {{ic| -c /etc/nginx/nginx.conf}}, but it is a good idea though.
 +
 
 +
Alternatively you can run '''only''' {{ic|ExecStart}} as chroot with parameter {{ic|RootDirectoryStartOnly}} set as {{ic|yes}} [http://www.freedesktop.org/software/systemd/man/systemd.service.html man systemd service] or start it before mount point as effective or a [http://www.freedesktop.org/software/systemd/man/systemd.path.html systemd path] is available.
  
 
{{hc|/etc/systemd/system/nginx.path|2=
 
{{hc|/etc/systemd/system/nginx.path|2=
 
[Unit]
 
[Unit]
Description=Nginx (Chroot) path
+
Description=nginx (Chroot) path
 
[Path]
 
[Path]
 
PathExists=/srv/http/site/Public_html
 
PathExists=/srv/http/site/Public_html
Line 474: Line 730:
 
WantedBy=default.target
 
WantedBy=default.target
 
}}
 
}}
to activate it
 
{{ic|systemctl enable nginx.path }}
 
and change on {{ic|/etc/systemd/system/nginx.service}} '''WantedBy=default.target''' to '''WantedBy=nginx.path'''
 
Practicality may be that the mount point delay unless the folder to be accessible, each time the point is accessible, systemd start the server. In my case, I prefer to mount, and before Bind to existing Dir. 
 
  
The {{ic| PIDFile}} on .service file allows Systemd to monitor process(absolute Path), If not the desired behavior, you can change to default one-shoot Type, and delete the reference on .service file.
+
[[Enable]] the created {{ic|nginx.path}} and change the {{ic|1=WantedBy=default.target}} to {{ic|1=WantedBy=nginx.path}} in {{ic|/etc/systemd/system/nginx.service}}.
 +
 
 +
The {{ic|PIDFile}} 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.
  
 +
== See also ==
  
== See Also ==
+
* [https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/ nginx configuration pitfalls]
* [[Nginx/Init_script|Init script for Nginx]]
+
* [https://calomel.org/nginx.html Very good in-depth 2014 look at nginx security and Reverse Proxying]
* [http://nginx.org/ Nginx Official Site]
+
* [http://www.tecmint.com/install-nginx-php-mysql-with-mariadb-engine-and-phpmyadmin-in-arch-linux/ Installing LEMP (nginx, PHP, MySQL with MariaDB engine and PhpMyAdmin) in Arch Linux]
* [http://calomel.org/nginx.html Nginx HowTo]
+
* [[Let’s Encrypt|Using SSL certificates generated with Let's Encrypt]]
* [http://wiki.gotux.net/config:nginx Easy Config Files]
 

Latest revision as of 23:42, 9 September 2017

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.

Nginx is often used together with a scripting language such as PHP and database such as MySQL. This combination is often referred to as a LEMP stack (Linux, EngineX, MySQL, PHP).

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 [1].

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.

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 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.

Configuration example

/etc/nginx/nginx.conf
user http;
worker_processes auto;
worker_cpu_affinity auto;
pcre_jit on;

events {
    worker_connections 2048;
}


http {
    include mime.types;
    default_type application/octet-stream;
    sendfile on;
    tcp_nopush on;
    aio threads;
    server_tokens off; # Security: Disables nginx version in error messages and in the “Server” response header field.
    charset utf-8; # Force usage of UTF-8
    index index.php index.html index.htm;
    # include sites-enabled/*; # See Server blocks
}

General configuration

Processes and connections

You should choose a fitting value for worker_processes. 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, 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 the master process as root and worker processes as user http. To run worker processes as another user, change the user directive in nginx.conf:

/etc/nginx/nginx.conf
user user [group];

If the group is omitted, a group whose name equals that of user is used.

Tip: It is also possible to run nginx without anything running as root using systemd. See #Running unprivileged using systemd.

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 from Apache.

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

/etc/nginx/nginx.conf
...
server {
        listen 80;
        server_name domainname1.dom;
        root /usr/share/nginx/domainname1.dom/html;
        location / {
           index index.php index.html index.htm;
        }
}

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

Restart 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 192.168.0.101 with the actual IP address of server:

192.168.0.101 domainname1.dom
192.168.0.101 domainname2.dom
Managing server entries

It may be easier to use an Apache like Virtual hosts system.

Create the following directories:

# mkdir /etc/nginx/sites-available
# mkdir /etc/nginx/sites-enabled

Create a file inside the sites-available directory that contains one or more server blocks:

/etc/nginx/sites-available/example
server {
    ..
}

Append the following line at the end of the http block in /etc/nginx/nginx.conf:

include sites-enabled/*;

To enable a server, simple create a symlink:

# ln -s /etc/nginx/sites-available/example /etc/nginx/sites-enabled/example

To remove a server, delete the symlink:

# unlink /etc/nginx/sites-enabled/example

Reload or restart nginx.service to enable the new configuration.

TLS/SSL

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.
  • Let’s Encrypt is a free, automated, and open certificate authority. A plugin is available to request valid SSL certificates straight from the command line and automatic configuration.
  • 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.
  • Cipherli.st provides strong SSL implementation examples and tutorial for most modern webservers.
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

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
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 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
Note: For more openssl options, read its man page or peruse its extensive documentation.

Example of a nginx.conf using SSL:

/etc/nginx/nginx.conf
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 8.8.8.8 8.8.4.4 valid=300s; # Google DNS Servers
        resolver_timeout 5s;

# Redirect to HTTPS
server {
        listen 80;
        server_name localhost;
        return 301 https://$server_name$request_uri;
}

server {
        #listen 80; # Uncomment to also listen for HTTP requests
        listen 443 ssl http2; # HTTP/2 is only possible when using SSL
        server_name localhost;

        ssl_certificate ssl/server.crt;
        ssl_certificate_key ssl/server.key;

        root /usr/share/nginx/html;
        location / {
            index index.html index.htm;
        }
}
}

Restart nginx.service to apply any changes.

Per-User Directories

To replicate Apache-style ~user URLs to users' ~/public_html directories, try the following. (Note: if both rules are used, below, the more-specific PHP rule must come first.)

/etc/nginx/nginx.conf
...
server {
    ...
    # PHP in user directories, e.g. http://example.com/~user/test.php
    location ~ ^/~(.+?)(/.+\.php)$ {
        alias          /home/$1/public_html$2;
        fastcgi_pass   unix:/run/php-fpm/php-fpm.sock;
        fastcgi_index  index.php;
        include        fastcgi.conf;
    }

    # User directories, e.g. http://example.com/~user/
    location ~ ^/~(.+?)(/.*)?$ {
        alias     /home/$1/public_html$2;
        index     index.html index.htm;
        autoindex on;
    }
    ...
}
...

See #PHP implementation for more information on PHP configuration with nginx.

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 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. Install the php and php-fpm packages and configure PHP as described on the PHP page.

The main configuration file of PHP-FPM is /etc/php/php-fpm.conf, then enable and start the systemd unit php-fpm.service.

Note:
  • If you run nginx under different user, make sure that the PHP-FPM socket file is accessible by this user, or use a TCP socket.
  • 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.
nginx configuration
Adding to main configuration

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

location ~ \.php$ {
     try_files $uri $document_root$fastcgi_script_name =404;
     fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
     fastcgi_index index.php;
     fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
     include fastcgi.conf;
}

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 be explicitly added in /etc/php/php-fpm.d/www.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,

fastcgi_pass 127.0.0.1:9000;
Unix domain sockets should however be faster.
PHP configuration file

If using multiple server blocks with enabled PHP support, it might be easier to create a PHP config file instead:

/etc/nginx/php.conf
location ~ \.php$ {
     ...
}

To enable PHP support for a particular server, simple include php.conf:

/etc/nginx/nginx.conf
 server {
     server_name example.com;
     ...
     include php.conf;
 }
Test configuration

You need to restart the php-fpm.service 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 root folder containing:

<?php phpinfo();

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

CGI implementation

This implementation is needed for CGI applications.

fcgiwrap

Install fcgiwrap. The configuration file is /usr/lib/systemd/system/fcgiwrap.socket. Enable and start 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:

/etc/systemd/system/fcgiwrap.service
[Unit]
Description=Simple CGI Server
After=nss-user-lookup.target

[Service]
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
PrivateTmp=true
Restart=on-failure

[Install]
WantedBy=multi-user.target

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.

If you keep getting a 502 - bad Gateway error, you should check if your CGI-application first announces the mime-type of the following content. For html this needs to be Content-type: text/html.

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 /srv/http is mounted without no-dev option
Tip: 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 /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:

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

$JAIL/etc/group
http:x:33:
nobody:x:99:
$JAIL/etc/passwd
http:x:33:33:http:/:/bin/false
nobody:x:99:99:nobody:/:/bin/false
$JAIL/etc/shadow
http:x:14871::::::
nobody:x:14871::::::
$JAIL/etc/gshadow
http:::
nobody:::
# 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

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.
/etc/systemd/system/nginx.service
 [Unit]
 Description=A high performance web server and a reverse proxy server
 After=syslog.target network.target
 
 [Service]
 Type=forking
 PIDFile=/srv/http/run/nginx.pid
 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
 
 [Install]
 WantedBy=multi-user.target
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

Tips and tricks

Running unprivileged using systemd

Edit nginx.service and set the User and optionally Group options under [Service]:

/etc/systemd/system/nginx.service.d/user.conf
[Service]
User=user
Group=group

We can harden the service against ever elevating privileges:

/etc/systemd/system/nginx.service.d/user.conf
[Service]
...
NoNewPrivileges=yes
Tip: See systemd.exec(5) for more options of confinement.

Then we need to ensure that user has access to everything it needs:

Port
Linux does not permit non-root processes to bind to ports below 1024 by default. A port above 1024 can be used:
/etc/nginx/nginx.conf
server {
        listen 8080;
}
Tip: If you want nginx accessible on port 80 or 443, configure your firewall to redirect requests from 80 or 443 to the ports nginx listens to.

Or you may grant the nginx process the CAP_NET_BIND_SERVICE capability which will allow it to bind to ports below 1024:

/etc/systemd/system/nginx.service.d/user.conf
[Service]
...
CapabilityBoundingSet=
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=
AmbientCapabilities=CAP_NET_BIND_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:

/etc/tmpfiles.d/nginx.conf
d /run/nginx 0775 root group - -

Run the configuration:

# systemd-tmpfiles --create

Edit nginx.service:

/etc/systemd/system/nginx.service.d/user.conf
[Service]
...
PIDFile=/run/nginx/nginx.pid
ExecStart=
ExecStart=/usr/bin/nginx -g 'pid /run/nginx/nginx.pid; error_log stderr;' # copied from nginx.service

/var/lib/nginx/*
Some directories under /var/lib/nginx need to be bootstrapped by nginx running as root. 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're good to go.

Remove logs
The step of running a configuration test will create a dangling root-owned log. Remove logs in /var/log/nginx to start fresh.

Now we should be good to go. Go ahead and start nginx, and enjoy your completely rootless nginx.

Tip: The same setup may be desirable for your FastCGI server as well.

Nginx Beautifier

nginxbeautifierAUR is a commandline tool used to beautify and format nginx configuration files.

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

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: 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 Archlinux, the configuration file mentioned in above link is /etc/php/php-fpm.conf.

Error: No input file specified

1. Verify that variable open_basedir in /etc/php/php.ini contains the correct path specified as root argument in nginx.conf (usually /usr/share/nginx/). When using PHP-FPM as FastCGI server for PHP, you may add fastcgi_param PHP_ADMIN_VALUE "open_basedir=$document_root/:/tmp/:/proc/"; in the location block which aims for processing php file in nginx.conf.

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. Check permissions: e.g. http for user/group, 755 for directories and 644 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 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 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 chroot is set correctly within /etc/php-fpm/php-fpm.d/www.conf (or /etc/php-fpm/php-fpm.conf if working on older version)

Alternative script for systemd

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements.Tango-edit-clear.png

Reason: Does not belong into a "troubleshooting" section. (Discuss in Talk:Nginx#)

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

/etc/nginx/nginx.conf
user http;
pid /run/nginx.pid;

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

/etc/systemd/system/nginx.service
[Unit]
Description=nginx (Chroot)
After=syslog.target network.target

[Service]
Type=forking
PIDFile=/srv/http/run/nginx.pid
RootDirectory=/srv/http
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

[Install]
WantedBy=multi-user.target

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.

/etc/systemd/system/nginx.path
[Unit]
Description=nginx (Chroot) path
[Path]
PathExists=/srv/http/site/Public_html
[Install]
WantedBy=default.target

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-shot type, and delete the reference from the unit file.

See also