nginx

nginx (pronounced "engine X"), is a free, open-source, high-performance HTTP server and reverse proxy, as well as an IMAP/POP3 proxy server, written by Igor Sysoev in 2005. nginx is well known for its stability, rich feature set, simple configuration, and low resource consumption.

This article describes how to set up nginx and how to optionally integrate it with PHP via #FastCGI.

Installation

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

Note: All nginx modules available in the official repositories require the nginx package (as opposed to nginx-mainline) as a dependency. It may be wise to review the list of modules for any you might need/want before making the nginx vs nginx-mainline decision. Modules for nginx-mainline can be found in the Arch User Repository.

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.

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, e.g. Perl, PHP and Python.

PHP implementation

Installphp-fpm and make sure PHP has been installed and configured correctly. The main configuration file of PHP-FPM is /etc/php/php-fpm.conf. For basic usage the default configuration should be sufficient.

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. Moreover, for modules that are dynamically linked to dependencies, you will need to copy those dependencies to the chroot (e.g. for php-imagick, you will need to copy the ImageMagick libraries to the chroot, but not imagick.so itself).

nginx configuration

Adding to main configuration

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

CGI implementation

fcgiwrap

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:

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.

Populate the chroot

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.

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.

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.

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

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.

Log file & Directory Permissions

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

The nginx service user needs write permission to /var/log/nginx. This may require changing permission and/or ownership of this directory on your system.

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

Error: The page you are looking for is temporarily unavailable. Please try again later. (502 Bad Gateway)

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: