Registering Filters in Enterprise Edition

In ISA Server Enterprise Edition, enterprise and array configuration settings are stored centrally on Configuration Storage servers. Each ISA Server computer in an enterprise obtains the enterprise configuration settings and the array configuration settings for its array from a Configuration Storage server and maintains a locally stored effective configuration that is derived from the enterprise configuration and the array configuration. Application filters can be registered in the application filters collections in the enterprise configuration and in array configurations.

In addition, ISA Server Management can be extended for an application filter by adding property pages for configuring the application filter on the enterprise and array levels.

An application filter can work on a ISA Server computer only if all of the following conditions are met:

Registering the application filter in the array configuration is required for enforcing its policy in the array. Registering an application filter in the enterprise configuration is optional, but provides several benefits. When you register an application filter in the enterprise configuration, you can do the following:

The Setup code may offer the following registration options:

Registering and Unregistering the Application Filter in the Enterprise Configuration

The process of registering and unregistering an application filter as an object in the enterprise configuration stored on a Configuration Storage server includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified Configuration Storage server with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator. This step can be skipped when Setup is run on a Configuration Storage server.
  3. Using the FPC.Enterprise property to get a reference to the FPCEnterprise object.
  4. Using the FPCEnterprise.Extensions property to get a reference to the FPCExtensions object for the enterprise configuration.
  5. Using the FPCExtensions.ApplicationFilters property to get a reference to the FPCApplicationFilters collection.
  6. Calling the FPCApplicationFilters.Add method with the application filter's GUID and name, or calling FPCApplicationFilters.Remove to unregister the application filter in the enterprise configuration and skipping the next step.
  7. Setting the vendor parameters sets and additional properties of the application filter.
  8. Calling the Save method on the FPCApplicationFilters collection to write the changes in the stored enterprise configuration.
  9. Defining protocols in the enterprise configuration (optional).
  10. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the Configuration Storage server. This step can be skipped when Setup is run on a Configuration Storage server.

If an enterprise administrator wants to register an application filter in the enterprise configuration from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the Configuration Storage server before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Registering and Unregistering the Application Filter in an Array

In ISA Server Enterprise Edition, an enterprise administrator can create an empty array and add an application filter to the array configuration before adding any ISA Server computers to the array. This code is applicable to registering and unregistering the application filter in an empty array or in an array that has array members.

Administrators should run this code only once to register the application filter in an array. It can be run on a remote management computer, a Configuration Storage server, or an array member. If this code is run on an array member, it also registers and unregisters the application filter as an installed application filter on the array member.

The process of registering and unregistering an application filter in an array includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified Configuration Storage server with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator. This step can be skipped when Setup is run on a Configuration Storage server.
  3. Using the FPC.Arrays property to get a reference to the FPCArrays collection of the arrays collection.
  4. Calling the FPCArrays.Item method to get a reference to the FPCArray object representing the array.
  5. Using the FPCArray.Extensions property to get a reference to the FPCExtensions object for the array.
  6. Using the FPCExtensions.ApplicationFilters property to get a reference to the FPCApplicationFilters collection for the array.
  7. Calling the FPCApplicationFilters.Add method with the application filter's GUID and name, or calling FPCApplicationFilters.Remove to unregister the application filter in the array and skipping the next step. Note that an application filter can be removed from an array configuration only after all the references to it in the FPCRefs collection stored in the InstalledApplicationFilters property of every member of the array have been removed.
  8. Setting the vendor parameters sets and additional properties of the application filter, particularly its description, the name of the vendor who supplied it, and the version number.
  9. Registering protocols, events, and alerts as necessary (optional). For more information about creating an event and alert in an array, see Customizing the Setup Process.
  10. Associating protocols defined in the array with the application filter using GUIDs from the Protocol_guids.h file for predefined protocols.
  11. Calling the Save method on the FPCApplicationFilters collection to write the changes in the stored enterprise configuration.
  12. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the Configuration Storage server. This step can be skipped when Setup is run on a Configuration Storage server.

After these steps are performed, the application filter can be installed on the array members.

If this code is run on an array member to register the application filter in its array, the DLL and other necessary files should be copied to the computer, and the COM objects defined in the DLL, the type library, and all the classes in the type library should be registered in its Windows registry sometime before the FPCApplicationFilters.Add method is called. When the FPCApplicationFilters.Add method is called to register the application filter in the array, this method also registers the application filter as being installed on the array member by creating a reference to the new FPCApplicationFilter object in the FPCRefs collection stored in the InstalledApplicationFilters property of the local ISA Server computer.

After an application filter is registered in an array, an Application filter not registered alert may be issued on array members that have the filter in their array configuration, but do not have a reference to it in their InstalledApplicationFilters property. This alert indicates that the steps required to install and register the application filter on those array members must still be performed. We recommend resetting this alert after the filter is registered on all the array members.

If an enterprise administrator wants to register an application filter in an array from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the Configuration Storage server before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Installing and Registering the Application Filter on an Array Member

The process of installing and uninstalling an application filter on an array member after the application filter has been registered in the array includes the following steps:

  1. Copying the application filter's DLL and other necessary files to the array member.
  2. Publishing the COM objects, the type library, and all interfaces in the type library in the Windows registry on the array member.
  3. Creating an instance of the FPC root object and obtaining a reference to it.
  4. Calling the FPC.GetContainingServer method to get a reference to the FPCServer object representing the ISA Server computer.
  5. Using the FPCServer.InstalledApplicationFilters property to get a reference to the FPCRefs collection of references to the application filters installed on the server.
  6. Calling the FPCRefs.Add method and specifying the application filter's GUID in the Name parameter to create a reference to the FPCApplicationFilter object in the FPCRefs collection stored in the InstalledApplicationFilters property of the local ISA Server computer, or calling FPCRefs.RemoveSpecified and specifying the application filter's GUID in the Name parameter to unregister the application filter as being installed on the array member. Note that the FPCRefs.Add method will fail with HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) if the application filter was installed by running the option to register the application filter in the array on the array member. This error should be ignored.
  7. Prompting the administrator to obtain agreement for restarting the Firewall service and, if the administrator agrees to restart the Firewall service, calling the FPCServer.SendRestartNotification method with bit 0 set, which indicates that the Firewall service needs to be restarted.
  8. Calling the Save method on the FPCServer object to write the changes in the stored array configuration.

Registering the ISA Server Management Extension for the Application Filter

For information about creating an extension to ISA Server Management for an application filter and registering the extension, see Extending Forefront TMG Management.


Send comments about this topic to Microsoft

Build date: 11/30/2009

© 2008 Microsoft Corporation. All rights reserved.