Incorporate Custom Actions
Updated: March 28, 2003
Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2
Connection Manager has the ability to run custom actions at various points when establishing a connection. By providing custom actions, you can enhance the connection experience for your users. Use the CMAK wizard to include custom actions in your service profile to automatically start programs when users connect to your service. A custom action can be any batch file, executable file, or dynamic-link library (DLL). These custom actions can use programs that users have installed, or you can distribute the programs with your service profile.
Using the CMAK wizard, you can specify custom actions for each of the following points during the connection process.
Pre-initialization actions. These actions occur immediately when the user starts the Connection Manager client.
Pre-connect actions. These actions occur before the connection attempt.
Pre-dial actions. These actions occur before every dialing attempt, including redials. (For dial-up connections only.)
Pre-tunnel actions. These actions occur before tunneling. (For VPN connections only.)
Post-connect actions. These actions occur immediately after the connection is established.
Disconnect actions. These actions occur immediately after the user or server disconnects.
On cancel actions. These actions occur whenever the user abandons a connection attempt.
On error actions. These actions occur whenever the connections attempt fails due to an error.
You might want to use pre-connect actions to start an application before you connect, such as an e-mail program, or use a post-connect action to upload logs of connection activity or to download the latest virus signatures. An on error action could also be used to point the user to custom Help files for self-help information, potentially reducing help desk calls.
Several common custom actions are built into CMAK, such as:
A post-connect action checks for phone book updates. This action is automatically included in your profile if you leave the Automatically download phone book updates check box selected on the Phone Book page of the CMAK wizard.
A post-connect action obtains and installs routing tables for the target network. This action is automatically included in your profile if you enable the Routing Table Update feature.
A post-connect action updates proxy settings of the client during the connection. This action is automatically included in your profile if you enable the Automatic Proxy Configuration feature.
The Windows Server 2003 Technical Reference also contains custom actions you can use to customize your profile:
This includes the files Getcm.exe, which runs as a post-connect action that checks for and downloads an updated service profile, and Instcm.exe, which runs as a disconnect action that checks to see if an updated service profile has been downloaded and installs it.
This DLL (Cmgetcer.dll) allows Connection Manager to automatically obtain a certificate for L2TP/IPSec connections.
Network Access Quarantine Control
This network policy requirements script runs as a post-connect action. The network policy requirements script performs validation checks on the remote access client computer to verify that it conforms to network policies. The script can be a custom executable file or simple batch file.
When the script has run successfully and the connecting computer has satisfied all of the network policy requirements (as verified by the script), the script executes a notifier component (an executable) with the appropriate parameters. You can also configure your script to download the latest version of the script from a quarantine resource. If the script does not run successfully, it directs the remote access user to a quarantine resource such as an internal Web page, which describes how to install the components that are required for network policy compliance.
The notifier component sends a message to the quarantine-compatible remote access server that indicates a successful execution of the script. You can use your own notifier component or you can use Rqc.exe, which is provided on the Windows Server 2003 Deployment Kit companion CD. With these components installed, the remote access client computer uses the Connection Manager profile to perform its own network policy requirements check and indicate its success to the remote access server as part of the connection setup.
Because Network Access Quarantine Control introduces a delay in obtaining normal remote access, applications that run immediately after the connection is complete might encounter problems. One way to minimize the delay is to separate your script into two scripts: one that runs as a pre-connect action and one that runs as a post-connect action.
For more information about Network Access Quarantine Control, see "IAS Network Access Quarantine Control" in Help and Support Center for Windows Server 2003, "Deploying Dial-up and VPN Remote Access Server" and "Deploying Internet Authentication Service (IAS)" in this book. For a sample notifier component, see the Windows SDK. For more information about the Windows SDK, see the Software Development Kit (SDK) information in the MSDN Library link on the Web Resources page at http://www.microsoft.com/windows/reskits/webresources.
In addition to these predefined custom actions, you can create your own custom actions to include in the service profile.
For security reasons, custom actions cannot be run when users log on to the network using dial-up networking unless certain registry keys have been set. For more information about custom actions, see "Incorporating custom actions" in Help and Support Center for Windows Server 2003.