1. If you are new to WebHub, make sure you have the Quick Start Guide handy. This guide is available from Customer Service and provided automatically to anyone evaluating WebHub.
2. Alert! When starting ZMAdmin, use the shortcut provided under Start > Programs > HREFTools > WebHub > ZMAdmin because this passes command line parameters to make the entire WebHub configuration easily readable, with hints, etc. There is a BAT file for this in webhub\bin in case you want to make additional shortcuts.
3. If you are on 64-bit hardware, be sure to install the 64-bit runner, which is available with WebHub v2.108+. Run the normal WebHub Runtime Setup installer. On the page where you can select options, scroll down and you turn on the checkbox for the 64-bit isapi runner. Tips:
   • Choose every single PATH very carefully. Avoid junction points. Consider permission issues. The runner will need to be able to read all the files under ZaphodsMap, plus the WebHub XML files such as WHCentralInfo.xml. Avoid spaces in folder names whenever possible.
   • When placing the runner, do NOT use the folder under the web site root ( example: do NOT use c:\inetpub\wwwroot\scripts ). Use any other folder (example: using c:\inetpub\scripts or d:\Apps\HREFTools\WebHub\bin\whrunner\. In a moment, you will need to make a virtual path to the folder containing the runner, which is easy as long as the folder is NOT nested under the web site's root.
4. Ideally, make sure that http://localhost/ works. If it does not, see the notes below for getting IIS7 going on a new version of Windows 7 or Windows Server 2008. Having localhost available makes testing easier because ?version and ?echo report more information on localhost than for any other domain. If you are new to IIS7, put a small TXT file such as hello.txt into the folder with the WebHub runner, and make sure that you can retrieve that file before getting involved with the ISAPI settings.
5. Using Control Panel > Programs and Features > Turn Windows Features On or Off, install ISAPI extension/filter support. This is not installed by default when you install Internet Information Services. It is under Internet Information Services > World Wide Web Services > Application Development Features > ISAPI Extensions. see screenshot here
6. After enabling ISAPI extensions, exit and re-open IIS Manager to enable the ISAPI features. If you do not restart it, IIS Manager will not list enough Features for you to complete all the following steps.
7. Create a Virtual Directory which points to the location of your runner (e.g. runisa64.dll). To do this, right-click on the site in the Connections pane, and select Add Virtual Directory. From there, give the directory an alias (e.g. "scripts" or "whrunner") and then point to the physical path where runisa64.dll resides. See also: technet docs Alternatively, you can create a so-called Application instead of a Virtual Directory, and that tells IIS7 to give you a separate application pool, which has some benefits.
8. To set execute permissions on the scripts virtual directory, select the virtual directory in IIS7 and double click Handler Mappings. Then click Edit feature permissions, uncheck Read and check Execute. You should map calls to *.DLL (within your virtual directory) to the runner DLL file. After doing that, a popup dialog should ask you whether you want to ENABLE isapi access; answer YES.
9. Navigate to the level you want to configure (i.e. the TOP level to allow the runner for all web sites), go into Features View and select ISAPI and CGI Restrictions. If it is not already there, add a so-called Restriction for the path to runisa64.dll and make sure to check the box [x] Allow extension path to execute. Note that Microsoft prompts for "path" yet they want a complete filespec including path and filename.
10. Test in the browser. First try http://localhost/scripts/runisa64.dll?version and then ?echo and then ?hubvers:pgversion and then your application.

Troubleshooting: if the web browser wants to SAVE the runner instead of displaying a version response

Make sure you have followed all of the above steps completely. If you have, go into Services and RESTART the World Wide Web Publishing service. This compensates for IIS7's tendency to ignore its own configuration changes. Downtime should be a few seconds.

Troubleshooting: if ?version reports the Runner ID as Unknown

There are at least four possible causes for an Unknown runner identifier.

• You might not have rebooted. Some versions of Windows (WinXP, WIn2008 R2) will NOT make the ZaphodsMap environment variable available to IIS and other applications until you reboot. This is indicated when ?version reports a blank string for the ZaphodsMap root.
• You might have moved the runner after running the Setup installer. Solution: copy the filespec as reported by the ?version page to the clipboard. Run ZMAdmin. Look under Runners and adjust the filespec so that it is correct.
• The ZaphodsMap environment variable might be invalid in that (a) it might point to a junction point, which is not the same for an isapi dll as it is for a running application like ZMAdmin; or (b) it might be a variable that works for the current user but is not global. Problem (a) is common when clicking through the Setup process very quickly. Problem (b) is rare; it can happens when one does not use the Runtime Setup to get things started. Either way, the cure is to go into Control Panel, System, Advanced, Environment Variables, and correct the setting. Be sure to end the path with a trailing path delimiter. Save changes, then reboot the computer.
• The runner might be unable to read the ZaphodsMap configuration files. This is very common. The solution is to add at least LIST permissions to the parent folders above the ZaphodsMap root, and READ permissions on the ZaphodsMap folders themselves.
• The runner might be unable to read the WebHub configuration files. Search for whcentralinfo.xml and make sure that there are enough permissions on its folder. The runner needs READ permission. If all attempts to do this fail, you can make your Application Pool run under a specific user, and then grant that specific user permission.

Troubleshooting: if ?echo reports that upload folder can not be accessed

Add Modify permission to the upload folder, for the user IUSR and IIS_USERS (and do this even if you have set your Application Pool to use a specific identify and that identity already has those permissions).

You will need to recycle the Application Pool before the runner will use the new permissions.

Enabling IIS 7

The place to install/enable IIS 7 is under Control Panel > Programs and Features > Turn Windows features on or off. Review all the choices under the Internet Information Services node. The following is a starting point, trying to give you reasonable suggestions for a WebHub development machine. If you have reasons to activate more features, please feel free to use your judgement.

■  Internet Information Services
  □ FTP Server  // recommend using FileZilla ftp server instead
  ■  Web Management Tools
    ■  IIS 6 Management Compatibility
      □ IIS 6 Management Console
      □ IIS 6 Scripting Tools
      □ IIS 6 WMI Compatibility
      ☑ IIS Metabase and IIS 6 configuration compatibility   // if using IIS Backup
    ☑ IIS Management console
    □ IIS Management Scripts and Tools
    □ IIS Management Service
  ■  World Wide Web Services
    ■  Application Development Features
      □ .NET Extensibility
      □ ASP
      □ ASP.NET
      □ CGI
      ☑ ISAPI Extensions
      ☑ ISAPI Filters  // if using StreamCatcher
      □ Server-Size Includes
    ■  Common Http Features
      ☑ Default Document
      ☑ Directory Browsing
      ☑ HTTP Errors
      □ HTTP Redirection
      ☑ Static Content
      □ WebDAV Publishing
    ■  Health and Diagnostics
      □ Custom Logging
      ☑ HTTP Logging
      □ Logging Tools
      ☑ Request Monitor
      □ Tracing
    ■  Performance Features
      □ Dynamic Content Compression  // consider this - can be helpful
      ☑ Static Content Compression
  ■  Security
      □ Basic Authentication
      □ IP Security
      ☑ Request Filtering
      □ URL Authorization

Permissions

LIST permission is needed by the runner and the Hub service for all parent folders above all configuration files, i.e. parent folders of ZaphodsMap root.

READ permission is needed by the runner and the Hub service for all XML files, i.e. everything under ZaphodsMap\HREFTools\WebHub\cv004 plus the folder containing WHCentralInfo.xml.

MODIFY permission is needed by the runner for: its errorlog folder, its temporary folder, the WebHub\CoverPageInfo folder, the WebHub\upload folder.

32-bit StreamCatcher ISAPI Filter on 64-bit Hardware

If you need to use 32-bit StreamCatcher or any other 32-bit ISAPI extension or filter, you will need to set the AppPool to 32-bit in order to avoid Server 500 errors.

To do this, select the AppPool and go into Advanced Properties. There you can Enable 32-bit Applications.

If 403 status messages do not show your custom cover page message

Example error text: 403 - Forbidden: Access is denied.
You do not have permission to view this directory or page using the credentials that you supplied.

This problem has been seen with IIS 7.5 on Windows 7. The symptom is that the WebHub system messages, including cover pages for intentional maintenance, are not used. If you check the HTTP headers with something like Firefox Live Headers, you will find that the 403 response is generated by the WebHub runner but the lovely message is not provided for the surfer. This can be fixed within IIS 7 manager.

Select the web site. Go into Error Pages. Select error 403. Click Edit Feature Settings.... Change the radio button from the 3rd option to the 2nd option, namely detailed errors. Click [Ok]. Now your full message will appear.

See also: Configuring ISAPI and CGI Restrictions in IIS 7 (on Microsoft TechNet)