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:
- 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
configuration of the computer's array.
- 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 ISA Server computers 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 ISA Server computer 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 ISA Server 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 ISA Server 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 a
Configuration Storage server includes the following steps:
- Creating an instance of the FPC root object and obtaining a
reference to it.
- 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.
- Using the FPC.Enterprise property to get a
reference to the FPCEnterprise object.
- Using the FPCEnterprise.Extensions
property to get a reference to the FPCExtensions object for the
enterprise configuration.
- Using the FPCExtensions.ApplicationFilters
property to get a reference to the FPCApplicationFilters
collection.
- 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.
- Setting the vendor parameters sets and additional properties of
the application filter.
- Calling the Save
method on the FPCApplicationFilters collection to write the
changes in the stored enterprise configuration.
- Defining protocols in the enterprise configuration
(optional).
- 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:
- Creating an instance of the FPC root object and
obtaining a reference to it.
- 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.
- Using the FPC.Arrays
property to get a reference to the FPCArrays collection of the
arrays collection.
- Calling the FPCArrays.Item method to get a
reference to the FPCArray
object representing the array.
- Using the FPCArray.Extensions property
to get a reference to the FPCExtensions object for the
array.
- Using the FPCExtensions.ApplicationFilters property to
get a reference to the FPCApplicationFilters collection for
the array.
- 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.
- 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.
- 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.
- Associating protocols defined in the array with the application
filter using GUIDs from the Protocol_guids.h file for predefined
protocols.
- Calling the Save method on the
FPCApplicationFilters collection to write the changes in the
stored enterprise configuration.
- 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:
- Copying the application filter's DLL and other necessary files
to the array member.
- Publishing the COM objects, the type library, and all
interfaces in the type library in the Windows registry on the array
member.
- Creating an instance of the FPC root object and
obtaining a reference to it.
- Calling the FPC.GetContainingServer
method to get a reference to the FPCServer object representing the
ISA Server computer.
- Using the FPCServer.InstalledApplicationFilters
property to get a reference to the FPCRefs collection of
references to the application filters installed on the server.
- 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.
- 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.
- 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.