Registering Filters on a Standalone Server

In a standalone server deployment, you must install application filters on the Forefront TMG computer. Filters must be registered as COM servers and as extensions of the Microsoft Firewall service in the stored Forefront TMG configuration.

Note   Forefront TMG Medium Business Edition is always installed as a standalone server in a configuration containing one array that is associated with a single Forefront TMG computer.

General Setup Process

The process of installing and registering an application filter includes the following steps:

  1. Copying the dynamic-link library (DLL) and other necessary files to the Forefront TMG computer.
  2. Publishing the COM objects, the type library, and all interfaces in the type library in 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 (in the Data Monitor sample, the names of the functions to be exported are listed in the .def file). This step must be performed even if the filter project is compiled on the Forefront TMG computer.
  3. Registering the application filter as an object in the stored array configuration of the Forefront TMG computer.
  4. Registering the application filter as an installed extension of the Microsoft Firewall service on the computer by adding an FPCRef object that references its FPCApplicationFilter object in the FPCRefs collection held in the Forefront TMG computer's InstalledApplicationFilters property.
  5. Registering the applicable protocols (primary connection ports), events, and alerts as necessary.

In addition, Forefront TMG Management can be extended for an application filter by adding property pages for configuring the application filter. Registering a Forefront TMG Management extension for the application filter is optional. A Forefront TMG Management extension is required only if configuration settings are defined for the application filter in one or more vendor parameters sets. For information about creating an extension to Forefront TMG Management for an application filter and registering the extension, see Extending Forefront TMG Management.

Registering and Unregistering the Application Filter in the Array Configuration

The process of registering or unregistering the application filter in the array of the Forefront TMG computer 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 DllInstall function, which must also be exported by your DLL, or in a script or application. This code also automatically registers or unregisters the application filter as an installed application filter on the Forefront TMG computer.

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

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling the FPC.GetContainingArray method on the root object to obtain a reference to the FPCArray object representing the local array.
  3. Using the FPCArray.Extensions property to get a reference to the FPCExtensions object for the array.
  4. Using the FPCExtensions.ApplicationFilters property to obtain a reference to the FPCApplicationFilters collection for the array.
  5. Calling the FPCApplicationFilters.Add method with the application filter's GUID and name to register the application filter, or calling the FPCApplicationFilters.Remove method to unregister the application filter in the array and skipping the next step. Note that calling the FPCApplicationFilters.Remove method to unregister an application filter in an array automatically removes the reference to the FPCApplicationFilter object representing the application filter from the FPCRefs collection stored in the InstalledApplicationFilters property of the local Forefront TMG computer.
  6. Setting the vendor parameters sets and additional properties of the FPCApplicationFilter object for the application filter, particularly its description, the name of the vendor who supplied it, and the version number.
  7. 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.
  8. Associating protocols defined in the array with the application filter using GUIDs from the Protocol_guids.h file for predefined protocols.
  9. Calling the Save method on the FPCApplicationFilters collection to write the changes in the stored configuration.

If this code is run on a standalone Forefront TMG computer 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.

Customizing the Setup Process

The registration process can include changes to the Forefront TMG configuration. These changes can be invoked by your implementation of DllInstall using properties and methods of Forefront TMG administration COM objects. For example, to define a new event that the filter will signal when opening a log file fails, the implementation of DllInstall in the Data Monitor sample calls a method that does the following:

  1. Uses CoCreateInstance to create an instance of the FPC root object and obtain a smart pointer to the IFPC interface exposed by it.
  2. Calls IFPC::GetContainingArray to retrieve a pointer to the IFPCArray interface representing the array.
  3. Calls IFPCArray::RuleElements to retrieve a pointer to the IFPCRuleElements interface representing the Firewall service rule elements container.
  4. Calls IFPCRuleElements::EventDefinitions to retrieve a pointer to the IFPCEventDefinitions interface representing the collection of events defined in the array.
  5. Calls IFPCEventDefinitions::Add to create a new event in the collection.

To create an alert that can be issued for the new event and configure it to log the alert-triggering occurrences of the event in the system event log, the method called by the implementation of DllInstall in the Data Monitor sample also does the following:

  1. Calls IFPCArray::Alerts to retrieve a pointer to the IFPCAlerts interface representing the collection of alerts that are defined in the array.
  2. Calls IFPCAlerts::Add to add an alert for the new event to the collection.
  3. Calls the IFPCAlert::Actions property of the interface returned in the previous step to retrieve a pointer to the IFPCAlertAction interface for the new alert.
  4. Calls the IFPCAlertActions::SetLogEvent method to create a new action for the alert that will log the alert-triggering occurrences of the event in the system event log.

Example of Setup on a Forefront TMG Computer

To set up an application filter on a Forefront TMG computer, perform the following steps:

  1. Copy the DLL to the Forefront TMG computer.
  2. Call DllRegisterServer.
  3. Call DllInstall with the bInstall parameter set to TRUE and the pszCmdLine parameter set to the applicable command-line string.

As an alternative to steps 2 and 3, you can run:

regsvr32 /i:command_line_string dll_name.dll

Example of Uninstall on a Forefront TMG Computer

To uninstall an application filter from a Forefront TMG computer, perform the following steps:

  1. Call DllInstall with the bInstall parameter set to FALSE and the pszCmdLine parameter set to the applicable command-line string.
  2. Call DllUnregisterServer.

As an alternative to these steps, you can run:

regsvr32 /u /i:command_line_string dll_name.dll

Note  Because the filter objects are created when the Firewall service starts, the Firewall service must be stopped and then restarted after setup is complete.

The Regsvr32 command-line tool is not a required part of the setup. A setup program can use Regsvr32, or load the DLL and call the registration code directly.

Services may not have the necessary permissions to allow them to write vendor-specific information to the stored Forefront TMG configuration. For this reason, you should perform the saving of vendor parameters to the stored Forefront TMG configuration during filter setup.


Send comments about this topic to Microsoft

Build date: 11/30/2009

 

© 2008 Microsoft Corporation. All rights reserved.