Intel vPro Expert Center Blog

Powershell: Controlling AMT Power States

pcgeek86@gmail.com — Sun, 19 Apr 2009 16:25:53 GMT

I wanted to quickly share an example of how to set the current power state of a provisioned Intel vPro system using Windows Powershell!

Take a moment, and ask yourself these quick questions:

Have you ever wanted to be able to automate the powering up, or powering off, of multiple computers?
Is your company interested in saving money by not needlessly leaving computers powered on at night?
Do you have a time-critical environment, such as a call center, where you need to reliably power up your computers so they are ready to go in the morning for agents?
Do you want to be able to create your own helpdesk tools to enable remote reset of hung systems?

If you answered "yes" to any of the previous questions, then hopefully this Powershell code will help you, as an administrator, achieve your goals! Let's take a look at how to perform the actions of:

Powering up a vPro (AMT) system
Powering down a vPro (AMT) system (not gracefully, just FYI)
Power cycling a vPro (AMT) system (also not graceful)

For the sake of simplicity, we'll continue to work with the ManageabilityStack.AmtSystem object that I have referenced in my previous article(s). If you aren't sure how to get the $Global:Amtdevice Powershell variable, please look back at my other articles. This will also require the download of the Intel AMT Developer Toolkit. You'll need the Manageability Stack.dll library contained within.

-------------------

In order to control the remote power state of an AMT system, all you really need to know are these 3 hex values:

0x10 = System reset

0x11 = Power on

0x12 = Power off

0x13 = Reset w/ power cycle

These hex values will be used with the $AmtSystem.Remote.SendRemoteControl() method to alter the power state of the remote system. The SendRemoteControl() method included with the DTK includes a number of parameters that go beyond the scope of this article, so we will pass hex value 0x0 to these parameters for the time being. In order to use the above hex values, simply pass the hex value as the first parameter of the SendRemoteControl() method. In order to fulfill the parameter requirements of this method, pass 5 additional parameters with the value 0x0. Here are some examples:

Powering up an AMT System

$Result = $AmtDevice.Remote.SendRemoteControl(0x11, 0x0, 0x0, 0x0, 0x0, 0x0)

Write-Host "Power command resulted with: ${Result}"

Powering off an AMT System

$Result = $AmtDevice.Remote.SendRemoteControl(0x12, 0x0, 0x0, 0x0, 0x0, 0x0)

Write-Host "Power command resulted with: ${Result}"

Power cycling an AMT System

$Result = $AmtDevice.Remote.SendRemoteControl(0x10, 0x0, 0x0, 0x0, 0x0, 0x0)

Write-Host "Power command resulted with: ${Result}"

The above samples show how to use the SendRemoteControl() method of the AmtRemoteControl .NET type in the Intel AMT Developer Toolkit (DTK) to control the power state of a remote AMT device.

If you have any questions about this, please leave a comment or send me a private message.

Sincerely,

Trevor Sullivan

Systems Engineer

OfficeMax Corporation

Which SCS Service setting to go for - script or from DB? Everything you ever wanted to know...

tal.elgar@intel.com — Wed, 15 Apr 2009 11:42:48 GMT

If you are using Intel SCS 5.x, after you've installed it you will need to decide whether you want to configure the scs service to either get configuration parameters from a script or from the DB. This seemingly innocuous decision has some technical implications, so here's the background..

Choice A - get configuration parameters from the DB

Let us first define what are the configuration parameters - they are the fields of a vPro system - such as: FQDN, AD OU, Profile - the important ones that are required for completing provisioning - and the remaining informative attributes, such as AMT firmware version etc. Therefore the configuration parameters that are necessary to have are FQDN (or hostname) AD OU path (if you are integrating with Active Directory) and the SCS provisioning profile being assigned to the vPro system. Where will the information for these 3 fields come from?

The wording of this option might be slightly misleading as you might (wrongfully) assume that the configuration parameters to get your vPro systems provisioned smoothly are sitting and waiting in the DB for you and will provide you an extra smooth provisioning experience over above the other method (using a script). This is however not the case; the configuration parameters are empty to begin with and only after going through a (successful or unsuccessful) provisioning process for each vPro machine, it will in turn have these configuration parameters populated in the DB, so that subsequent provisioning attempts will in fact be able to rely on these now populated configuration parameters in the DB.

Let us consider the flow of events...

A vPro system needs to initiate the provisioning process and let the SCS know about its existence - this is commonly known as the 'hello packet'. The hello packet contains a UUID (unique identifier), certificate hash or PID, MAC Address and ip address. Purely technically speaking, this will manifest itself by a new entry appearing in the AMTS table in the SCS DB. At that point you are missing the FQDN, AD OU path and profile ID. Once a new entry makes it into the AMTS table, it will also appear in the SCS Console as an unconfigured system with the UUID field populated, but the rest being blank.

You now have an option to manually double click on the row in the SCS Console and enter these 3 fields. Once you've done that, the information will now be sitting also in the UUID_MAPS table which is also know as the configuration parameters. This is typically not a scalable method and therefore the current BKM is to rely on a client side utility to send more than just the UUID, pre-provisioning information (cert hash or PID) and IP address, but also the FQDN, AD OU path and a profile ID.

The utility that has been designed to do this is the Activator utility which comes bundled when you download the SCS application (this blog posting won't go into the details of how to use the Activator Utility and what options you have and will assume you have an understanding of how to do this). Therefore instead of manually (and quite error prone) populating the fields, you can now have a utility that effectively pushes all the information required for provisioning into the UUID_MAPS table as well.

Another last option is to create a list mapping UUIDs and pre-assigning them FQDNs and uploading it into the UUID_MAPS table. This is more difficult as it relies on the OEM providing you with an accurate list of all the UUIDs prior to receiving the systems. This is technically feasible but logistically more difficult and as such is a rarer implementation.

Choice B - get configuration parameters from the script

This method might be less popular, as it is a bit more complex and should be used only when the circumstances necessesitate it. The script would typically be a VBscript for which a sample script is provided when you install the SCS service. What the server script does in essence is set the AD OU path and profile ID. The FQDN still needs to be provided by the vPro machine itself and for that it will rely on either the activator utility (as mentioned above) or client side vbscript - either of which will typically rely on a WMI query.

Purely technically speaking, the script takes the different parameters available to it and constructs an XML file (map.xml) that is formulated in a manner that is recognised and can be consumed by the SCS application. If there aren't enough permissions for the script to run locally, any necessary parameters are missing, or if the XML is not formulated properly then the SCS will complain about a missing XML file.

Using the server side script provides you the flexibitliy of making changes to the AD OU path and profile ID further down the line as opposed to the client side only method, which would have required you to pre-package the parameters to invoke the client utility and any changes would involve deploying a new package to all machines.

The server side script also allows you to overcome any permissions related issues and security concerns, as the client side only method typically requires administrator priveleges and involves letting each client right into the main DB (which for some security experts is an opportunity for malicious behaviour). Therefore a 2-tiered approach is possible where the client side (script or activator) send information into an interim DB and the server script reads the information from the interim DB. The trigger for the server script to run, is for a new entry to appear in the AMTS table but not have an entry in the UUID_MAPS table - i.e. a hello packet has arrived and there are no present configuration parameters.

Finally, the server script is essential if any further manipulations are required in order to accommodate a particular environment. Such is the case when the FQDN queried on the vPro client has a domain suffix of an Active Directory domain, but there is a separate non-AD integrated network domain and any queries to DNS will return the network domain FQDN. This requires provisioning the vPro system with the network domain, which could either be hard coded as a constant (like the AD OU path and profile ID) if there is only one, or it will need to be dynamic and poll DNS (though something like nslookup on IP address) to replace the AD FQDN with a network FQDN. Provisioning will succeed regardless, but the problem will be later on when trying to manage the vPro machine if you will be using AD integration and therefore will need to conform to the Kerberos protocol.

A situation can arise where you have configured SCS to use the script, however the the configuration parameters have already been populated due to a previous provisioning attempt - be it fully successful or not, since the parameters are in the DB already, the trigger for the server script to run will be missing and therefore it won't execute again. This scenario is typically come across in testing when the same machine is re-used. There are some 'real-world' scenarios such as machine has broken, is re-imaged and fixed by IT department, the client side provisioniong components (activator) kick-in on startup (typically) but the configuration parameters are already in the SCS DB and therefore the script will not run and provisioning won't succeed. Unfortunately SCS does not automatically remove the configuration parameters for machines that are partially or even fully unprovisioned. It can only be done manually when a system is deleted from the SCS Console and the 'delete configuration parameters' must explicitly be selected.

This turned out to be a longer posting than originally intended... but if you've made this far, hopefully you've picked up a few useful nuggets of information...

Tal

Powershell: Exploring the Management Engine

pcgeek86@gmail.com — Wed, 25 Feb 2009 04:26:00 GMT

Hello vPro Experts!

I would like to take some time to touch on exploration of the management engine via the local interface (specifically the HECI driver). In order to follow the exercise here, you'll need to have Windows Powershell installed, have the Intel AMT Developer Toolkit downloaded and installed, and have an AMT client (does not need to be provisioned) with the HECI driver installed. The HECI driver should be downloadable from your OEM.

To give you a high-level idea of the program flow we'll use to access the AMT device, consider the following:

Load the "Manageability Stack.dll" .NET library
Create an instance of the ManageabilityStack.HeciWrapper object
Reference the properties and methods of the HeciWrapper object, and the HeciMeInfo object (provided by the HeciWrapper.MeInfo property)

Here is the Powershell code that correlates to the above process:

Loading the .NET Library

# Load the Manageability Stack .NET library

$AmtLib = "C:\Program Files\Intel\Manageability Developer Tool Kit\Manageability Stack.dll"
[System.Reflection.Assembly]::LoadFile($AmtLib)
# Create a HeciWrapper object

$Heci = New-Object ManageabilityStack.HeciWrapper

# Pipe the $Heci variable into the Get-Member cmdlet to determine what properties

# and methods are available to us.

$Heci | Get-Member

Obtaining a list of embedded certificate hashes

# List embedded certificate hashes
$Heci.MeInfo.EnumerateHashHandles()

Getting the BIOS and AMT Versions

# Retrieve the AMT version
Write-Host "AMT version: $($Heci.Versions.Versions["AMT"])"
# Retrieve the BIOS version
Write-Host "BIOS version: $($Heci.Versions.BiosVersion)"

Retrieving Provisioning Information

# Retrieve the provisioning server name
Write-Host "Provisioning server: $($Heci.MeInfo.GetAuditRecord().ProvServerFQDN)"
# Determine provisioning date
# This will return "01/01/0001 00:00:00" if not provisioned
Write-Host "Provision date: $($Heci.MeInfo.GetAuditRecord().TlsStartTime)"
# Get provisioning mode (Enterprise, SMB, etc.)
Write-Host "Provision mode: $($Heci.MeInfo.GetProvisioningMode().ProvisioningMode)"
# Get provisioning state
Write-Host "Provision state: $($Heci.MeInfo.GetProvisioningState())"

-----------------------------------

I hope these code samples are able to help you out in your administration / engineering endeavors! Please let me know if you have any questions, and don't forget that in Powershell .... when in doubt .... use Get-Member to discover what information is available to you!

Trevor Sullivan

Systems Engineer

OfficeMax Corporation

Powershell: Enabling auto-provisioning on SCCM client

pcgeek86@gmail.com — Tue, 17 Feb 2009 05:01:39 GMT

Hello!

Have you ever run into the situation where you want to enable the auto-provisioning policy for a ConfigMgr client, but dont' want to wait for the policy to filter down to the client? If you're like me, then you would answer with a hearty "yes." Thankfully, I've got a method for you to force an SCCM client to enable auto-provisioning, without relying on the collection setting!

Keep in mind that, for some odd reason, pasting this code into a Powershell window will probably fail. Instead, paste the first 4 lines, and manually type out the last (red) line.

$OobSettings = [wmiclass]”root\ccm\policy\machine\actualconfig:CCM_OutOfBandManagementSettings”
$OobSettingsInstance = $OobSettings.CreateInstance()
$OobSettingsInstance.AutoProvision = $True
$OobSettingsInstance.SiteSettingsKey = 1
$OobSettingsInstance.Put()

Basically what this does is spawn an instance of the CCM_OutOfBandManagementSettings WMI class, sets two properties on it, and then writes it back to the system. This should enable auto-provisioning immediately so you don't have to wait!

Trevor Sullivan

Systems Engineer

OfficeMax Corporation

Stepping through vPro / Powershell code

pcgeek86@gmail.com — Thu, 04 Dec 2008 01:21:45 GMT

Hello vPro community!

I rather quickly posted the Powershell code I got functioning yesterday just to make sure that I didn't forget to post it at some point, but if you're new to Powershell, you might not understand everything that's going on here. If I left your head spinning, then I apologize, but tonight, I'm wrapping back around to help describe to you the thought process behind the script I posted!

On top of that, once I put together some notes from earlier today, I will post later on about some of my newest findings! To give you a teaser, I found a method of setting AMT power profiles using Powershell code! I'll be sure to get this posted as soon as I can, but for now, I think it would be most beneficial to understand the basics of connecting to a vPro system.

I'm going to step through the script line-by-line and leave some comments about each of them. Comments will be denoted by lines beginning with a pound sign (#). This is because Powershell uses this character as a "comment" character.

If you're experienced with .NET, then you'll probably either already know about, or want to get familiar with, the tool known as the .NET Reflector. This utility allows you to "reflect" over a .NET library, and discover the objects, methods, and properties that are available to you to use in your Powershell scripts. It's not always a simple task to figure out how to use .NET objects, especially if there is either poor documentation, or none at all, but this tool definitely makes it easier.

----------------------------------

# The following 6 lines are simply variables that we are setting

# to make troubleshooting and customizing our script easier.

# We will be instantiating (creating) an object of the data type

# "AmtSystem" that requires these values as params to its

# constructor method.

# This is the domain\userID we want to authenticate as

$amtusername = "vprodemo\DomainUser"

# This is the password for the user account to authenticate
$amtpassword = "P@SSW0Rd"

# This is the FQDN of the vPro client system we want to connect to
$amthostname = "vproclient.vprodemo.com"

# This is the TCP port that we want to connect to the vPro client on

# TCP 16993 is used for TLS communications to AMT clients

$amtport = 16993

# This parameter determines whether or not your password is

# saved in the AmtSystem object (I think)
$amtrecallpassword = $false

# I haven't verified this, but I believe that this parameter determines

# whether or not WS-MAN is used exclusively on vPro clients

# that support it. Otherwise, it will attempt to use EOI (SOAP).
$amtwebservicesonly = $false

# Next, this variable stores the path to the "Manageability Stack.dll"

# which is included with the Intel AMT Developer Toolkit (DTK).

# Be sure to download the latest version from the Intel website.

# This DLL is a .NET library, written in C#, that provides an API

# to interact with Intel vPro clients.

$manageabilitystack = "C:\Program Files\Intel\Manageability Developer Tool Kit\0.6.08325.2\Manageability Stack.dll"

# This line uses the built-in Assembly class (part of .NET reflection)

# to load the .NET DLL containing the AMT API. The Out-Null Powershell

# cmdlet is used to suppress any console output of the LoadFile() method.

[System.Reflection.Assembly]::LoadFile("$ManageabilityStack") | Out-Null

# The Write-Host cmdlet is built into Powershell and simply writes

# some text to the console. We are using inline variables to dynamically

# display the information about the client we're connecting to.

Write-Host "Connecting to $amthostname on port $amtport"

# This is the line that's actually getting the object that we will use to

# reference our target Intel AMT client. We are creating a global variable

# name "amtdevice" and setting its value to a "New-Object" of datatype

# ManageabilityStack.AmtSystem (you can use .NET Reflector to find this)

# and then passing the parameters that we defined before to its constructor.

# If the below line wraps in your browser, please be sure to put it all on one line in your script.

$global:amtdevice = New-Object ManageabilityStack.AmtSystem -ArgumentList $amthostname,$amtport,$amtusername,$amtpassword,$amtrecallpassword,$amtwebservicesonly

# Footnote: With respect to variable scope in Powershell, the reason I am

# defining this as a global variable explicitly, is because if you copy and paste

# this code into a script, and then run that script from within an interactive

# Powershell session, the $amtdevice will now be defined as global to the session

# and will not be deleted when the script exits. This allows you to run the script to

# retrieve the device object, but then continue to work with it interactively once

# the connection is established!

# Tell the AmtSystem object that we want to use TLS

$amtdevice.UseTls = $true

# Enable WS-MAN support (if available) on the connection
$amtdevice.WsManSupport = $true

# Once we've set up all of our configuration options about the connection,

# this next line actually establishes the connection.

$amtdevice.Connect()

# The "State" property of the AmtSystem object is "Connecting" until the

# connection either succeeds or fails. We want to monitor the status until

# this occurs.

while ($amtdevice.State -eq "Connecting") { Start-Sleep 1 }

# Finally, once the connection either succeeds or fails, we write out the

# State property to the console so that we know what the outcome was.

Write-Host "AMT device is in state $($amtdevice.State.ToString())"

-----------------------------------

So, there you have it. That is the code, with my comments inline. If you have any questions or feedback on my articles, please feel free to comment on this blog article. I will try my best to answer them, although please understand that I am still working on comprehending this great API! If this is useful to any of you, I would like to know that, and if not, then please recommend something that you would like to hear about!

As promised, I will eventually write another follow-up article on how you can set Management Engine (ME) power profiles on a provisioned AMT client remotely, using Powershell! Until next time ...

Happy Powershell Scripting!!

Trevor Sullivan

Systems Engineer

OfficeMax Corporation