Copyright: ZmeY ISAPI URL Remapper


ZmeY ISAPI URL Mapper Filter

Package contents

This package contains following files:

File name:	Description:
URLMapper.dll	ISAPI filter for Microsoft Information Server 4.0 or later. Maps requests to some URLs to specified physical locations.
URLMapperConfig.exe	CGI application for ISAPI filter administration. This tool must be placed in some IIS virtual directory/site and must be accessible only for the server administrators. Configure your server to ask for authentication while accessing this file.
Readme.doc	This document.
Purpose and description of the filter

The main purpose of the filter is to give an alternative way of creating virtual hosts under IIS. The filter can also work under Personal Web Server, giving the ability to have more than one site. It identifies the different sites by their hostnames and maps all requests, connected with the given site, to a physical location on the server. There are two schemes of mapping (see below for detailed description of each scheme). Additionally exceptions of the common way of mapping can be defined. These exceptions apply when specific subdirectories are found in the requested URL. Exceptions can be defined globally for all sites on a given IP as well as for a particular site.

Note: As the mapping exceptions can be global i.e. common for all sites on an IP and personal for a specified site only we will name the global mapping exceptions ‘Common mapping paths’ and the personal mapping exceptions – ‘Folder exceptions’.

To make things clear let’s take one simple example. Assume you are an ISP and you host customer sites on your server. You have a /cgi-bin and a /img directories that you want to be accessible for every customer because they should use some common scripts and images. Of course every customer should have personal web root directory where to store his files. Additionally some customers have more privileges and use /cgi-bin and /img directories with different contents than the other users. And, in the end, all users should see the shared directories in a same way.

If you use this filter you can manage this situation like this: Create a virtual host for every user, assign him directory and mapping scheme. Define common mapping paths for the two shared directories /cgi-bin and /img and direct them there, where are the files for normal users. Only for the users with higher privileges you can define folder exceptions for these two directories and direct them a different location or locations.

Mapping schemes

There are two mapping schemes. In the configuration CGI program they are referred as Scheme A and Scheme B. The following two pictures represent the directory structure needed for every scheme.

Scheme A	Scheme B
When configuring one virtual host you give only the name of Userdir. Its location is by default under Webroot, which can be specified separately and if it is not given by default that is the root directory of the site under IIS for which the filter is activated. So if you have sites with different structure, you should use Scheme A. In that case every site has its own directory tree under Userdir. If some of your sites use common directory structure, you can use Scheme B. In that case the common directory structure is under Webroot and user directories are subsequent to every directory. The name of the user site root directory must be specially configured with the CGI configuration program so the filter knows it.

Installation

Filter and administrative tool installation is simple – ISAPI filter must be copied somewhere and registered as a filter in IIS. Use Microsoft Management Console and open Internet Information Server snap-in for your machine. Click properties, then choose WWW service and go to tab ISAPI Filters. Click Add button and browse for URLMapper.dll or directly type the path to it. Filter name field is not meaningful - type there pretty name of your choice. After all you will need to restart your Internet Information Server (the easy way is to restart your machine but you can also stop iisadmin service and then start it again with all dependant services – w3svc, msftpsvc, nntpsvc, smtpsvc (start only the needed services – that were stopped with iisadmin).

Step by step installation process

•	copy URLMapper.dll and URLMapperConfig.exe to their permanent locations. URLMapper.dll can be at any location but take in mind that IIS must have access to it. URLMapperConfig.exe is a CGI application so put it in a directory accessible from the WEB and from Microsoft Management Console give execute access to that directory.

•	Register the filter in IIS. You can mount it either on the whole server or on some sites only. If you register it on a site you must stop and run the site again to load the filter. If you install in on the whole server (it will apply to all sites) you must restart the IIS service.

•	With your browser go to the location where you placed URLMapperConfig.exe and start it. By default it starts the first menu item ‘Registry Configuration’ and if you start it for the first time all other options are inaccessible. On that screen you should type in the location where the filter configuration file will be placed. Bare in mind that both the filter (i.e. IIS as a service) and URLMapperConfig.exe must have read/write access to that directory and it should not be accessible from the WEB.  On the same screen you should type your serial number.

Initial configuration

Filter was installed but now you must configure filter options like configuration file and serial number. To do this you must use the CGI application URLMapperConfig.exe. Place it somewhere in a shared virtual directory of a WEB site - you can create such directory or choose to copy this application somewhere in your administrative WEB site. Administrative application works without any pre-configuration - after copying it to a desired location, open your browser and go to the URL that points to it. For example:

www.admin.mycompany.com/tools/URLMapperConfig.exe.

This virtual directory must have execute access, not only script access (change this setting if needed) and site must require authentication - you will be unable to set serial number and configuration file unless you are authenticated as administrator. First time you refer to the administrative tool it may generate an error that means that there is no configuration file and will ask you to enter path to it. You can set configuration file location and serial number from the first link Registry Configuration in the URLMapperConfig.exe menu. Type in the full path and file name to the configuration file (the directory must exist and must NOT be exposed to the WEB!). The configuration tool will create an empty file the first time.

Registration

Place your registration number (if it is wrong - filter will not work, but administrative tool ignores serial numbers). To do so in the URLMapperConfig.exe menu choose Registry Configuration (You must be authenticated as user with administrative privileges !). If you enter invalid registration code you won’t receive any warning but the filter will not work.

Usage

IP registration

The first thing you should do before configuring any virtual hosts is to add one or more IPs on which your sites will respond. You can do this from Add real site IP menu. All other menu options (except Registry Configuration and List IPs) require to select one IP from a list of registered IPs.

You can view the registered IPs from List IPs menu and remove them with the button Remove. Note that you cannot remove an IP while there are virtual hosts bound to it. First you must remove all virtual hosts from that IP.

General options

With this menu you can configure the general options for the selected IP. Every IP has its own separate options. If you check the Disable filter box, the filter won’t make any mappings for requests on that IP.

You can type the location and name of a log file in the Log file field. When the field is empty filter doesn’t make any logging. Note: It is recommended to turn logging on only when there is a special need because filter frequently writes in the log file and that slows down the operation and the log can become too big.

Also here you give the name of the subdirectory that is used as root directory for sites that use Scheme B. (The ‘siteroot’ directory in the picture for Scheme B upwards)

In the field Base web root directory you can type the full location of the directory where your shared to the WEB files and folders are present. (That is the Webroot directory on the pictures illustrating the two mapping schemes.) If that field is left empty the filter takes Home directory location in IIS of the site where the filter is installed for Webroot.

Common mappings

Here you specify the general mapping exceptions. They apply to all sites on a given IP. Here is an example of exceptions operation:

Suppose you have configured virtual host www.user.yourcompany.dom. The site uses Scheme A and the user directory name is TheUserDir. Your web server uses C:\Inetpub\wwwroot for root directory. So the filter will map request www.user.yourcompany.dom/sub/file.htm to C:\Inetpub\wwwroot\TheUserDir\sub\file.htm. But if you define a common mapping path for subdirectory cgi-bin to E:\common\cgi-bin request www.user.yourcompany.dom/cgi-bin/file.htm will be mapped to E:\common\cgi-bin\file.htm regardless to that from which site it comes.

You can define separate common mappings for the two schemes.

Creating virtual host

You can create new virtual host from New mapping menu. First you must select the IP from the list on which the host is, on the next screen you give the full name of the host (For example: www.user.yourcompany.dom). On the next screen you give the user directory name and the mapping scheme.

Hosts management

You can view, edit settings and remove virtual hosts form List mappings menu. First you select the IP and next you see a list of all registered hosts on it. You can manage them with the two buttons – Edit and Remove.

Folder exceptions

The operation of folder exceptions is similar to common mappings but they apply only for the specified site. (See the description for Common mappings and Purpose and description of the filter in the beginning of document) You select IP, then you see a list of hosts on it. Choose that one you want set exceptions to.

Demo version restrictions

The demo version of the filter does not need a serial number. Its functionality is the same but the filter handles only the first 200 request and after that stops mapping. You should restart the web server to activate it again. Note that 200 requests to the filter doesn’t mean 200 visits on the site is maps to, because the links and pictures on pages also generate requests to URLMapper.

Additional notes

•	All exceptions are defined for the first subdirectory after the host name. That means that even if you define exception for /cgi-bin subdirectory, on request www.user.yourcompany.dom/subdir/cgi-bin/file.htm it won’t take place.

•	When you add new virtual hosts they must be separately registered on a DNS server to the same IP to which you are binding them in the filter.

•	If you encounter any problems activating the filter e.g. after typing the registration code try restarting the IIS service.

If you have any questions and suggestions please mail us: support@zmey.com

Copyright © 1999,2000 ZmeY soft