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