The Pubcookie ISAPI Filter for Microsoft IIS is configured by properties set in the Windows registry. Pubcookie's registry settings are divided into two categories: web properties and filter variables. Web properties are used to configure webs, applications, folders, and files. Filter variables configure the filter itself.

Included on this page:

• PubcookieFilter Registry Key
• Use Example
• Web Properties - settings for individual webs, applications, folders, and files
• Filter Variables - settings for the Pubcookie filter itself
• Reset the Pubcookie Filter - for re-reading the registry

PubcookeFilter Registry Key

All of Pubookie's registry settings are found under the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PubcookieFilter

Use Example

When used to change the Windows registry this example.reg.txt file sets four filter variables and four web properties specific to one application, called WebApp. Notice that the AuthTypeName1 setting defines the string used by the AuthType setting.

Web Properties

In Pubcookie terms, a web property is used to configure any web, subfolder, or file. Think of them as per-application or per-resource settings. They take effect immediately upon entry into the registry without the need to reset the Pubcookie filter.

To assign a web property to a resource, set the corresponding PubcookieFilter registry key. For example:

HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter\<APPID>\<SUBDIR>\...\<FILE>

The APPID is required, but the subdirectory and filename are optional. The subdirectory structure should mirror that of the virtual directory structure of the filtered web.

A special key, HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter\Default, will override the default web property values shown in the table above. This means that "Default" is a reserved word; it cannot be used as an application name.

All web properties are inherited from higher-level subdirectories and overridden by lower-level subdirectories and file entries. For example, if AuthType is set to UWNetID in the application MYAPP, set to SecurID in MYAPP\SubDir, and set to None in MYAPP\SubDir\myfile.html, then MYAPP\SubDir\myfile.html will have the AuthType of None, but another unspecified file in MYAPP\SubDir will have the AuthType of SecurID.

To support legacy webs (i.e. Pubcookie filter 2.6 and below), the special subdirecotry names "UWNETID", "None", and "SecurID" will set the AuthType property to "UWNetID", "None", and "SecurID", respectively. These three strings can be redefined using filter variables (see below). Support for legacy webs can be turned off by setting the filter variable LegacyDirNames to 0.

Filter Variables

In Pubookie terms, a filter variable is used to control the default behavior of the Pubcookie ISAPI Filter itself. These settings are defined in the registry under the following key:

HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter

They all require a filter reset to be re-read. (They can also be defined at compile time in pbc_config.h.)

Pubcookie 3.0 Filter Reset

With Pubcookie 3.0, you can force the Pubcookie filter to re-read the Windows registry for new filter variables by doing an iisreset or by opening a special Pubcookie reset URL on your application server. For example:

http://appserver.example.edu/pubcookiefilter_reset

Note: Just stopping and starting the Web won't bounce the PubcookieFilter DLL.

Note: Pubcookie 3.1 doesn't require this step. It will read new settings on every request.