Using PowerShell to manage HP servers via the iLO RESTful API

If your environment contains HPE Gen9 Servers running iLO 4 2.00 you can leverage PowerShell to interact with the iLO RESTful API of these devices.

Why should I care about using PowerShell to access the iLO RESTful API?

By using some basic PowerShell commands you can perform anything you could do in a normal iLO session via the shell.  There are a lot of possibilities!  Here a few potential use cases:

• Audit the BIOS settings of every device in your environment to ensure that every BIOS settings meets your specifications
• Update the Administrator BIOS password on every device
• Update iLO user account settings fleet-wide
• Push pre-determined BIOS configuration to 20 newly deployed devices

Using PowerShell to interact with the iLO RESTful API

If you prefer video format over written documentation I provide a brief demo of using PowerShell to interface with the iLO API in the following Techthoughts video:

For this topic I’m going to assume some basic familiarity with the following:

• Invoke-WebRequest cmdlet
• HTTP operations and RESTful web service APIs
• JSON and JSON payloads
• HTTP operations and headers

Even if you don’t have a lot of insight into any of those topics you can still establish a basic session and begin interacting with the iLO RESTful API by following this guide.  To tailor these base examples to meet the needs of your unique environment however, you will need to read up on these topics.

Start with obtaining iLORESTAPI.ps1 from the TechThoughts GitHub:

https://github.com/techthoughts2/iLORestAPI

Not sure how to use GitHub?  No worries, once you’re there just click on the Clone or Download button and click Download Zip:

The iLORESTAPI.ps1 script contains several base functions to get you started with establishing an iLO session and interacting with the iLO API:

New-HpSession       - Creates an ILO session and returns the session details
Remove-HpSession    - Closes an existing ILO session
Get-HPSetting       - Gets settings from the HP BIOS using the ILO API
Test-Call           - Testing function for interacting with various iLO API URI's
Set-HPBIOSSettings  - Makes CHANGES to BIOS that are specified in JSON payload

Start by first gathering the following:

• IP of the iLO you will be connecting to
• Username that has access to the iLO device
• Password for the user identified

Armed with this information we can begin by creating a session to the iLO RESTful API:

$ip = "172.16.96.55"
$username = "UserName"
$password = "P@$$w0rd"
$session = New-HpSession -ip $ip -username $username -password $password

$session now contains an established session to the iLO device – provided that your username/password is authorized.

Note: If your workstation isn’t configured to trust the iLO certificate the New-HpSession will prompt to see if you wish to temporarily ignore the iLO cert warning

With a good session established you can now begin interacting with the iLO API!

$biosBootSettings = ConvertFrom-Json (Get-HPSetting -Session $session -Config "Boot" -IP $ip)
$biosRunSettings = ConvertFrom-Json (Get-HPSetting -Session $session -Config "Running" -IP $ip)

HP Gen9 servers are equipped with a dual state BIOS.  The above functions will retrieve both the pending (Boot) and current (running) BIOS settings.

What other information can you retrieve in this fashion? Lots!

Use the Test-Call function and play around with the various available URI’s:

Try {
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Chassis/1/PowerMetrics" -Method Get -Headers $AuthHeaders -ErrorAction Stop
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/systems/1" -Method Get -Headers $AuthHeaders
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1" -Method Get -Headers $AuthHeaders
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios/Settings" -Method Get -Headers $AuthHeaders
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios" -Method Get -Headers $AuthHeaders
    #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/systems/1/bios/Boot" -Method Get -Headers $AuthHeaders
    $json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Chassis/1" -Method Get -Headers $AuthHeaders -UseBasicParsing -ErrorAction Stop
}
Catch {
    Write-Host $_
}
#************************************************************************************
Return $json

Note that in the Test-Call function you can comment and un-comment several different URI examples.  Each contains different information so you can play around with this and then execute the function as follows:

$test = ConvertFrom-Json (Test-Call -Session $session -IP $ip)

Leveraging the API in this fashion you can pull in a lot of data about the server and the server’s configuration.

The iLO API also permits changes to be specified.

The ability to make sweeping server configurations to your environment using PowerShell and the iLO API will likely save you a lot of time and potential mistakes.  You should definitely utilize this functionality but you are hereby cautioned that you could cause significant damage if not careful.

To have the iLO API execute changes to the server you simply pass it a JSON payload that contains the desired changes to the correct resource URI.

That sounds a little complicated, but it’s relatively straightforward.

Configuring the JSON payload can be a little tricky but this can be simplified by first pulling in the data to see what available options you have.

In the above example I demonstrated how to pull in the BIOS settings of a server.  A view of that return indicates the following:

NicBoot1               : NetworkBoot
NicBoot2               : NetworkBoot
NicBoot3               : NetworkBoot
NicBoot4               : NetworkBoot

So, all the network ports are set to NetworkBoot which means each will try to PXE – adding a good chunk of time to a server reboot.  Do I need this?  Not at all, so lets save some time by disabling this setting:

First specify the JSON payload:

$noNICBootingJSON = "{
    `"NicBoot1`": `"Disabled`",
    `"NicBoot2`": `"Disabled`",
    `"NicBoot3`": `"Disabled`",
    `"NicBoot4`": `"Disabled`"
}"

Not sure on the specifics of the JSON payload settings?  Hit up the Additional Reading section at the bottom of this article to see if you can find a specific setting example.

With the JSON payload constructed you can push it using the Set-HPBIOSSettings function:

Set-HPBIOSSettings -IP $ip -Json $noNICBootingJSON -Session $session

This will change all four NICs to not attempt network boot in the BOOT section of the BIOS.  This is the pending portion of the HP BIOS and the changes won’t take effect until a reboot is accomplished at which point the setting will enter the RUNNING portion of the BIOS.

Push changes to the iLO API are not limited to simple BIOS configurations, there are a wide variety of settings that you can change using PowerShell.

The Set-HPBIOSSettings function is set to push changes to the following resource URI:

https://$ip/rest/v1/Systems/1/Bios/Settings

Depending on what changes you are trying to make you will need to push your changes to a different resource URI that contains the settings you are attempting to change.

The above examples will get you started with establishing a basic session, interacting with the URI, and even pushing basic BIOS setting changes.  To further customize and use PowerShell to address your environments unique needs through the iLO RESTful API take a look at the links below:

Additional Reading

• Managing Hewlett Packard Enterprise Servers Using the RESTful API
• iLO API Data Model Reference (iLO 4)
• Tips for Using the RESTful API
• PowerShell-ProLiant-SDK
• iLO API Forum