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
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:
- Copying the dynamic-link library (DLL) and other necessary
files to the Forefront TMG computer.
- 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.
- Registering the application filter as an object in the stored
array configuration of the Forefront TMG computer.
- 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
- 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
Registering and Unregistering the Application Filter in the
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:
- 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
- Using the FPCArray.Extensions property
to get a reference to the FPCExtensions object for the
- Using the FPCExtensions.ApplicationFilters
property to obtain a reference to the FPCApplicationFilters
collection for the array.
- Calling the FPCApplicationFilters.Add
method with the application filter's GUID
and name to register the application filter, or calling the
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
- 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.
- Registering protocols, events, and alerts as necessary
(optional). For more information about creating an event and alert
in an array, see Customizing the Setup
- Associating protocols defined in the array with the application
filter using GUIDs from the Protocol_guids.h file for predefined
- 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.
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:
- Uses CoCreateInstance to create an instance of
the FPC root object and obtain a smart pointer to the
IFPC interface exposed by it.
- Calls IFPC::GetContainingArray to retrieve a pointer to
the IFPCArray interface representing the array.
- Calls IFPCArray::RuleElements to
retrieve a pointer to the IFPCRuleElements interface
representing the Firewall service rule elements container.
- Calls IFPCRuleElements::EventDefinitions
to retrieve a pointer to the IFPCEventDefinitions
interface representing the collection of events defined in the
- 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
- Calls IFPCArray::Alerts to retrieve a
pointer to the IFPCAlerts interface
representing the collection of alerts that are defined in the
- Calls IFPCAlerts::Add to
add an alert for the new event to the collection.
- 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.
- 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
Example of Setup
on a Forefront TMG Computer
To set up an application filter on a Forefront TMG computer,
perform the following steps:
- Copy the DLL to the Forefront TMG computer.
- Call DllRegisterServer.
- 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:
Uninstall on a Forefront TMG Computer
To uninstall an application filter from a Forefront TMG
computer, perform the following steps:
- Call DllInstall with the bInstall
parameter set to FALSE and the pszCmdLine parameter set to
the applicable command-line string.
- Call DllUnregisterServer.
As an alternative to these steps, you can run:
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
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.
about this topic to Microsoft
© 2008 Microsoft Corporation. All rights reserved.