Codex Nginx Page

Nginx_Codex

{{Stub}}

While the LAMP stack is very popular (Linux + Apache + MySQL + PHP) for powering WordPress, a lot of people have started using Nginx in place of Apache. This page aims to help those looking to configure WordPress with Nginx.

Before you consider using Nginx, be aware that PHP APC or a similar opcode cache with a WordPress caching plugin is going to offer significant performance improvements over just switching from Apache to nginx. If you aren't already using a PHP opcode cache and WordPress caching plugin, Nginx will do little for your WordPress-based website's performance.  WordPress development is intertwined with the Apache world, and as a result, support for Nginx-based setups is limited; but it is growing.  Factor these things into your decision to use Nginx.

This is '''not going to cover''' how to install and configure Nginx, so this assumes that you have already installed Nginx and have a basic understanding of how to work with it.

'''Note''': This has been tested on and known to work with:

* Arch Linux 64 bit (Nginx 0.8.54)
* Mac OSX Server Leopard and OSX Server Snow Leopard via MacPorts (Nginx 0.8.54, php-fpm support requires modifying the PHP 5.3 'Portfile')
* Ubuntu Server 10.04 LTS (Nginx 0.8.54 with php-fpm)


== Generic and Network (Multi-Site) Support ==

To make WordPress work with Nginx you have to configure the backend php-cgi.  The options available are 'fastcgi' or 'php-fpm'.  Here I'm using php-fpm because it is included in PHP 5.3, so installing it is more straightforward.

The Nginx configuration has been broken up into five distinct files and it's heavily commented to make each option easier to understand. The [http://wordpress.org/support/profile/bigsite author] also made a best-effort attempting to follow "best practices" for nginx configurations.

=== Main (generic) startup file ===

This is equivalent to /etc/nginx/nginx.conf (or /etc/nginx/conf/nginx.conf if you're using Arch Linux).

<pre>
# Generic startup file.
user {user} {group};

#ususally equal to number of CPU's you have. run command "grep processor /proc/cpuinfo | wc -l" to find it
worker_processes  2;

error_log  /var/log/nginx/error.log;
pid        /var/run/nginx.pid;

# Keeps the logs free of messages about not being able to bind().
#daemon     off;

events {
	worker_connections  1024;
}

http {
#	rewrite_log on;

	include mime.types;
	default_type       application/octet-stream;
	access_log         /var/log/nginx/access.log;
	sendfile           on;
#	tcp_nopush         on;
	keepalive_timeout  3;
#	tcp_nodelay        on;
#	gzip               on;
        #php max upload limit cannot be larger than this       
	client_max_body_size 13m;
	index              index.php index.html index.htm;

	# Upstream to abstract backend connection(s) for PHP.
	upstream php {
                #this should match value of "listen" directive in php-fpm pool
		server unix:/tmp/php-fpm.sock;
#		server 127.0.0.1:9000;
	}

	include sites-enabled/*;
}
</pre>

Now, you'll observe that this is a bit different from most nginx.conf files. I opted to follow the Ubuntu/Debian method of declaring enabled sites for maximum flexibility - using 'sites-available' to store a config and then symlink to the config file from 'sites-enabled'.  It takes a little extra effort to set up but is well worth that effort for managing multiple websites.

=== Per Site configuration ===

<pre>
# Redirect everything to the main site. We use a separate server statement and NOT an if statement - see http://wiki.nginx.org/IfIsEvil

server {
        server_name  _;
        rewrite ^ $scheme://mysite.com$request_uri redirect;
}

server {
	server_name mysite.com;
	root /var/www/mysite.com;

	include global/restrictions.conf;

	# Additional rules go here.

	# Only include one of the files below.
	include global/wordpress.conf;
#	include global/wordpress-ms-subdir.conf;
#	include global/wordpress-ms-subdomain.conf;
}
</pre>

If you look around the Internet, you can find various WordPress configs for nginx. Most of them drop stuff into the 'server' block, but I figure some people might want to reuse the same logic over and over. As long as the blog is in the root of the site, this is no problem. I created a 'global' subdirectory to add extra rules for general purpose use and performing quick WordPress setups (either /etc/nginx/conf/global/ or /etc/nginx/global/ depending on how your nginx install is set up).

=== Global restrictions file ===
<pre>
# Global restrictions configuration file.
# Designed to be included in any server {} block.</p>
location = /favicon.ico {
	log_not_found off;
	access_log off;
}

location = /robots.txt {
	allow all;
	log_not_found off;
	access_log off;
}

# Deny all attempts to access hidden files such as .htaccess, .htpasswd, .DS_Store (Mac).
# Keep logging the requests to parse later (or to pass to firewall utilities such as fail2ban)
location ~ /\. {
	deny all;
}

# Deny access to any files with a .php extension in the uploads directory
# Works in sub-directory installs and also in multisite network
# Keep logging the requests to parse later (or to pass to firewall utilities such as fail2ban)
location ~* /(?:uploads|files)/.*\.php$ {
	deny all;
}

</pre>

=== General WordPress rules ===

For single blog installations, here is the 'global/wordpress.conf' file:

<pre>
# WordPress single blog rules.
# Designed to be included in any server {} block.

# This order might seem weird - this is attempted to match last if rules below fail.
# http://wiki.nginx.org/HttpCoreModule
location / {
	try_files $uri $uri/ /index.php?$args;
}

# Add trailing slash to */wp-admin requests.
rewrite /wp-admin$ $scheme://$host$uri/ permanent;

# Directives to send expires headers and turn off 404 error logging.
location ~* ^.+\.(ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|rss|atom|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|doc|xls|exe|ppt|tar|mid|midi|wav|bmp|rtf)$ {
       access_log off; log_not_found off; expires max;
}

# Uncomment one of the lines below for the appropriate caching plugin (if used).
#include global/wordpress-wp-super-cache.conf;
#include global/wordpress-w3-total-cache.conf;

# Pass all .php files onto a php-fpm/php-fcgi server.
location ~ \.php$ {
	# Zero-day exploit defense.
	# http://forum.nginx.org/read.php?2,88845,page=3
	# Won't work properly (404 error) if the file is not stored on this server, which is entirely possible with php-fpm/php-fcgi.
	# Comment the 'try_files' line out if you set up php-fpm/php-fcgi on another machine.  And then cross your fingers that you won't get hacked.
	try_files $uri =404;

	fastcgi_split_path_info ^(.+\.php)(/.+)$;
	#NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini

	include fastcgi_params;
	fastcgi_index index.php;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
#	fastcgi_intercept_errors on;
	fastcgi_pass php;
}
</pre>


====URL Rewrites / Permalinks====

WordPress includes checks for Apache mod_rewrite before enabling permalinks. For older versions of WordPress, this check would fail on nginx, which can leave 'index.php' in the permalink structure. This was fixed in WordPress 3.7, which now detects nginx servers and enables "pretty" permalinks automatically.

For pre-WordPress 3.7 installs, to force WordPress to enable permalinks completely, add the following to a plugin or use  [http://wordpress.org/extend/plugins/nginx-helper/ Nginx Helper plugin]. Nginx Helper also provides support for [http://codex.wordpress.org/Nginx#Better_Performance_for_Static_Files_in_Multisite Nginx Map]

<pre>
add_filter( 'got_rewrite', '__return_true' );
</pre>

If placed in an MU plugin, like '/wp-content/mu-plugins/nginx.php', this code will not be accidentally disabled. Also, WordPress 3.0 or higher is required to have a filter '__return_true'.

=== WordPress Multisite Subdirectory rules ===
For multisite subdirectory installations, here is the 'global/wordpress.conf' file:

<pre>
# WordPress multisite subdirectory rules.
# Designed to be included in any server {} block.

# This order might seem weird - this is attempted to match last if rules below fail.
# http://wiki.nginx.org/HttpCoreModule
location / {
	try_files $uri $uri/ /index.php?$args;
}

# Directives to send expires headers and turn off 404 error logging.
location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
	expires 24h;
	log_not_found off;
}

location ~ ^/[_0-9a-zA-Z-]+/files/(.*)$ {
        try_files /wp-content/blogs.dir/$blogid/files/$2 /wp-includes/ms-files.php?file=$2 ;
        access_log off; log_not_found off; expires max;
}

#avoid php readfile()
location ^~ /blogs.dir {
        internal;
        alias /var/www/example.com/htdocs/wp-content/blogs.dir ;
        access_log off; log_not_found off;      expires max;
}

# Uncomment one of the lines below for the appropriate caching plugin (if used).
#include global/wordpress-ms-subdir-wp-super-cache.conf;
#include global/wordpress-ms-subdir-w3-total-cache.conf;

# Rewrite multisite '.../wp-.*' and '.../*.php'.
if (!-e $request_filename) {
	rewrite /wp-admin$ $scheme://$host$uri/ permanent;
	rewrite ^/[_0-9a-zA-Z-]+(/wp-.*) $1 last;
	rewrite ^/[_0-9a-zA-Z-]+(/.*\.php)$ $1 last;
}

# Pass all .php files onto a php-fpm/php-fcgi server.
location ~ \.php$ {
	# Zero-day exploit defense.
	# http://forum.nginx.org/read.php?2,88845,page=3
	# Won't work properly (404 error) if the file is not stored on this server, which is entirely possible with php-fpm/php-fcgi.
	# Comment the 'try_files' line out if you set up php-fpm/php-fcgi on another machine.  And then cross your fingers that you won't get hacked.
	try_files $uri =404;

	fastcgi_split_path_info ^(.+\.php)(/.+)$;
	#NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini

	include fastcgi_params;
	fastcgi_index index.php;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
#	fastcgi_intercept_errors on;
	fastcgi_pass php;
}
</pre>

=== WP Super Cache Rules ===

<pre>
# WP Super Cache rules.
# Designed to be included from a 'wordpress-ms-...' configuration file.

set $cache_uri $request_uri;

# POST requests and urls with a query string should always go to PHP
if ($request_method = POST) {
        set $cache_uri 'null cache';
}
   
if ($query_string != "") {
        set $cache_uri 'null cache';
}   

# Don't cache uris containing the following segments
if ($request_uri ~* "(/wp-admin/|/xmlrpc.php|/wp-(app|cron|login|register|mail).php|wp-.*.php|/feed/|index.php|wp-comments-popup.php|wp-links-opml.php|wp-locations.php|sitemap(_index)?.xml|[a-z0-9_-]+-sitemap([0-9]+)?.xml)") {
        set $cache_uri 'null cache';
}   

# Don't use the cache for logged in users or recent commenters
if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_logged_in") {
        set $cache_uri 'null cache';
}

# START MOBILE
# Mobile browsers section to server them non-cached version. COMMENTED by default as most modern wordpress themes including twenty-eleven are responsive. Uncomment config lines in this section if you want to use a plugin like WP-Touch
# if ($http_x_wap_profile) {
#        set $cache_uri 'null cache';
#}

#if ($http_profile) {
#        set $cache_uri 'null cache';
#}

#if ($http_user_agent ~* (2.0\ MMP|240x320|400X240|AvantGo|BlackBerry|Blazer|Cellphone|Danger|DoCoMo|Elaine/3.0|EudoraWeb|Googlebot-Mobile|hiptop|IEMobile|KYOCERA/WX310K|LG/U990|MIDP-2.|MMEF20|MOT-V|NetFront|Newt|Nintendo\ Wii|Nitro|Nokia|Opera\ Mini|Palm|PlayStation\ Portable|portalmmm|Proxinet|ProxiNet|SHARP-TQ-GX10|SHG-i900|Small|SonyEricsson|Symbian\ OS|SymbianOS|TS21i-10|UP.Browser|UP.Link|webOS|Windows\ CE|WinWAP|YahooSeeker/M1A1-R2D2|iPhone|iPod|Android|BlackBerry9530|LG-TU915\ Obigo|LGE\ VX|webOS|Nokia5800)) {
 #       set $cache_uri 'null cache';
#}

#if ($http_user_agent ~* (w3c\ |w3c-|acs-|alav|alca|amoi|audi|avan|benq|bird|blac|blaz|brew|cell|cldc|cmd-|dang|doco|eric|hipt|htc_|inno|ipaq|ipod|jigs|kddi|keji|leno|lg-c|lg-d|lg-g|lge-|lg/u|maui|maxo|midp|mits|mmef|mobi|mot-|moto|mwbp|nec-|newt|noki|palm|pana|pant|phil|play|port|prox|qwap|sage|sams|sany|sch-|sec-|send|seri|sgh-|shar|sie-|siem|smal|smar|sony|sph-|symb|t-mo|teli|tim-|tosh|tsm-|upg1|upsi|vk-v|voda|wap-|wapa|wapi|wapp|wapr|webc|winw|winw|xda\ |xda-)) {
  #      set $cache_uri 'null cache';
#}
#END MOBILE

# Use cached or actual file if they exists, otherwise pass request to WordPress
location / {
        try_files /wp-content/cache/supercache/$http_host/$cache_uri/index.html $uri $uri/ /index.php?$args ;
}    
</pre>

'''Experimental modifications:'''

If you are using HTTPS, the latest development version of WP Super Cache may use a different directory structure to differentiate between HTTP and HTTPS.  The ${scheme} variable will eventually become a necessary part of the path in that case. try_files line may look like below:

<pre>
location / {
        try_files /wp-content/cache/supercache/$http_host/$scheme$cache_uri/index.html $uri $uri/ /index.php?$args ;
}
</pre>

=== W3 Total Cache Rules ===
W3 Total Cache uses different directory structure for disk-based cache storage depending on WordPress configuration. 

Cache validation checks will remain common as shown below:

<pre>
#W3 TOTAL CACHE CHECK 
set $cache_uri $request_uri;

# POST requests and urls with a query string should always go to PHP
if ($request_method = POST) {
        set $cache_uri 'null cache';
}   
if ($query_string != "") {
        set $cache_uri 'null cache';
}   

# Don't cache uris containing the following segments
if ($request_uri ~* "(/wp-admin/|/xmlrpc.php|/wp-(app|cron|login|register|mail).php|wp-.*.php|/feed/|index.php|wp-comments-popup.php|wp-links-opml.php|wp-locations.php|sitemap(_index)?.xml|[a-z0-9_-]+-sitemap([0-9]+)?.xml)") {
        set $cache_uri 'null cache';
}   

# Don't use the cache for logged in users or recent commenters
if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_logged_in") {
        set $cache_uri 'null cache';
}
#ADD mobile rules from WP SUPER CACHE section above

#APPEND A CODE BLOCK FROM BELOW...
</pre>

'''FOR Normal WordPress (without Multisite)'''
Use following:
<pre>
# Use cached or actual file if they exists, otherwise pass request to WordPress
location / {
        try_files /wp-content/w3tc/pgcache/$cache_uri/_index.html $uri $uri/ /index.php?$args ;
}    
</pre>

'''FOR Multisite with subdirectories'''
Use following:
<pre>
if ($request_uri ~* "^/([_0-9a-zA-Z-]+)/.*" ){
        set $blog $1;
}

set $blog "${blog}.";

if ( $blog = "blog." ){
        set $blog "";
}

# Use cached or actual file if they exists, otherwise pass request to WordPress
location / {
        try_files /wp-content/w3tc-$blog$host/pgcache$cache_uri/_index.html $uri $uri/ /index.php?$args ;
}
</pre>

'''FOR Multisite with Subdomains/Domain-mapping'''
Use following:
<pre>
location / {
        try_files /wp-content/w3tc-$host/pgcache/$cache_uri/_index.html $uri $uri/ /index.php?$args;
}
</pre>

'''Notes'''
* Nginx can handle gzip & browser cache automatically so better leave that part to nginx. 
* W3 Total Cache Minify rules will work with above config without any issues.

== Nginx fastcgi_cache ==
Nginx can perform caching on its own end to reduce load on your server. 
When you want to use Nginx's built-in fastcgi_cache, you better compile nginx with [https://github.com/FRiCKLE/ngx_cache_purge fastcgi_cache_purge] module. It will help nginx purge cache for a page when it gets edited. On the WordPress side, you need to install a plugin like [http://wordpress.org/extend/plugins/nginx-helper/ Nginx Helper] to utilize fastcgi_cache_purge feature.

For Ubuntu users, you can use [https://launchpad.net/~brianmercer/+archive/nginx launchpad repo by Brian Mercer] to install/upgrade nginx with fastcgi_cache_purge support.

Config will look like below:

'''Define an Nginx cache zone'''
<pre>
#move next 3 lines to /etc/nginx/nginx.conf if you want to use fastcgi_cache across many sites 
fastcgi_cache_path /var/run/nginx-cache levels=1:2 keys_zone=WORDPRESS:500m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
fastcgi_cache_use_stale error timeout invalid_header http_500;
</pre>

'''For wordpress site config, in server{..} block add a cache check block as follow'''
<pre>
#fastcgi_cache start
set $no_cache 0;

# POST requests and urls with a query string should always go to PHP
if ($request_method = POST) {
        set $no_cache 1;
}   
if ($query_string != "") {
        set $no_cache 1;
}   

# Don't cache uris containing the following segments
if ($request_uri ~* "(/wp-admin/|/xmlrpc.php|/wp-(app|cron|login|register|mail).php|wp-.*.php|/feed/|index.php|wp-comments-popup.php|wp-links-opml.php|wp-locations.php|sitemap(_index)?.xml|[a-z0-9_-]+-sitemap([0-9]+)?.xml)") {
        set $no_cache 1;
}   

# Don't use the cache for logged in users or recent commenters
if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in") {
        set $no_cache 1;
}

#note location{] block is simple now as caching is done on nginx's end
location / {
        try_files $uri $uri/ /index.php?$args;
}    
</pre>

'''Then make changes to PHP handling block'''
<pre>
location ~ .php$ {
         try_files $uri =404; 
         include fastcgi_params;
         fastcgi_pass php;

         fastcgi_cache_bypass $no_cache;
         fastcgi_no_cache $no_cache;

         fastcgi_cache WORDPRESS;
         fastcgi_cache_valid  60m;
 }
</pre>

'''Finally add a location for conditional purge'''
<pre>
location ~ /purge(/.*) {
        fastcgi_cache_purge WORDPRESS "$scheme$request_method$host$1";
} 
</pre>

== Better Performance for Static Files in Multisite ==

By default, on a Multisite setup, a static file request brings php into picture i.e. <code>ms-files.php</code> file. You can get much better performance using Nginx <code>Map{..}</code> directive. 

In nginx config for your site, above <code>server{..}</code> block, add a section as follows:

<pre>
map $http_host $blogid {
    default               0;

    example.com           1;
    site1.example.com     2;
    site1.com             2;
}</pre>


It is just a list of site-names and blog-ids. You can use [http://wordpress.org/extend/plugins/nginx-helper Nginx helper] to get such a list of site-name/blog-id pairs. This plugin will also generate a <code>map.conf</code> file which you can directly include in the map{} section like this:

<pre>
map $http_host $blogid {
    default               0;

    include /path/to/map.conf ;
}</pre>

After creating a <code>map{..}</code> section, you just need to make one more change in your Nginx config so requests for <code>/files/</code> will be first processed using nginx <code>map{..}</code>:

<pre>location ~ ^/files/(.*)$ {
          try_files /wp-content/blogs.dir/$blogid/$uri /wp-includes/ms-files.php?file=$1 ;
          access_log off; log_not_found off; expires max;
 }</pre>

=== Notes ===
* Whenever a new site is created, deleted or an extra domain is mapped to an existing site, Nginx helper will update map.conf file automatically but you will still need to reload Nginx config manually. You can do that anytime later. Till then, only files for new sites will be served using php-fpm.
* This method does not generate any symbolic links. So, there will be no issues with accidental deletes or backup scripts that follow symbolic links.
* For large networks, this will scale-up nicely as there will be a single map.conf file.

== Notes ==

A couple of final but important notes: This whole setup assumes that the root of the site is the blog and that all files that will be referenced reside on the host. If you put the blog in a subdirectory such as /blog, then the rules will have to be modified. Perhaps someone can take these rules and make it possible to, for instance, use a:

 set $wp_subdir "/blog";

directive in the main 'server' block and have it automagically apply to the generic WP rules.


== Warning ==

* A typo in [http://codex.wordpress.org/Nginx#Global_restrictions_file Global restrictions file] can create loopholes. To test if your "uploads" directory is really protected, create a PHP file with some content (example: <?php phpinfo(); ?>), upload it to "uploads" directory (or one of its sub-directories), then try to access (execute) it from your browser.

== Resources ==

=== Reference ===
* [http://wordpress.org/support/topic/nginx-php-fpm-php-apc-wordpress-multisite-subdirectory-wp-super-cache nginx + php-fpm + PHP APC + WordPress multisite (subdirectory) + WP Super Cache] (Thanks [http://wordpress.org/support/profile/bigsite bigsite])
* [http://josephscott.org/archives/2010/06/wordpress-pretty-permalinks-with-nginx/ Notes on removing 'index.php' from Permalinks] (Can be done using [http://wordpress.org/extend/plugins/nginx-helper/ Nginx Helper Plugin])

=== External Links ===
* [http://rtcamp.com/wordpress-nginx/tutorials/ List of 20+ WordPress-Nginx Tutorials for common situations]
* [http://mindsharestrategy.com/2011/installing-a-new-engine-nginx/ Tutorial on transferring WordPress Multisite from Apache to Nginx]
* [http://wiki.nginx.org/Wordpress Nginx WordPress wiki page]
* [http://library.linode.com/lemp-guides/ LEMP guides on Linode's Library]
* [http://library.linode.com/web-servers/nginx/ Various guides about Nginx on Linode's Library]
* [http://www.sitepoint.com/lightning-fast-wordpress-with-php-fpm-and-nginx/ Lightning fast Wordpress with Php-fpm and Nginx]
* [http://wiki.nginx.org/VirtualHostExample Virtual Hosts Examples]
* [http://blog.martinfjordvald.com/2010/07/nginx-primer/ An introduction to Nginx configuration]
* [http://wiki.nginx.org/FullExample Nginx Full Example]
* [http://wiki.nginx.org/FullExample2 Nginx Full Example 2]

=== Scripts & Tools ===
* For wordpress-nginx based site management, [https://github.com/rtCamp/easyengine  EasyEngine] can be used. EasyEngine is collection of shell scripts for Ubuntu.

=== Securing Nginx ===
* [http://kbeezie.com/view/securing-nginx-php/ Securing Nginx and PHP]
* [https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/ Setting up PHP-FastCGI and nginx? Don’t trust the tutorials: check your configuration!]

[[Category:New page created]]