Registering Filters in Enterprise Edition

  • Article

In Forefront TMG Enterprise Edition, multiple Forefront TMG servers can be joined to the same array. In the case of a standalone array, one of the servers is designated as the array manager, from which the array-level configuration settings of the other array members are updated. When an Enterprise Management Server (EMS) is deployed, multiple enterprise arrays can be created within a single enterprise. The EMS stores both enterprise-level and array-level configuration settings and centrally manages all the arrays in the enterprise. In this case, each array member obtains the enterprise configuration settings and the array configuration settings for its array from the central EMS and maintains a locally stored effective configuration that is derived from the enterprise and array configurations. Application filters can be registered in the application filters collections in the enterprise configuration and in array configurations.

In addition, Forefront TMG 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 Forefront TMG server only if all of the following conditions are met:

  • Its dynamic-link library (DLL) and other necessary files are copied to the computer.
  • The COM objects defined in the DLL, the type library, and all the classes in the type library are registered in its Windows registry.
  • The application filter is registered as an object in the array configuration of the Forefront TMG server.
  • The application filter is registered as being installed on the computer.

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:

  • Introduce an enterprise-wide configuration by attaching vendor parameters sets to the application filter object and enterprise nodes that will be available to all Forefront TMG servers in all arrays in the enterprise.

    The configuration settings in a vendor parameters set created on an enterprise-level object are combined into the effective configuration stored locally on each Forefront TMG server and can be retrieved by an application filter by accessing the vendor parameters sets attached to the corresponding array-level object. In particular, the vendor parameters sets attached to an enterprise-level application filter object can be retrieved by the application filter through the isaArray.Extensions.ApplicationFilters(Filter_GUID).VendorParametersSets property. If two vendor parameters sets with different globally unique identifiers (GUIDs) are defined for an application filter, one in the enterprise configuration and one in the array configuration, the application filter can access both of them through this property.

  • Associate a protocol that is defined in the enterprise configuration with the application filter in the enterprise configuration.

    If a protocol is defined with the same GUID in both the enterprise and array configurations, there will be only one protocol definition for it in the effective configuration, and the enterprise-level properties will override the array-level properties. If vendor parameters sets with different GUIDs are attached to this protocol definition in the enterprise and array configurations, both can be found in the combined protocol definition in the effective configuration.

  • Enable or disable the application filter in the enterprise configuration. If an application filter is enabled in the enterprise configuration, the enterprise setting is applied to each array, and the filter cannot be disabled in an array configuration. If an application filter is disabled in the enterprise configuration, it can be enabled or disabled in an array configuration.

  • Extend Forefront TMG Management by adding property pages for setting enterprise configuration settings for the application filter.

The Setup code may offer the following registration options:

  • Registering the application filter as an object in the enterprise configuration. This option is needed only if the application filter is enterprise-aware.
  • Registering the application filter as an object in an array.
  • Installing and registering the application filter on an array member.
  • Registering the Forefront TMG Management extension for the application filter. This option is needed only if configuration settings are defined for the application filter in one or more vendor parameters sets.

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 the EMS 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 EMS with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator.
  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 EMS.

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 EMS 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 Forefront TMG Enterprise Edition, an enterprise administrator can create an empty array and add an application filter to the array configuration before joining any Forefront TMG servers 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, an array manager, an EMS, 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 array manager or EMS 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 an array manager or EMS.
  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 configuration.
  12. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the array manager or EMS. This step can be skipped when Setup is run on the array manager or EMS.

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 Forefront TMG server.

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 array manager or EMS 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 Forefront TMG server.
  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 Forefront TMG server, 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 Forefront TMG Management Extension for the Application Filter

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

 

 

Build date: 7/12/2010