Intel vPro Expert Center Blog

Finding AMT Objects in Active Directory

pcgeek86@gmail.com — Wed, 11 Nov 2009 21:03:38 GMT

If you are using Out Of Band (OOB) Management in Microsoft System Center Configuration Manager (SCCM) 2007 SP1 (or greater) to manage your Intel vPro clients, you may have noticed that computer objects are created in your Active Directory domain during provisioning of the Intel vPro firmware. These computer objects are created by the amtproxymgr component of an OOB Service Point, and allow Intel vPro to communicate directory with Active Directory, regardless of the operating system state.

Since these vPro computer objects appear very similar to standard computer objects that are created when joining a Windows OS to an AD domain, it may be hard to distinguish which ones are vPro accounts, and which ones aren't. This situation can be worsened if you somehow have Windows computer accounts mixed into the same OU that contains your AMT objects.

As you'll see below, it's very easy to locate these computers using some simple PowerShell code:

$vprosearcher = [adsisearcher]"(&(objectclass=computer)(serviceprincipalname=*:16993*)(samaccounttype=805306368))"
$vproaccounts = $vprosearcher.FindAll()

These two lines of code simply create a System.DirectoryServices.DirectorySearcher instance, with some LDAP search criteria to identify the accounts, and then assigns the results of this search to a PowerShell variable called $vproaccounts. The default search root is the top-level of your Active Directory domain, and the default search scope is already set to SubTree, so you don't have to specifically configure these settings on the DirectorySearcher. Once you're at this point, you can simply enumerate the accounts, or pipe the results into a PowerShell ForEach loop, and perform some operation against them (for example, givem them a Description attribute value).

Because this code sample uses the "adsisearcher" type accelerator (aka. type shortcut), it will only work with PowerShell v2.0 (included as part of the Windows Management Framework), unless you modify PowerShell v1.0 to include it. There's almost no reason not to be using PowerShell 2.0, now that it has been officially released, however.

I recommend using the free Quest PowerGUI tool to develop and debug PowerShell scripts.

Cheers,

Trevor Sullivan

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

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

Setting Power Policies in Windows Powershell

pcgeek86@gmail.com — Tue, 09 Dec 2008 02:03:20 GMT

Hello Intel vPro Community!

I'm going to talk to you today a little bit about how to use Windows Powershell to set Intel vPro power profiles. I'll provide a quick bit of background first on what power profiles are, and why you'd want to be able to set them with Powershell.

Intel vPro power profiles are nothing more than a setting in the Management Engine that tells the AMT chip when to be powered up, and when not to be powered up. In some cases, you may want vPro to be inactive during sleep states, or after the computer has lost power (eg. UPS failure).

In my case however, I want vPro to be always active. This is problematic, because Microsoft Configuration Manager's implementation of a provisioning server doesn't give you the option of setting the active power profile. Instead, during provisioning, ConfigMgr sets the active profile to whatever index "5" is. You'll actually see this in the amtopmgr.log file on your OOB (Out-Of-Band) service point during the provisioning process.

Because ConfigMgr decides the default power profile during provisioning, I've decided that I wanted to change it. Because Windows Powershell is an awesome automation tool, and because Intel's AMT Developer Toolkit (DTK) offers a .NET library that I can use in Powershell, I figured that I would figure out how to do it!

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

You might remember my last post on how to use Powershell to connect to an AMT device. The process basically involves loading the aforementioned .NET DLL from the DTK, and then establishing a connection to the device. I didn't really get the opportunity to show you how to do a whole lot with it after making the connection though, so that's the purpose of this post! Let's go ahead and take a look at a few lines of Powershell code, so you can understand the retrieval, and setting of power profiles.

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

# In my last Powershell script, I used the $amtdevice variable

# to reference the AmtSystem .NET object. We'll assume at this point

# that you have already connected to the AMT device based

# on my last article.

$amtdevice

# By using the .NET Reflector tool, we can see that the AmtSystem

# object has a property called SecurityAdmin, which returns an AmtSecurityAdmin

# object.

$AmtSecAdmin = $AmtDevice.SecurityAdmin

# The AmtSecurityAdmin object has a method called GetPowerPackages().

# After examining this data type in .NET Reflector, we can filter for only the two

# properties we want to see, the profile ID, and its Name. We'll use the Powershell

# Select-Object cmdlet to filter this data.

$AmtSecAdmin.GetPowerPackages() | Select-Object -Property ID,Name

# You should get some output looking something like this:

# 12834f94-10fb-dc4f-968e-1e232b0c9065 Desktop: ON in S0
# ab0086a1-7f9a-424c-a6e6-bb243a295d9e Desktop: ON in S0, S3
# acab8672-b496-e248-9b9e-9b7df91c7fd4 Desktop: ON in S0, S3, S4-5
# 4dcd327b-be6b-8943-a62a-4d7bd8dbd026 Desktop: ON in S0, ME Wake in S3
# 46732273-dc23-2f43-a98a-13d37982d855 Desktop: ON in S0, ME Wake in S3, S4-5
# baa419c5-6f6e-4d8d-b227-517f7e4595db Desktop: ON in S0, S3, S4-5, OFF After Power Loss
# ede30bd6-c504-462c-b772-d18018ee2fc4 Desktop: ON in S0, ME Wake in S3, S4-5, Off After Power Loss

# Once we have a listing of the power profiles available on the AMT device

# we can get the one that we want, and then set it. Since I always want my

# AMT device active, no matter the system's power state, I'm going to choose

# "Desktop: ON in S0, S3, S4-5" which is index 2 (in a zero-based collection).

$TargetPowerProfile = ($AmtSecAdmin.GetPowerPackages())[2]

# Now that I have a variable referencing the target power profile, I will set the

# profile on the AMT device. The AmtSecurityAdmin object has a method called

# SetActivePowerPackage() that takes one parameter: the power profile we have

# a reference to.

$AmtResult = $AmtSecAdmin.SetActivePowerPackage($TargetPowerProfile)

"Setting power profile to $($TargetPowerProfile.Name) resulted in $AmtResult!"

##### End Setting Power Profile #####

# Let's also take a quick look at how to get some basic information about

# the AMT device's provisioning data. We can figure out if IDE-R, SoL, and the

# WebUI are enabled. We'll use the AmtGeneralInfo object for this.

# Get a reference to the AmtGeneralInfo object

$AmtInfo = $amtdevice.Info

# Write out the current configuration settings

"SOL Enabled: $AmtInfo.SerialOverLanEnabled"

"IDE-R Enabled: $AmtInfo.IdeRedirectEnabled"

"WebUI Enabled: $AmtInfo.WebUiEnabled"

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

I hope this helps get you on your way to doing some cool Powershell / vPro automation! Let me know whether or not this helps you in your endeavors

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

Intel AMT, Windows Powershell, and You

pcgeek86@gmail.com — Wed, 03 Dec 2008 03:36:40 GMT

Hello everyone!

I have been working on understanding the Intel AMT Developer's Toolkit (DTK) so that I can begin developing some custom tools around Intel vPro. One of the tools that I am planning on working with is Microsoft's Windows Powershell. Windows Powershell is a very powerful, object-oriented command-line replacement for Windows XP, Vista, 2003, and 2008. It's an administrative scripting language that is significantly more powerful than VBscript, and has the entire power of the Microsoft .NET Platform behind it.

Just today, I've had my first success in using the Intel DTK with Windows Powershell, in my quest to automate Intel vPro related tasks using Powershell!

This is some really cool stuff, and I just had to get it out there to share with the community. I can't wait to see what else people build off of this!

Here is the first sample code that I've gotten to function correctly. I'm using it against a Dell Optiplex 755 running AMT firmware version 3.2.1, which was provisioned through ConfigMgr SP1.

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

$amtusername = "vprodemo\DomainUser"
$amtpassword = "P@SSW0Rd"
$amthostname = "vproclient.vprodemo.local"
$amtport = 16993
$amtrecallpassword = $false
$amtwebservicesonly = $false

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

[System.Reflection.Assembly]::LoadFile("$ManageabilityStack") | Out-Null
Write-Host "Connecting to $amthostname on port $amtport"
$amtdevice = New-Object ManageabilityStack.AmtSystem $amthostname,$amtport,$amtusername,$amtpassword,$amtrecallpassword,$amtwebservicesonly
$amtdevice.UseTls = $true
$amtdevice.WsManSupport = $true
Write-Host "TLS: $($amtdevice.UseTls), WsMan Support: $($amtdevice.WsManSupport)"
$amtdevice.Connect()

while ($amtdevice.State -eq "Connecting")
{
Start-Sleep 1
}
Write-Host "AMT device is in state $($amtdevice.State.ToString())"

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

Unfortunately that's all I can post for now, but I definitely plan on continuing work on this development!

Trevor Sullivan

Systems Engineer

OfficeMax Corporation