Web Filter Setup
A Web filter must be installed locally on each Forefront TMG server where it will be invoked. The installation process must include copying the dynamic-link library (DLL) of the Web filter to the Forefront TMG server and registering the Web filter as an extension of the Forefront TMG Web proxy in the stored Forefront TMG configuration. The installation process can include steps that define events, alerts, and other elements in the Forefront TMG configuration. Each time that the Forefront TMG Web proxy is launched on a Forefront TMG server, the DLLs of all the installed Web filters are loaded into memory and stay in memory until it shuts down.
When an Enterprise Management Server (EMS) is deployed, Web filters can be registered in the stored Forefront TMG configuration on the enterprise level and on the array level.
Note Enterprise-level configuration settings are available only in Forefront TMG Enterprise Edition. Forefront TMG Standard Edition is always installed as a standalone server in a configuration containing one array that is associated with a single Forefront TMG server.
The process of installing and registering a Web filter includes the following steps:
- Copying the dynamic-link library (DLL) of the Web filter to the Forefront TMG server. Note that the path of the filter's DLL, including the file name of the DLL, relative to the Forefront TMG installation folder will be specified later in the RelativePath parameter of the FPCWebFilters.Add method when the Web filter is registered in the array configuration.
- Adding entries for the Web filter to the Windows registry. This registration is typically performed by the DllRegisterServer function. The implementation of this function in your DLL can be called by the Regsvr32 command-line tool (Regsvr32.exe), provided your DLL exports the function.
- Registering the Web filter as an object in the stored array configuration of the Forefront TMG server.
- Registering the Web filter as an installed extension of the Forefront TMG Web proxy on the computer by adding an FPCRef object that references its FPCWebFilter object in the FPCRefs collection held in the Forefront TMG server's InstalledWebFilters property.
- Defining the events, alerts, and other elements in the Forefront TMG configuration as necessary.
In addition, Forefront TMG Management can be extended for a Web filter by adding property pages for configuring the Web filter. Registering a Forefront TMG Management extension for the Web filter is optional. A Forefront TMG Management extension is required only if configuration settings are defined for the Web filter in one or more vendor parameters sets. The Forefront TMG Management extension for a Web filter should be installed in a separate process that includes copying its DLL to the Forefront TMG server and registering it as an extension. For information about creating an extension to Forefront TMG Management for a Web filter and registering the extension, see Extending Forefront TMG Management.
The process of registering or unregistering the Web filter in the array of the Forefront TMG server on which it is run uses properties and methods of the Forefront TMG administration COM objects. This process can be implemented in your DLL using the DllRegisterServer or DllInstall function, which must be exported by your DLL, or in a script or application. This code also automatically registers or unregisters the Web filter as an installed extension of the Web proxy on the Forefront TMG server.
The process of registering and unregistering a Web filter in the local array of a Forefront TMG server consists of the following steps:
- Creating an instance of the FPC root object and obtaining a reference to it.
- Calling the FPC.GetContainingArray method on the root object to obtain a reference to the FPCArray object representing the local 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 of the filter's DLL, including the file name of the DLL, relative to the Forefront TMG installation folder, the filter's priority, and the filter's direction to register the Web filter by creating an instance of the FPCWebFilter COM object that represents the new filter in the FPCWebFilters collection, or calling the FPCWebFilters.Remove method to unregister the Web filter in the array and skipping the next step. Note that calling the FPCWebFilters.Remove method to unregister an Web filter in an array automatically removes the reference to the FPCWebFilter object representing the Web filter from the FPCRefs collection stored in the InstalledWebFilters property of the local Forefront TMG server.
After you register a new Web filter in the array, you can change the order of the filters in the collection using the MoveDown and MoveUp methods. Each FPCWebFilter object is specified by the GUID used to add it to the FPCWebFilters collection.
- Registering the filter as a Web filter on each member server within the array by adding an FPCRef object that references the new FPCWebFilter object in the FPCWebFilters collection.
The registration of the Web filter is accomplished autmatically for the server on which the FPCWebFilters.Add method is run. The Web filter's GUID which was provided in the Name parameter of the FPCWebFilter.Add method was used to create a reference to the new FPCWebFilter object in the FPCRefs collection held in the InstalledWebFilters property of the local Forefront TMG server.
- 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.
- Calling the Save method on the FPCWebFilters collection to write the changes in the stored enterprise configuration.
You can write code into a Web filter so that it can be registered or unregistered from the command line, and added to Forefront TMG Management. For information about how to build a Web filter that supports self-registration of the filter with Forefront TMG, see Self-Registering Web Filters. For code examples that demonstrate how a Web filter can be registered from the command line, see Forefront TMG Web Filter Sample Administration Steps.
For information about registering Web Filters in Forefront TMG Enterprise Edition, see Registering Web Filters in Enterprise Edition.
Build date: 7/12/2010