Deep Freeze: Using PowerShell with DF Console Custom Actions

Overview
This document details the process of creating a Custom Action in Deep Freeze Enterprise Console using Windows PowerShell scripting technology

Introduction
A Deep Freeze Action File is an XML file that allows end users to define additional functionality in the Deep Freeze Enterprise Console. An Action File defines a method for calling an external command or program file and passing some workstation-specific information (e.g. machine IP addresses, computer names).

This document describes an example of using PowerShell script to initiate a remote command or run a process remotely on selected workstation(s) using Deep Freeze Enterprise Console.  It is assumed the user has some knowledge of PowerShell scripting, XML language, as well as Deep Freeze Custom Action XML syntax. For more information about Custom Action scripting please refer to Deep Freeze user’s guide and Technical Papers.

Configuring the environment and testing PowerShell script
To be able to use Windows PowerShell remote commands, PowerShell must be installed on the target Windows workstations and enabled. Recent Windows OS already have PowerShell installed, but those systems still may be shipped in a locked down configuration, where PowerShell is disabled.

The easiest way to enable Windows PowerShell remoting is to use the Enable-PSRemoting cmdlet on target workstation. To do this, launch Windows PowerShell with Admin rights and run following command:

PS C:\> Enable-PSRemoting -Force

This enables Windows Remoting service (WinRM) and configures the Windows Firewall so that it can accept incoming commands within same Domain. Mixed Domain environments require some additional configuration to get remote execution working, which is not in the scope of this document.

Testing PowerShell script
Before implementing PowerShell script as a Custom Action, it is a good practice to run the script on its own to insure it works correctly. In that case it makes it easier troubleshoot the script.

For the purpose of this document we will use a “Invoke-Command” which runs a script remotely. It has following syntax:

Invoke-Command -computername [COMPUTER] -ScriptBlock { [COMMAND] }

where [COMPUTER] is the target workstation Computer name, and [COMMAND] is the series of PoweShell commands.

In order to run PowerShell command without initiating PowerShell session we will use following command:

powershell -Command "& { <list of PowerShell commands> ;}"

In a following example it shows a command which uses PowerShell script for running IpConfig remotely against the target workstation with the name "Workstation1":

powershell -Command "& {Invoke-Command -computername Workstation1} -ScriptBlock {ipconfig /all; Start-Sleep -s 10};}"

This command can be launched from Windows Command Prompt window and will bring up a full IPConfig report for the target workstation and keep the Command Prompt window open for 10 seconds.

Implementing Custom Action for running a remote command
Once the above script has been successfully tested, it now can be embedded into Custom Action inside <EXECUTE> tag, where computer name will be parameterized with %%WKSNAME%% parameter, which is contextual to the selected workstation. Upon launching Custom Action Deep Freeze Console will build the actual command by replacing %%WKSNAME%% parameter with the currently selected workstation name:

<EXECUTE>powershell -Command & "{Invoke-Command -computername %%WKSNAME%% -ScriptBlock {ipconfig /all; Start-Sleep -s 10};}"</EXECUTE>

Some other Custom Action properties tags can be implemented accordingly to the user's requirements. Following is the complete Custom Action XML code:

<ACTION#>

    <CAPTION>

       <ENGLISH>Get ipconfig info</ENGLISH>

       <GERMAN>Get ipconfig info</GERMAN>

       <JAPANESE>Get ipconfig info</JAPANESE>

       <SPANISH>Get ipconfig info</SPANISH>

       <FRENCH>Get ipconfig info</FRENCH>

       <CHINESE>Get ipconfig info</CHINESE>

       <PORTUGUESE>Get ipconfig info</PORTUGUESE>

    </CAPTION>

    <FILEMENU>Y</FILEMENU>

    <POPUPMENU>Y</POPUPMENU>

           <SILENT>Y</SILENT>

    <SUBITEMS/>

    <PARAMS/>

    <SYNC/>

    <LOG/>

    <EXECUTE>powershell -Command &amp; &quot;{Invoke-Command -computername %%WKSNAME%% -ScriptBlock {ipconfig /all; Start-Sleep -s 10};}&quot;</EXECUTE>

    <WORKDIR>C:\Windows\system32\</WORKDIR>

</ACTION#>

This code snippet can be added into existing CustomActions.xml file, where <ACTION#> tag must be edited with actual number of action as it would show in Console Custom Action menus.

Note: in XML code some of the special characters must be replaced with character entities, as seen in above code sample.

In order the newly created Custom Action take effect, the Deep Freeze Console must be restarted.

Implementing Custom Action which prompts user to enter a remote command
In previous example we have created a specific custom action for running IPCconfig. This way user can create an unlimited number of predefined Custom Actions for each specific command as per user requirements.

However, it may give more flexibility, if the Custom Action would prompt the user to enter a command or program to be run on selected workstation. In order to achieve this, the command must parameterized inside the XML file similarly to workstation name described above.

In the below XML code sample we have reworked the previous PowerShell command, which now remotely runs cmd command, which in its turn launches any command, script or executable represented by %CMD% parameter, entered by user.

<ACTION#>
<CAPTION>
<ENGLISH>Push remote command using Powershell</ENGLISH>
<GERMAN>Push remote command using Powershell</GERMAN>
<JAPANESE>Push remote command using Powershell</JAPANESE>
<SPANISH>Push remote command using Powershell</SPANISH>
<FRENCH>Push remote command using Powershell</FRENCH>
<CHINESE>Push remote command using Powershell</CHINESE>
<PORTUGUESE>Push remote command using Powershell</PORTUGUESE>
</CAPTION>
<FILEMENU>Y</FILEMENU>
<POPUPMENU>Y</POPUPMENU>
<SILENT>Y</SILENT>
<SUBITEMS/>
<PARAMS>
<CMD>
<VAR>%CMD%</VAR>
<CAPTION>
<ENGLISH>Command</ENGLISH>
<GERMAN>Befehl</GERMAN>
<JAPANESE>ƒRƒ}ƒ“ƒh</JAPANESE>
<SPANISH>Comando</SPANISH>
<FRENCH>Commande</FRENCH>
<CHINESE>ÃüÁî</CHINESE>
<PORTUGUESE>Comando</PORTUGUESE>
</CAPTION>
</CMD>
</PARAMS>
<SYNC>N</SYNC>
<LOG/>
<EXECUTE>powershell -Command &quot;&amp; {Invoke-Command -computername %%WKSNAME%% -ScriptBlock {cmd /c %CMD%}&quot;</EXECUTE>
<WORKDIR>C:\Windows\system32\</WORKDIR>
</ACTION#>