Online Chat
 Call Us: 
1-877-744-1221
Browse Submit a Ticket
 
Advanced Search
Tools
Rss Categories

Installation of URL Rewriting module (IIRF) for IIS6/IIS7

Author: Edward Hardin Reference Number: AA-00461 Views: 78864 Last Updated: 10/21/2011 10:56 AM 0 Rating/ Voters

IIS servers do not support URL rewriting by default, so we would need to use a third party tool.

This guide cover installation of Ionic's ISAPI Rewriting Filter (IIRF) on a IIS server and setup of the rewrite configuration required by KMP. If you would like to find out more about IIRF, you can refer to its documentation.

Note

IIS7 servers support native component for URL rewriting. It is much easier to install. If you're using IIS7, we recommend to follow the Installation of native URL Rewriting module (URL Rewrite) for IIS7 instead of current guide.

Warning

If you're using Helicon ISAPI Rewrite, you do not need to install any other URL rewrite software. KMP works with this module from the box.

If you're already using some other URL Rewrite tool, we strongly recommend to completely uninstall it, because it may interfere with IIRF and it is most likely that URL rewriting will not work correctly, and KMP may be inaccessible even if you follow the instructions in this article carefully.

Installing on IIS5 or IIS6

Follow these steps to install IIRF on IIS5 or IIS6.

 IIS v5.0 is included with Windows 2000. IIS v5.1 is included with Windows XP. IIS v6.0 is included with Windows Server 2003. These are the steps for installing IIRF v2.0 on to any of those operating systems.

  1. First of all, download the IIRF v2.0+ package from the official website and extract it.
  2. Copy the IIRF DLL (IIRF.dll) from the "bin" folder to an appropriate folder on your server, such as c:\windows\system32\inetsrv\IIRF . Or it could be in a totally separate directory tree. It's up to you.
  3. Grant READ permissions on the DLL, and the ini file, to the appropriate principals. To do this, first view the IIRF.dll in Windows Explorer.



    Figure 1:Viewing the IIRF.dll in Explorer

    On Windows XP or Windows 2000, the appropriate Windows principal is, by default, IUSR_<hostname>, although an IIS administrator is free to configure IIS to use an alternative identity. Grant READ permissions to this identity.

    On Windows Server 2003, grant Read permissions to the IIS_WPG group for the DLL and the ini file. According to Microsoft's documentation on IIS6 and Application Pool identities, on a clean installation of IIS 6.0, the IIS worker process (w3wp.exe) runs under the new built-in Network Service account by default. As with IIS 5, an IIS administrator can change this, but typically this is the account used. Also, On a clean installation of IIS 6.0, the IIS_WPG group contains the Network Service, Local Service, LocalSystem, and IWAM_ComputerName accounts. If you change the identity for the Application Pool to be something other than NetworkService, then you'll have to grant that identity the appropriate READ permissions.

    Right click on the IIRF.dll, and select Properties...



    Click the Add button and, if running on Windows Server 2003, specify IIS_WPG as the group. If running on Windows XP, specify the appropriate IUSR_<hostname> principal.



    Click OK, and OK again. Confirm you want to make the changes if necessary.

    Create the iirfGlobal.ini file. In Explorer, in the same folder where you installed IIRF.dll, right click and create a new text file.



    Specify the name as "iirfGlobal.ini" (without quotes). Confirm the change of the file extension. Finally, set the permissions on the INI file in the same way you've set permissions on the DLL.

     You do not need to put anything to it, you just need an empty file.

    Verify that the permissions are set properly. Browse to the IIRF.dll in Windows Explorer. Right click on the file. Select Properties...Security tab, then click the button labeled "Advanced". You should see something like this:



    Click on the Effective Permissions tab, click the Select button, and on Windows Server 2003, specify NETWORK SERVICE for the identity. On Windows XP or 2000, specify IUSR_<hostname>. Click OK and you should see something like this:



    Notice that the checkbox next to List folder / read data is checked. This shows that the appropriate permissions are available to the NetworkService identity on the Iirf.ini file. If you don't get this checkbox, then you'll need to go back and edit the permissions so that the identity used by w3wp.exe can read the Iirf.ini file.

    Browse to the iirfGlobal.ini file, and verify permissions in the same way.

    Note

    Incorrectly set permissions on the DLL or INI file is the #1 problem in IIRF installations, so please do take the time to get this right. If the IIS process cannot read the DLL or ini file because of security restrictions, the filter will not work.

  4. Now, add the DLL as an ISAPI Filter. To do so, open the Internet Information Services Manager. In Windows XP, You can do this via Start... Run... %systemRoot%\System32\inetsrv\iis.msc . Or, browse to Start...Control Panel...Administrative Tools, and select IIS Manager.



     On Windows Server 2003, Start > Administrative Tools > Internet Information Services (IIS) Manager.



  5. Choose the appropriate level for the ISAPI filter:
    • to use the ISAPI filter with all Web sites, select the "Web Sites" icon just under the machine name.
    • to use the ISAPI filter with a specific Web site, select the icon for that Web site (for example, the default Web site). This is recommended if you're going to use IIRF with KMP only - you just enable it for the website where KMP is installed.
      Do not install it twice!

      Do not enable the ISAPI filter on the "Web Sites" level AND on the website with KMP at the same time! In this case URLs will be rewritten twice and KMP will not work properly.

  6. Right-click the level (icon) that you selected. Click the Properties button.


  7. Click the ISAPI Filters tab.


  8. Click Add. Type a name for the ISAPI filter. Eg, "Ionic Rewriter". Click Browse and select the ISAPI filter DLL that you copied in step 1. Click OK.



    If you have multiple ISAPI filters running, you may want to modify the filter load order. For example, if you have Ruby-on-Rails installed on IIS, it typically uses an ISAPI filter. You may need to specify that IIRF should load first, prior to Rails. What this means is that IIRF gets the first chance to rewrite the URL, before Rails sees the URL.

    Information Box Title

    The relative load order of ISAPI filters is observed only for those filters that have the same priority.

  9.   Finally, save configuration and restart IIS. To do this, right click on the Server node in IIS Manager, and select All Tasks.Then Save Configuration to Disk



    Then right click on the Server node in IIS Manager again, and select All Tasks.Then Restart IIS


  10. IIRF is now installed. You must now proceed to configuring IIRF

Installing on IIS7

IIS v7 is included with Windows Server 2008, Windows         Vista, and Windows 7. These are the steps required to install IIRF on either of         those operating systems.

To configure IIRF on IIS7, follow these steps:

  1. First of all, download the IIRF v2.0+ package from the official website and extract it.
  2. Copy the IIRF DLL (iirf.dll) from the "bin" folder to an appropriate folder on your server, such as c:\windows\system32\inetsrv\IIRF . Or it could be in a totally separate directory tree. It's up to you.
  3. Create the iirgGlobal.ini file. In Explorer, in the same folder where you installed IIRF.dll, right click and create a new text file. You do not need to put anything to it, you just need an empty file.
  4. Be sure to allow the appropriate user or security group read + execute access to the DLL and the ini file. On IIS7, it should be sufficient to grant READ permissions to NetworkService or IIS_WPG.

    To verify that the permissions are set properly on each file, browse to the file in Windows Explorer. Right click on the file. Select Properties...Security tab, then click the button labeled "Advanced". You should see something like this:



    Click on the Effective Permissions tab, click the Select button, and specify NETWORK SERVICE for the identity. Click OK and you should see something like this:



    Notice that the checkbox next to List folder / read data is checked. This shows that the appropriate permissions are available to the NetworkService identity on the Iirf.ini or Iirf.dll file. If you don't get this checkbox, then you'll need to go back and edit the permissions so that the identity used by w3wp.exe can read the iirf.ini or iirf.dll file. Repeat these steps for both IIrf.dll and Iirf.ini.

    Note

    Incorrectly set permissions on the DLL or INI file is the #1 problem in IIRF installations, so please do take the time to get this right. If the IIS process cannot read the DLL or ini file because of security restrictions, the filter will not work.


  5. Open the IIS Manager. Simply use Start... Run... %systemRoot%\System32\inetsrv\iis.msc
  6. If you would like to configure IIRF to be a "global filter" (applies to all websites and virtual directories), then, select the machine or server name on the left-hand side tree. This should be the top-most (root) node in the tree.



    If you would like to configure IIRF for an individual web site, expand the server node, and select the appropriate web site on the left-hand side tree. tree.




  7. In either case, in the center-right panel of the MMC window you should now see a set of icons. One of them is labeled "ISAPI Filters". Double click it. Your window should look similar to the following:



  8. On the far right hand side in the "Actions" pane for the MMC window, click the top-most item, which reads "Add...".
  9. You get a simple dialog with a box for filter name and a box for the path to the Filter DLL. Type in "IIRF" or "Ionic Rewrite" for the filter name (the particular name is not important), and the full path for the DLL, eg, c:\windows\system32\inetsrv\IIRF\IIRF.dll .



    Click OK.
  10. IIRF is now installed. You must now proceed to configuring IIRF

     

For 64-bit systems

If your OS is 64-bit, you must select "Enable 32-Bit Application" in the Advanced Settings on the App Pool, in order to let IIRF run. 



Setting Up Rewriting Configuration for Knowledgebase Manager Pro

Now we need to create a file that contains all rewriting rules for KMP.

  1. Open the web root folder for the website with KMP (e.g. C:\Inetpub\wwwroot).
  2. Create "iirf.ini" file in this folder with following contents:

    RewriteEngine ON
    StatusUrl /iirfStatus
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/PATH-TO-KMP/hosts/hosted(.*)$ /PATH-TO-KMP/hosts/hosted/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/PATH-TO-KMP/hosts/preview(.*)$ /PATH-TO-KMP/hosts/preview/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/PATH-TO-KMP/admin(.*)$ /PATH-TO-KMP/admin/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/PATH-TO-KMP/(.*)$ /PATH-TO-KMP/index.php?/$1 [L]
  3. Replace  "PATH-TO-KMP" with correct path to Knowledgebase Manager Pro files starting from the web root folder. For example, if you uploaded KMP to the C:\Inetpub\wwwroot\KB directory, you need to replace "PATH-TO-KMP" with "KB" like this:

    # This is an example, it may not work for you if you have different path to KMP
    RewriteEngine ON
    StatusUrl /iirfStatus
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/kb/hosts/hosted(.*)$ /kb/hosts/hosted/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/kb/hosts/preview(.*)$ /kb/hosts/preview/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/kb/admin(.*)$ /kb/admin/index.php?/$1 [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^/kb/(.*)$ /kb/index.php?/$1 [L]
    Note

    Please note that you need to replace 8 occurrences! Do not forget the trailing slash: "/kb/index.php?/$1", NOT "kb/index.php?/$1"

  4. That's all! You can check if you have installed everything correctly by opening this URL in your browser: http://localhost/iirfStatus (it works only if you open it on the same machine where IIS with IIRF runs). You'll get something like this:



  5. Go to Styling and Front-end Settings to switch URL Rewriting ON and save the new settings.

  6. Open a KMP front-end page in your browser to check if URL Rewrite works correctly now.
  7. If you still got the 404, please contact our support for help.

Troubleshooting

You can find documentation for IIRF here. There are installation troubleshooting instructions under the Installing IIRF > Verifying and Troubleshooting Installation.