Registering
Web 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. Web
filters can be registered in the Web filters collections in the
enterprise configuration and in array configurations. The Web
filters collection in the enterprise configuration is not ordered,
while the Web filters collection in an array configuration is
ordered and provides methods for changing the ordinal position of
each Web filter in the collection.
In addition, ISA Server Management can be extended for a Web
filter by adding property pages for configuring the Web filter on
the enterprise and array levels.
A Web filter can work on a ISA Server computer only if all of
the following conditions are met:
- Its dynamic-link library (DLL) is copied to the computer.
- The Web filter is registered as an object in the configuration
of the computer's array.
- The Web filter is registered as being installed on the
computer.
Registering the Web filter in the array configuration is
required for enforcing its policy in the array. Registering a Web
filter in the enterprise configuration is optional, but provides
several benefits. When you register a Web filter in the enterprise
configuration, you can do the following:
-
Introduce an enterprise-wide configuration by attaching vendor
parameters sets to the Web 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 a Web 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 Web
filter object can be retrieved by the Web filter through the
FPC.GetContainingArray.Extensions.WebFilters(Filter_GUID).VendorParametersSets
property. If two vendor parameters sets with different globally
unique identifiers (GUIDs) are defined for a Web filter,
one in the enterprise configuration and one in the array
configuration, the Web filter can access both of them through this
property.
- Enable or disable the Web filter in the enterprise
configuration. If a Web 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 a Web
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 Web filter.
The Setup code for a Web filter may offer the following
registration options:
- Registering the Web filter as an object in the enterprise
configuration. This option is needed only if the Web filter is
enterprise-aware.
- Registering the Web filter as an object in an array.
- Installing and registering the Web filter on an array member.
- Registering the ISA Server Management extension for the Web
filter. This option is needed only if configuration settings are
defined for the Web filter in one or more vendor parameters
sets.
Registering and Unregistering the Web Filter in the Enterprise
Configuration
The process of registering and unregistering a Web 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.WebFilters
property to get a reference to the FPCWebFilters
collection.
- Calling the FPCWebFilters.Add method with
the Web filter's GUID, the filter's name, the path for storing the
filter's DLL, including the file name of the DLL, relative to the
ISA Server installation folder, the filter's priority, and the
filter's direction, or calling FPCWebFilters.Remove to
unregister the Web filter in the enterprise configuration and
skipping the next step. Note that the path and priority supplied in
the call to the Add method are ignored in the enterprise
configuration.
- Setting the vendor parameters sets and additional properties of
the Web filter.
- Calling the Save
method on the FPCWebFilters 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.
If an enterprise administrator wants to register a Web 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 Web Filter in an Array
In ISA Server Enterprise Edition, an enterprise administrator
can create an empty array and add a Web filter to the array
configuration before adding any ISA Server computers to the array.
This code is applicable to registering and unregistering the Web
filter in an empty array or in an array that has array members.
Administrators should run this code only once to register the
Web 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 or
unregisters the Web filter as an installed Web filter on the array
member.
The process of registering and unregistering a Web 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.WebFilters property to get a
reference to the FPCWebFilters collection for the
array.
- Calling the FPCWebFilters.Add method with the Web
filter's GUID, the filter's name, the path for storing the filter's
DLL, including the file name of the DLL, relative to the ISA Server
installation folder, the filter's priority, and the filter's
direction, or calling FPCWebFilters.Remove to unregister the
Web filter in the array and skipping the next step. Note that a Web
filter can be removed from an array configuration only after all
the references to it in the FPCRefs collection stored in
the InstalledWebFilters
property of every member of the array have been removed.
- Setting the vendor parameters sets and additional properties of
the Web filter, particularly its description, the name of the
vendor who supplied it, and the version number.
- Registering events and alerts in the array configuration
(optional). For more information about creating an event and alert
in an array, see Signaling Events and
Alerts.
- Calling the Save method on the FPCWebFilters
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.
Steps for changing the order of the filters in the collection
using the FPCWebFilters.MoveDown and
FPCWebFilters.MoveUp
methods may be added.
After these steps are performed, the Web filter can be installed
and registered on the array members.
If this code is run on an array member to register the Web
filter in its array, the DLL should be copied to the computer and
stored in the location that will be passed in the
RelativePath parameter of the FPCWebFilters.Add
method sometime before this method is called. When the
FPCWebFilters.Add method is called to register the Web
filter in the array, this method also registers the Web filter as
being installed on the array member by creating a reference to the
new FPCWebFilter
object in the FPCRefs collection stored in the
InstalledWebFilters property of the local ISA Server
computer.
After a Web filter is registered in an array, a Web 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 InstalledWebFilters property. This
alert indicates that the steps required to install and register the
Web 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 a Web 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 Web Filter on an Array Member
The process of installing and uninstalling a Web filter on an
array member after the Web filter has been registered in the array
includes the following steps:
- Copying the Web filter's DLL to the array member and storing it
in the location that was specified in the RelativePath
parameter of the FPCWebFilters.Add method when the Web
filter was registered in the array.
- 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.InstalledWebFilters
property to get a reference to the FPCRefs collection of
references to the Web filters installed on the server.
- Calling the FPCRefs.Add
method and specifying the Web filter's GUID in the Name
parameter to create a reference to the FPCWebFilter object
in the FPCRefs collection stored in the
InstalledWebFilters property of the local ISA Server
computer, or calling FPCRefs.RemoveSpecified
and specifying the Web filter's GUID in the Name parameter
to unregister the Web 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 Web filter was
installed by running the option to register the Web filter in the
array on the array member. This error should be ignored.
- 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 Web
Filter
For information about creating an extension to ISA Server
Management for a Web 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.