Register, Heartbeat, and Shutdown an Agent

Intel AMT Features > Agent Presence > Use Cases > Register, Heartbeat, and Shutdown an Agent

Register, Heartbeat, and Shutdown an Agent

The following steps describe how to register an agent with the Intel AMT device, send a heartbeat signal, and send a shutdown signal.

The instance of AMT_AgentPresenceWatchdog used to perform these commands is uniquely defined by the DeviceID of the agent. This is the DeviceID used when the agent watchdog was created. See Create an Agent Watchdog.

1. Locally create an instance of AMT_AgentPresenceWatchdog. Set the key fields to the following values:

Parameter	Value
SystemCreationClassName	'CIM_ComputerSystem'
SystemName	'Intel(r) AMT'
CreationClassName	'AMT_AgentPresenceWatchdog'
DeviceID	DeviceID used when the agent watchdog was created, in Base 64.

2. To register an agent when it has been activated, invoke AMT_AgentPresenceWatchdog.RegisterAgent. Intel AMT responds with a SessionSequenceNumber.

Click here for a snippet demonstrating this step

You can execute this snippet by inserting it into the execution template found here.

$deviceID =# The ID of the agent watchdog in Base64 format, provided by the caller when the AMT_AgentPresenceWatchdog was created.

$agentPresenceWatchdogRef =$wsmanConnectionObject.NewReference("SELECT * FROM AMT_AgentPresenceWatchdog WHERE DeviceID='" +$deviceID +"'")

$inputObject =$agentPresenceWatchdogRef.CreateMethodInput("RegisterAgent")

$outputObject =$agentPresenceWatchdogRef.InvokeMethod($inputObject)

$returnValue =$outputObject.GetProperty("ReturnValue")

if($returnValue -like "0")

{

$sessionSequenceNumber =$outputObject.GetProperty("SessionSequenceNumber")

}

3. Increase the SessionSequenceNumber retrieved from the RegisterAgent request by 1. This prepares for sending the first heartbeat.

Click here for a snippet demonstrating this step

You can execute this snippet by inserting it into the execution template found here.

if([UInt32]$sessionSequenceNumber.ToString() -le [UInt32]::MaxValue)

{

$sessionSequenceNumberString =$sessionSequenceNumber.ToString()

$sessionSequenceNumber =[UInt32]$sessionSequenceNumberString + 1

}

else

{

$sessionSequenceNumber = 0

}

4. To send a watchdog heartbeat invoke AMT_AgentPresenceWatchdog.AssertPresence, using the increased SessionSequenceNumber.

Click here for a snippet demonstrating this step

You can execute this snippet by inserting it into the execution template found here.

$inputObject =$agentPresenceWatchdogRef.CreateMethodInput("AssertPresence")

$inputObject.SetProperty("SequenceNumber",$sessionSequenceNumber.ToString())

$outputObject =$agentPresenceWatchdogRef.InvokeMethod($inputObject)

$returnValue =$outputObject.GetProperty("ReturnValue")

5. Increase the SessionSequenceNumber by 1 to prepare for the next heartbeat.

6. To indicate a controlled shutdown, invoke AMT_AgentPresenceWatchdog.AssertShutdown, using the increased SessionSequenceNumber.

Click here for a snippet demonstrating this step

You can execute this snippet by inserting it into the execution template found here.

$inputObject =$agentPresenceWatchdogRef.CreateMethodInput("AssertShutdown")

$inputObject.SetProperty("SequenceNumber",$sessionSequenceNumber.ToString())

$outputObject =$agentPresenceWatchdogRef.InvokeMethod($inputObject)

$returnValue =$outputObject.GetProperty("ReturnValue")

Note:

• The DeviceID is the ID of the Agent watchdog in Base64 format.

• The initial SessionSequenceNumber is a random sequence number returned by Intel AMT as a response to the RegisterAgent method. This number should be incremented by one in subsequent calls. After the counter reaches its highest possible value, it is rolled to zero. The sequence number is used to enforce detection of crashed applications. The sequence number is not intended to provide any form of security for this flow.

• Re-registration of a running or expired application is allowed but may be interpreted by Intel AMT as an application that has gone through a crash/restart state. Since the state for crash/restart does not exist in the application state list, Intel AMT defines this to be a transition from “running” to “stopped” to “running.” Therefore, re-registrigation can be on a running or expired application.

Instance Diagram

Classes Used in This Flow

AMT_AgentPresenceWatchdog

SDK Sample

If there is a sample demonstrating this flow, it is included in the SDK installation file. See SDK Installation Layout for details.