Microsoft Internet Security and Acceleration Server 2004 SDK

Filter Setup

You must install application filters on the ISA Server computer, where they must reside locally. Filters must be registered as COM servers and as extensions of the Microsoft Firewall service in the ISA Server configuration. Each time that the Firewall service starts, it creates an instance of the registered COM object that implements the IFWXFilter interface, known as the filter object, for each application filter that is installed and enabled.

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

  1. Copy the dynamic-link library (DLL) and other necessary files to the ISA Server computer..
  2. Publish the COM objects, the type library, and all interfaces in the type library in the Windows registry. This registration is typically implemented in the DllRegisterServer function. The implementation of this function in your DLL can be called by the Regsvr32 command-line utility (Regsvr.exe), provided your DLL exports the function. This step must be performed even if the filter project is compiled on the ISA Server computer.
  3. Register the filter in the stored ISA Server configuration as an application filter for the Microsoft Firewall service by calling IFWXFilterAdmin::InstallFilter. This call passes the CLSID of the filter object, the name of the filter, a description, the name of the vendor who supplied it, the version number, and an array of GUIDs that specifies the protocols using GUIDs from the Protocol_guids.h file. You should implement this step using the DllInstall function, which must also be exported by your DLL.
  4. Register the primary connection ports and alert events, as necessary.

Customizing the Setup Process

The registration process can include changes to the ISA Server configuration. These changes can be invoked by your implementation of DllInstall using properties and methods of ISA Server administration COM objects. For example, to register a new event that the Firewall service will trigger when opening a log file fails, the implementation of DllInstall in the Data Monitor sample calls a method that performs the following steps:

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

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

  1. Call IFPCArray::Alerts to retrieve a pointer to the IFPCAlerts interface representing the collection of alerts that are defined in the array.
  2. Call IFPCAlerts::Add to add an alert for the new event to the collection.
  3. Call 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. Call the IFPCAlertActions::SetLogEvent method to create a new action for the alert that will log the signaled occurrences of the event in the system event log.

Example of Setup on an ISA Server Computer

To set up an application filter on an ISA Server computer, perform the following steps:

  1. Copy the DLL to the ISA Server 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" mydll.dll 

Example of Uninstall on an ISA Server Computer

To uninstall an application filter from an ISA Server 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" mydll.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 utility is not a required part of the setup. A setup utility 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 directory service. For this reason, you should perform the saving of vendor parameters to ISA Server during filter setup.