Stirling and Windows PowerShell

Stirling and Windows PowerShell

Collapse All

Microsoft Forefront codename Stirling

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Windows Windows PowerShell provides the foundation for all tasks in the Stirling environment. Each task you perform in the Stirling console is powered by Windows PowerShell, and most of the tasks can be performed independently of the Stirling console, within Windows PowerShell itself.

About Windows PowerShell and Stirling

Stirling functionality in Windows PowerShell is provided by an addition to the Windows PowerShell environment called a snap-in. Snap-ins extend the functionality of Windows PowerShell by adding additional cmdlets to the standard Windows PowerShell environment.

Windows PowerShell performs tasks through the use of cmdlets. Cmdlets are commands in the Windows PowerShell environment that are composed of verb-noun pairs. The verb defines the action to be performed, and the noun defines the item the action is performed on.

For example, to get the list of the available cmdlets in a Windows PowerShell console, type the following in a Windows PowerShell console:

Get-Command

This cmdlet "gets" a list of available "commands".

The output of a cmdlet varies depending on the cmdlet itself and any formatting parameters passed to the cmdlet.

About snap-ins

By default, only the standard Windows PowerShell snap-ins are loaded, or added, to the default Windows PowerShell console. To get a list of the snap-ins currently added to your Windows PowerShell console, use the Get-PSSnapin cmdlet. Type the following in a Windows PowerShell console:

Get-PSSnapin

The output is a list of all snap-ins currently added to the Windows PowerShell console.

If your snap-in is not listed when you use Get-PSSnapin, you must add the snap-in to your Windows PowerShell console. To determine the name of the snap-in, type the following in a Windows PowerShell console:

Get-PSSnapin -Registered

The output is a list of all non-default snap-ins currently installed on your computer.

Once you have the name of the snap-in, you can add it to your Windows PowerShell console. To do this, use the Add-PSSnapin cmdlet. Type the following in a Windows PowerShell console:

Add-PSSnapin name of snapin

There is no output from this cmdlet. However, you can check the list of current snap-ins by using Get-PSSnapin to verify your snap-in was added.

To add the Stirling snap-in to your Windows PowerShell console, type the following in a Windows PowerShell console:

Add-PSSnapin ffspssnapin

The snap-ins added using Add-PSSnapin are only added for that console; if you close the Windows PowerShell console and open it again, you must add the snap-in back into the Windows PowerShell environment.

To load the Stirling snap-in every time you start a Windows PowerShell console, you must create a Windows PowerShell profile.

To create a Windows PowerShell profile

Start Notepad, and then add the following line:

Add-PSSnapin ffspssnapin
On the menu bar, click File, and then click Save As.
In the folder list, browse to the folder location appropriate for the scope of the profile:

For a profile that affects all users of the computer, browse to the following location:

%windir%\system32\windowspowershell\v1.0

For a profile that affects only the current user, browse to the following location: %UserProfile%\My Documents\windowspowershell
In the File name box, enter Profile.ps1.
In the Save as type box, click on the down arrow, click All Files, and then click Save.

The Stirling snap-in will now be loaded each time you start Windows PowerShell.

About parameters

Each cmdlet has parameters that are used to provide information to the cmdlet when it runs. Parameters are placed after the cmdlet and are preceded by a dash (-).

Parameters can be either mandatory or optional. Mandatory parameters are used to supply the cmdlet with information necessary to complete the task. Optional parameters are used to either modify the way the cmdlet runs or supply additional information to the cmdlet.

For example, to get the list of Stirling-specific cmdlets installed in the Windows PowerShell environment, you use the same cmdlet mentioned previously, Get-Command. However, this time you must restrict the returned list of cmdlets to those that are provided by the Stirling snap-in. To get the list of cmdlets provided by the Stirling snap-in, type the following in a Windows PowerShell console on the Stirling server:

Get-Command -pSSnapin ffspssnapin

The output is a list of the cmdlets available in the Stirling snap-in (ffspssnapin).

Help in Windows PowerShell

Help in the Windows PowerShell environment is available via a cmdlet. To get help about a cmdlet, type the following in a Windows PowerShell console:

get-help cmdletname

The output is a basic help display in the console itself.

To get help for the cmdlet that creates connections to the Stirling database, type the following:

get-help new-fsyssession

The following table describes the four types of help available in Windows PowerShell for cmdlets.

Help type	Output
Basic	When you use the Get-Help cmdlet without any parameters, the output is a brief summary of what the cmdlet does. Included in this summary is the synopsis of the cmdlet, the cmdlet's syntax, and a detailed description of the cmdlet.
Detailed	When the -detailed parameter is used with Get-Help, the help output is expanded to include information about cmdlet parameters.
Full	When the -full parameter is used with Get-Help, the help output is expanded further to include technical details about the parameters.
Examples	When the -examples parameter is used with Get-Help, the help output is restricted to only the synopsis and the usage examples of the cmdlet.

In addition to accessing the Stirling cmdlet help in a Windows PowerShell console, help for each cmdlet is available in the Stirling Technical Reference.

Working with configuration documents

You create policies in the Stirling console by selecting the individual policy units to be included with the policy. The main policy sections in the Stirling console contain the policy units for particular protection areas. For example, in the Edit Policy dialog box, under the Computer Protection section, and then under the Antimalware section, the General policy unit contains all general antimalware settings.

Each specific policy section in the policy tree is contained within a configuration document. Each configuration document contains the policy units that are represented under the main policy sections.

To create and manage policy with Windows PowerShell, you create the policy object and then add configuration documents to the policy object. When the policy is bound to a group, these configuration documents are used to calculate the effective configuration of the assets in the group, based on the precedence of the bindings linking the group to all of its policies. This effective configuration is sent to the asset in the form of an .xml document.

Using Windows PowerShell and the Stirling snap-in, you can directly read and, in some cases, edit these sections and subsections by using the configuration documents directly.

Changing configuration document settings

To work with a configuration document, you must first add it to a policy object. To do this, type the following in a Windows PowerShell console, substituting the appropriate name for your policy after -PolicyRef:

New-FSysConfigDoc -Type FSys.am -PolicyRef MyPolicy

This adds an instance of the FSys.am configuration document to the policy named MyPolicy.

Because configuration documents contain many settings, you must work with them in an environment that can hold the entire group of settings. To work with the configuration document in the previous example, for instance, type the following in a Windows PowerShell console:

$am = Get-FSysConfigDoc -Type FSys.am -PolicyRef MyPolicy

$am is a variable that is used in the example in order to hold the FSys.am configuration document from the policy named MyPolicy.

Once the configuration document has been retrieved and assigned to a Microsoft .NET object, you can work with it as you would work with any other .NET object. You must enable the subsections within the configuration document (for example, General) in order to enable the individual settings within that section.

For example, to enable the General section in the FSys.am configuration document, type the following in a Windows PowerShell console:

$am.General.FSys.DocumentSection.FSys.Enabled = $True

This example sets the Enabled value for the General subsection (DocumentSection) to True. To enable other subsections in the FSys.am configuration document, substitute the subsection name for General in the example.

Once a subsection is enabled, you can then modify the values of the individual settings. Configuration documents have default attribute values that are enabled once a subsection has been enabled. For example, once the General subsection has been enabled, the General.Updates.IntervalUpdate.Enabled attribute is set to True, and the General.Updates.IntervalUpdate.Enabled.HourlyFrequency is set to 3.

To change the update frequency to every six hours, type the following in a Windows PowerShell console:

$am.General.Updates.IntervalUpdate.Enabled.HourlyFrequency.FSys.Value=6

Modifying an attribute that is a "choice"-type value is done in a different way. To access these settings, envision the settings that share the "choice" value as a mutually-exclusive selection list. For example, the settings for Interval and Daily scanning are "choice" values:

General.ScheduledScans.QuickScan.Enabled.Schedule.Interval

The "choice" between these two is the only "choice" to be made at this level, so the "choice" ordinal is 0. You must then set "choice 0" to the desired setting. To set QuickScan to run on a Daily schedule instead of an Interval schedule, type the following in a Windows PowerShell console:

$am.General.ScheduledScans.QuickScan.Enabled.Schedule.FSys.Choices[0].FSys.ActiveChoice="Daily"

If there are multiple "choices" at the level you need to configure, you must count to determine the ordinal for the "choice" you want to modify.

Once you have finished editing the configuration document, you must write the changes from the variable to the database. To do this, you use the Set-FSysConfigDoc cmdlet. Type the following in a Windows PowerShell console:

Set-FSysConfigDoc -InputObject $am

Reading configuration document settings

In order to determine if a subsection or attribute is enabled or disabled, configuration documents can also be read from. Again, to work with the configuration document, you must load the configuration document into a Windows PowerShell variable. Type the following in a Windows PowerShell console:

$am=Get-FSysConfigDoc -Type FSys.am -PolicyRef MyPolicy

To determine the value of a single attribute, you type the path to the value without specifying a value. For example, type the following in a Windows PowerShell console and press ENTER:

$am.General.FSys.DocumentSection.FSys.Enabled

If the output is True, then the General section of the configuration document has been enabled. If the output is False, it is not enabled.

Typing the path to any value and pressing ENTER without specifying a new value will output the current value.

Site Feedback