Module: AMT

Defined in:: lib/amt/system.rb,
lib/amt/service.rb,
lib/amt/utility.rb,
lib/amt/version.rb,
lib/amt/pt_status.rb,
lib/amt/utility/enum.rb,
lib/amt/service/basic.rb,
lib/amt/utility/bit_struct.rb,
lib/amt/service/hardware_asset.rb,
lib/amt/service/remote_control.rb,
lib/amt/service/hardware_asset/fru.rb,
lib/amt/service/hardware_asset/bios.rb,
lib/amt/service/hardware_asset/asset.rb,
lib/amt/service/network_administration.rb,
lib/amt/service/security_administration.rb,
lib/amt/service/hardware_asset/baseboard.rb,
lib/amt/service/hardware_asset/processor.rb,
lib/amt/service/remote_control/structures.rb,
lib/amt/service/hardware_asset/media_device.rb,
lib/amt/service/hardware_asset/memory_module.rb,
lib/amt/service/hardware_asset/computer_system.rb,
lib/amt/service/hardware_asset/portable_battery.rb,
lib/amt/service/network_administration/structures.rb,
lib/amt/service/security_administration/structures.rb,
lib/amt/service/hardware_asset/amt_information_table.rb,
lib/amt/service/hardware_asset/vpro_verification_table.rb

Overview

The ruby-amt library provides access to the SOAP services provided by Intel AMT devices. Before you decide whether to use the library or not, you should know the following:

The library has been designed to be used with Intel AMT 5.0 devices. This is the reason why no deprecated methods have been implemented.
Furthermore, the library has been designed to be used with Intel AMT devices in SMB mode. So SOAP methods which are only useful for devices in Enterprise Mode have not been implemented. One reason is that I don’t have access to devices in Enterprise Mode and therefore cannot test these methods.

Short Overview

The library provides a “low-level” implementation of the client side of the SOAP services (as classes in AMT::Service) as well as a class (AMT::System) for high-level access. The adjective “low-level” is not really correct since the implementation of the client side of the SOAP services is not done by generating code from WSDL files (which normally results in a direct mapping of the SOAP methods and data structures) but by hand-crafting the code and providing simple but adequate data structures.

So, although the SOAP service classes directly represent SOAP services and their methods, their usage in an application is actually quite simple. However, there are some AMT work flows which require calling more than one method or getting available states before actually setting something. This can easily be overlooked by people not acquainted with Intel AMT. Therefore there exists a class for high-level access to the AMT functionality of a system which takes this burden of you.

Library Organization

This module houses all modules/classes that are in the ruby-amt library. There are three main modules/classes:

AMT::Service: This module contains all SOAP service classes. There is a one-to-one mapping from the Intel AMT SOAP services to classes in this module. Note that not all SOAP services are implemented because some are not really useful for a management application.
AMT::Utility: This module houses utility classes that are used by other classes (mostly the service classes).
AMT::System: This is the class that can be used for high-level access to the functionality of an AMT system.

Library Usage

Direct use of SOAP Service Classes

All service classes are derived from AMT::Service::Basic and have the same initialization parameters. You need to provide at least the hostname of the AMT device, a username and a password.

You don’t need to load an individual service class, just use

require 'amt/service'

since this will automatically load any service class and any data structures that are needed on demand.

For example, the AMT::Service::RemoteControl service can be created like this:

rcs = AMT::Service::RemoteControl.new('amt.example.com', 'admin', 'P@ssw0rD')

After that you can just call the method you would like to invoke on the AMT system. But before that you should read the method description sothat you know what parameters to pass. Since the SOAP service classes are not created from WSDL files, they provide a nicer, more Ruby like interface to the SOAP methods. However, this also means that the method signature sometimes differs a little bit from the method signature as defined in the “Network Interface Guide” (which can be found in the Intel AMT SDK).

Take the AMT::Service::RemoteControl#get_system_power_state as example:

sps = rcs.get_system_power_state

Since this method takes no parameters, there is no difference in this respect. The method would nominally return a bit structure as an unsigned 32 bit integer. However, this has been changed sothat it returns an instance of AMT::Service::RemoteControl::SystemPowerState which provides easy access to the fields of the bit structure. For example:

sps.power_state         # => :s0
sps.watchdog_expired?   # => false
sps.power_source        # => :ac

Such a conversion of input or output arguments is true for all implemented methods. The special data structures needed by a service are defined in the namespace of the service. For example, all data structures needed as input or returned as output for the RemoteControl service are defined unter AMT::Service::RemoteControl.

So how does one provide input parameters? We take the AMT::Service::RemoteControl#remote_control method as example. You can learn from the method description that it has one mandatory and several optional arguments. Additionally, it is stated which type the arguments have. In its simplest form, one needs to provide just a value for the command parameter which should be an instance of AMT::Service::RemoteControl::RemoteControlCommand. Checking out the class we see that it is a subclass of AMT::Utility::Enum. This allows us to use any of the following ways to power up an AMT system which is currently powered down:

rcs.remote_control(AMT::Service::RemoteControl::RemoteControlCommand.for(:0x11))
rcs.remote_control(AMT::Service::RemoteControl::RemoteControlCommand.for(:power_up))
rcs.remote_control(0x11)
rcs.remote_control(:power_up)

As you can see, one doesn’t actually need to create an instance of the RemoteControlCommand class, one just needs to provide either a valid enumeration value or enumeration name! This is true everywhere a subclass of AMT::Utility::Enum is expected.

A simliar short-cut is available when an instance of a subclass of AMT::Utility::BitStruct is expected - see AMT::Utility::BitStruct.new !

Here is a final example with some optional parameters:

rcs.remote_control(:power_up, 343, :boot_options => [:lock_keyboard], :special_command => :pxe_boot)

High-level Interface

The high-level interface is not implemented currently.

Defined Under Namespace

Modules: Service, Utility Classes: InvocationError, PTStatus, System

Constant Summary collapse

VERSION = The version of the AMT library.

'0.1.0'