Issues Running WordPress on IIS7

In my previous post, Why I Chose WordPress for My Site, I covered why I am using WordPress. WordPress typically runs on Apache, but since my host is a .NET hosting company, I am on IIS7. Overall this was not a problem, but I ran into one gotcha with custom permalinks. If you are running WordPress on IIS7, I hope this helps you out.

The problem? The custom “pretty” permalink setting I wanted to use did not work. To understand how I made it work for IIS, first let’s answer:

What are permalinks?

Permalinks are unique URLs which allow WordPress to pull up and display content like blog entries and pages. WordPress stores this content in a database, and refers to each item by a unique ID. When a blog posting needs to be displayed as a web page, a PHP page gets the request, pulls the right content from the DB, merges it into the correct page template, and sends the result back to the client. The template provides the look and feel, and layout, and the content fills in the page.

These URLs with pages and content references are called permalinks because they are permanent links. The link to a particular piece of content will not change as other content is added or deleted from the site.

Looking at the available permalink settings in WordPress

So the URL needs to reference a page, and the content it should display. If you look at the four common permalink settings below, you will see the middle three include the page reference ‘index.php’. Everything that follows is the content reference. The first option, ‘Default’ doesn’t explicitly refer to index.php or any page. However, IIS’s default document setting includes index.php, so this option also uses index.php.

Unfortunately the first four methods are all ugly in different ways. The most commonly used custom setting is shown in ‘Custom Structure’. It is the same as ‘Day and name’, but leaves out index.php.

Thus this permalink:

Becomes cleaner:

The problem and fix for IIS

The problem with the custom permalink setting is that pages fail to load. The default home page loads (IIS has index.php configured as a default page), but all other custom pages, and blog posts, do not open. The problem is that the custom permalink structure does not reference a page. On Apache servers, redirecting these requests is handled with mod_rewrite. On IIS it can be achieved using the Mod Rewrite Module (which is available on my hosted server). Configuring IIS to redirect all requests to index.php allows the custom permalink setting to work.

The WordPress help page (referenced below) provides the solution. It specifies to add the following to the web.config file in the WordPress folder:



<rule name=”Main Rule” stopProcessing=”true”>

<match url=”.*” />

<conditions logicalGrouping=”MatchAll”>

<add input=”{REQUEST_FILENAME}” matchType=”IsFile” negate=”true” />

<add input=”{REQUEST_FILENAME}” matchType=”IsDirectory” negate=”true” />


<action type=”Rewrite” url=”index.php/{R:0}” />




Once added the custom permalink works as expected!