Difference between revisions of "Nginx"

From ArchWiki
Jump to: navigation, search
(wikify some external links, use https for archlinux.org)
(CGI implementation: Attempting to tidy up fcgiwrapper configuration)
Line 132: Line 132:
  
 
This implementation is needed for CGI applications.
 
This implementation is needed for CGI applications.
 
===== fcgiwrap =====
 
  
 
Install {{Pkg|fcgiwrap}}:
 
Install {{Pkg|fcgiwrap}}:
 
  # pacman -Sy fcgiwrap
 
  # pacman -Sy fcgiwrap
 +
 +
===== Systemd =====
 +
 +
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.  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.
 +
 +
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'll 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 doesn't have any trouble if invoked directly in the unit file.  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]
 +
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 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?}}
 +
 +
===== Initscripts =====
  
 
====== Using a Unix Domain Socket ======
 
====== Using a Unix Domain Socket ======
  
The default configuration sets TCP socket 127.0.0.1:9001 for listening.  It is possible to alter the configuration to use a Unix domain socket, which will be more efficient. Configuration depends on whether you're using initscripts or systemd:
+
The default configuration sets TCP socket 127.0.0.1:9001 for listening.  It is possible to alter the configuration to use a Unix domain socket, which will be more efficient.
 
+
; initscripts
+
  
 
If you desire to use a Unix domain socket, edit {{ic|/etc/conf.d/fcgiwrap}} like this:
 
If you desire to use a Unix domain socket, edit {{ic|/etc/conf.d/fcgiwrap}} like this:
 
  SPAWNER='/usr/bin/spawn-fcgi'
 
  SPAWNER='/usr/bin/spawn-fcgi'
 
   
 
   
  FCGI_SOCKET='/var/run/fcgiwrap.sock'
+
  FCGI_SOCKET='/run/fcgiwrap.sock'
 
  FCGI_USER='http'
 
  FCGI_USER='http'
 
  FCGI_GROUP='http'
 
  FCGI_GROUP='http'
  FCGI_EXTRA_OPTIONS='-M 700'
+
  FCGI_EXTRA_OPTIONS='-M 660'
 
   
 
   
 
  SPAWNER_ARGS="-u $FCGI_USER -g $FCGI_GROUP -s $FCGI_SOCKET $FCGI_EXTRA_OPTIONS -- /usr/sbin/fcgiwrap"
 
  SPAWNER_ARGS="-u $FCGI_USER -g $FCGI_GROUP -s $FCGI_SOCKET $FCGI_EXTRA_OPTIONS -- /usr/sbin/fcgiwrap"
Line 156: Line 179:
 
  # rc.d start fcgiwrap
 
  # rc.d start fcgiwrap
 
and add {{Ic|fcgiwrap}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}.
 
and add {{Ic|fcgiwrap}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}.
 
; systemd
 
 
Copy the unit file from {{ic|/usr/lib/systemd/system/fcgiwrap.service}} to {{ic|/etc/systemd/system/fcgiwrap.service}}, and modify the {{ic|ExecStart}} line to read as follows:
 
 
  ExecStart=/usr/bin/spawn-fcgi -u http -g http -s /var/run/fcgiwrap.sock -M 700 -P /var/run/fcgiwrap.pid -- /usr/sbin/fcgiwrap
 
 
; Nginx
 
 
Inside each {{Ic|server}} block serving a PHP web application should appear a {{Ic|location}} block similar to:
 
 
  location ~ \.cgi$ {
 
      fastcgi_pass  unix:/var/run/fcgiwrap.sock;
 
      include        fastcgi.conf;
 
  }
 
   
 
  location ~ \.pl$ {
 
      fastcgi_pass  unix:/var/run/fcgiwrap.sock;
 
      include        fastcgi.conf;
 
  }
 
  
 
====== Multiple Workers ======
 
====== Multiple Workers ======
  
You can increase the number of worker threads by adding the {{ic|-F <num>}} option to the {{ic|SPAWNER_ARGS}} variable in '''/etc/conf.d/fcgiwrap''' (if using initscripts), or the ExecStart line (if using systemd).  Although this option will work, you may find it difficult to monitor the workers, because they have no parent process.
+
You can increase the number of worker threads by adding the {{ic|-F <num>}} option to the {{ic|SPAWNER_ARGS}} variable in '''/etc/conf.d/fcgiwrap'''.  Although this option will work, you may find it difficult to monitor the workers, because they have no parent process.
  
 
A better way to handle multiple worker threads is to use the [https://aur.archlinux.org/packages.php?ID=60080 multiwatch] package from the [[AUR]].  After installing the package, perform the following configuration to achieve this:
 
A better way to handle multiple worker threads is to use the [https://aur.archlinux.org/packages.php?ID=60080 multiwatch] package from the [[AUR]].  After installing the package, perform the following configuration to achieve this:
 
; initscripts
 
  
 
Add the following line near the top of the '''/etc/conf.d/fcgiwrap''' file:
 
Add the following line near the top of the '''/etc/conf.d/fcgiwrap''' file:
Line 196: Line 197:
 
You'll find that the '''/etc/rc.d/fcgiwrap''' script now creates a '''/run/multiwatch.pid''' file instead of the old '''/run/fcgiwrap.pid''' file.  The multiwatch daemon will take care of respawning children that die.
 
You'll find that the '''/etc/rc.d/fcgiwrap''' script now creates a '''/run/multiwatch.pid''' file instead of the old '''/run/fcgiwrap.pid''' file.  The multiwatch daemon will take care of respawning children that die.
  
; systemd
+
===== Nginx Configuration =====
  
Modify the ExecStart line to add the invocation of multiwatch, like this:
+
Inside each {{Ic|server}} block serving a PHP web application should appear a {{Ic|location}} block similar to:
  
   ExecStart=/usr/bin/spawn-fcgi -u http -g http -s /var/run/fcgiwrap.sock -M 700 -P /var/run/fcgiwrap.pid -- /usr/bin/multiwatch -f 2 -- /usr/sbin/fcgiwrap
+
   location ~ \.cgi$ {
 
+
      fastcgi_pass  unix:/run/fcgiwrap.sock;
The {{ic|-f 2}} option controls the number of children that are spawned, so tweak this as required.  The multiwatch daemon will take care of respawning children that die.
+
      include        fastcgi.conf;
 
+
  }
{{Note|There is probably a nice systemd-ish way of controlling a pool of fcgiwrap workers using service templates combined with a socket unit file. Until this surfaces, though, multiwatch is still a good option, mainly because of the automatic respawning of children.}}
+
   
 +
  location ~ \.pl$ {
 +
      fastcgi_pass  unix:/run/fcgiwrap.sock;
 +
      include        fastcgi.conf;
 +
  }
  
 
== Troubleshooting ==
 
== Troubleshooting ==

Revision as of 12:54, 20 December 2012

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 April 2012 Web Server Survey, Nginx now hosts 10.32% of all domains worldwide, while Apache hosts about 65.46%. Nginx is now well known for its stability, rich feature set, simple configuration, and low resource consumption.

Installation

Install package nginx in the official repositories.

For a Ruby on Rails oriented installation, see The Perfect Rails Setup.

Starting Service

To start the Nginx service, run:

# rc.d start nginx

The default served page at http://127.0.0.1 is:

/usr/share/nginx/html/index.html

To enable the Nginx service by default at start-up just add nginx to the DAEMONS array in /etc/rc.conf:

DAEMONS=(ntpd syslog-ng ... nginx)

Using Systemd

To start the Nginx service, run:

# systemctl start nginx

To enable the Nginx service by default at start-up, run:

# systemctl enable nginx

Configuring

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 can be found here: Nginx Configuration Examples.

FastCGI

FastCGI, also FCGI, is a protocol for interfacing interactive programs with a web server. FastCGI is a variation on the earlier Common Gateway Interface (CGI); FastCGI's main aim is to reduce the overhead associated with interfacing the web server and CGI programs, allowing 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. So, you cannot use these unless a FastCGI server has been started.

PHP implementation

There are different ways to run a FastCGI server for PHP.

Step 1: PHP configuration

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

open_basedir = /usr/share/webapps/:/srv/http/:/home/:/tmp/:/usr/share/pear/
Step 2, option A: php-fpm

Install php-fpm:

# pacman -S php-fpm

The configuration file is /etc/php/php-fpm.conf.

To start the service:

# systemctl start php-fpm

Enable php-fpm at startup

# systemctl enable php-fpm.service
Step 2, option B: spawn-fcgi-php

Install spawn-fcgi-phpAUR, available at AUR:

$ yaourt -Sy spawn-fcgi-php

The configuration file is /etc/conf.d/spawn-fcgi-php.conf.

To start the service:

# rc.d start spawn-fcgi-php

Add spawn-fcgi-php to the DAEMONS array in /etc/rc.conf.

Step 3: Nginx configuration

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

/etc/nginx/nginx.conf

 location ~ \.php$ {
      fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
      fastcgi_index  index.php;
      root           /usr/share/nginx/html;
      include        fastcgi.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;
      root           /usr/share/nginx/html;
      include        fastcgi.conf;
 }
 location / {
      root   /usr/share/nginx/html;
      index  index.html index.htm index.php;
 }

Non .php files processing in php-fpm should be explicitly enabled in configuration /etc/php/php-fpm.conf

 security.limit_extensions = .php .html .htm

You need to restart a php-fpm daemon if you changed configuration

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 for php-fpm is

fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;

and for spawn-fcgi-php,

fastcgi_pass unix:/var/run/spawn-fcgi-php.sock;

. Or you may use the common TCP socket, not default,

fastcgi_pass 127.0.0.1:9000;

. Unix domain sockets are however much better.

fastcgi.conf or 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:

# rc.d restart nginx

If you would like to test the FastCGI implementation, create /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.

Install fcgiwrap:

# pacman -Sy fcgiwrap
Systemd

The systemd unit file is currently being discussed on this ArchLinux task page. You may want to examine the unit file yourself to ensure it will work the way you want. 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.

If you want to spawn multiple worker threads, it's recommended that you use multiwatchAUR, which will take care of restarting crashed children. You'll need to use spawn-fcgi to create the unix socket, as multiwatch seems unable to handle the systemd-created socket, even though fcgiwrap itself doesn't have any trouble if invoked directly in the unit file. 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]
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?
Initscripts
Using a Unix Domain Socket

The default configuration sets TCP socket 127.0.0.1:9001 for listening. It is possible to alter the configuration to use a Unix domain socket, which will be more efficient.

If you desire to use a Unix domain socket, edit /etc/conf.d/fcgiwrap like this:

SPAWNER='/usr/bin/spawn-fcgi'

FCGI_SOCKET='/run/fcgiwrap.sock'
FCGI_USER='http'
FCGI_GROUP='http'
FCGI_EXTRA_OPTIONS='-M 660'

SPAWNER_ARGS="-u $FCGI_USER -g $FCGI_GROUP -s $FCGI_SOCKET $FCGI_EXTRA_OPTIONS -- /usr/sbin/fcgiwrap"

Start the service:

# rc.d start fcgiwrap

and add fcgiwrap to the DAEMONS array in /etc/rc.conf.

Multiple Workers

You can increase the number of worker threads by adding the -F <num> option to the SPAWNER_ARGS variable in /etc/conf.d/fcgiwrap. Although this option will work, you may find it difficult to monitor the workers, because they have no parent process.

A better way to handle multiple worker threads is to use the multiwatch package from the AUR. After installing the package, perform the following configuration to achieve this:

Add the following line near the top of the /etc/conf.d/fcgiwrap file:

DAEMON='multiwatch'

and modify the SPAWNER_ARGS line:

FCGI_CHILDREN=5
SPAWNER_ARGS="-u $FCGI_USER -g $FCGI_GROUP -s $FCGI_SOCKET $FCGI_EXTRA_OPTIONS -- /usr/bin/multiwatch -f $FCGI_CHILDREN -- /usr/sbin/fcgiwrap"

You'll find that the /etc/rc.d/fcgiwrap script now creates a /run/multiwatch.pid file instead of the old /run/fcgiwrap.pid file. The multiwatch daemon will take care of respawning children that die.

Nginx Configuration

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

 location ~ \.cgi$ {
      fastcgi_pass   unix:/run/fcgiwrap.sock;
      include        fastcgi.conf;
 }
   
 location ~ \.pl$ {
      fastcgi_pass   unix:/run/fcgiwrap.sock;
      include        fastcgi.conf;
 }

Troubleshooting

Accessing local IP redirects to localhost

Solution from the Arch Linux forum.

Edit /etc/nginx/nginx.conf and locate the "server_name localhost" line without a # infront 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. Are you sure whatever user configured in the Nginx configuration is able to read the correct files?

If the files are located within a home directory, (e.g. /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), /home/arch might be chmod 750, simply chmod it to 751, and it should work.

If you have changed your document root

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: 404 (Pathinfo error)

In some framework (like thinkphp, cakephp) or CMS, they need the pathinfo function.

1. Edit the file /etc/php/php.ini, make sure

cgi.fix_pathinfo=1

2. Edit /etc/nginx/conf/nginx.conf, comment

location ~ \.php$ {
...
}

to

#location ~ \.php$ {
#...
#}

Then add the follows,

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.

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

Error: No input file specified

Most Likely you do not have the SCRIPT_FILENAME containing the full path to you scripts. If the configuration of nginx (fastcgi_param SCRIPT_FILENAME) is all right, this kind of error means php fail to load the requestd 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 some group and user to start the php-cgi. For example:

# 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

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.

Also keep in mind that your php script path was defined as /srv/www/nginx/html by default using the variable "open_basedir" in /etc/php/php.ini; you can change them if you need.

See Also