Manage a Large Number of Redirects with NGINX maps

NGINX logo

Handling redirects for web sites in NGINX (or Apache for that matter) is always a pain. Because when you upgrade your site, every search engine in the world continues to serve and scan the old pages. Those search engine bots will continue to test old pages and the algorithm will continue to list them in SERPs (Search Engine Results Pages).

If you are using NGINX on Ubuntu (I have only tested this on 14.04 and 16.04 ubuntu server) then you have probably noticed the new folder at /etc/nginx/snippets/. We can leverage this by making a subfolder and using those includes in our /etc/nginx/sites-available/<site-name> files.

	sudo su
	mkdir -p /etc/nginx/snippets/includes/
	cd /etc/nginx/snippets/includes
	touch nc-301-redirects-global.map

	# and you probably have other common things to include like ciphers so we add
	touch sa-ciphers.conf
	touch sa-custom.conf
	touch sa-redirects-global.conf
	touch sa-all-includes.conf

Why the naming? Well the NGINX redirect MAP module requires that the map NOT live in the server block in sites-available (sym linked to sites-enabled). The "map" must live in /etc/nginx/nginx.conf. So you could put your redirects map in /etc/nginx/conf.d/ but I've been burned by that too many times with upgrades so I avoid it. The naming I used for the nginx redirects tells me where they should go allowing me to grep files and check for errors.

"nc" is an abbreviation meaning the include will be in the file /etc/nginx/nginx.conf
"sa" is an abbreviation meaning the include will be processed in /etc/nginx/sites-available/sitename

First we need to populate our "nc-301-redirects-global.map" file which looks something like this:

map $request_uri $new_uri { default ""; /rss/feed/ /rss/; /2011/01/my-article/ /my-article/; /staff/ /team/; }

Then inside of your /etc/nginx/nginx.conf file you include it:

include /etc/nginx/snippets/includes/nc-301-redirects-global.map;

The next issue is if the map is included in the global http block, how are we going to process it inside of the files at /etc/nginx/sites-available/. And hopefully also be flexible with other global specifications like "prefer ciphers on"? For that you can include includes in an include. (makes my head hurt, but it works). Next we need to edit our file "sa-all-includes.conf" file.

nano /etc/nginx/snippets/includes/sa-all-includes.conf # paste the following three lines in. They are blank currently. touch sa-ciphers.conf touch sa-custom.conf touch sa-redirects-global.conf

then inside of the sites-available virtual server include the top would look something like this:

server {
    listen 443 ssl;
    server_name www.example.org;
    access_log /var/log/nginx/example-org-access.log;
    error_log /var/log/nginx/example-org-error.log;
    # use letsencrypt and support the eff.org as well!
    ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.org/privkey.pem;

    include /etc/nginx/snippets/includes/sa-all-includes.conf;

    location / {
    ....

The important line is the include /etc/nginx/snippets/includes/sa-all-includes.conf;

At this point you should still be able to run "nginx -t" because the included files are all empty. Test it.

Now we put this code block in the file /etc/nginx/snippets/includes/sa-redirects-global.conf

 # process the map file
 if ($new_uri != "") {
    rewrite ^(.*)$ $new_uri permanent;
 }

 # stop badly configured DNS settings from flooding the logs
 location ~* ^/autodiscover
 {
   return 301 $scheme://outlook.office365.com$request_uri;
 }

That second part is just because Microsoft's autodiscover is rarely configured properly on client's local networks.