├── README.md └── iLORESTAPI.ps1 /README.md: -------------------------------------------------------------------------------- 1 | # iLORestAPI 2 | Basic PowerShell construct for interacting with HP iLO via the RestAPI 3 | 4 | ## Synopsis 5 | 6 | Collection of functions that can be leveraged to establish session connection and interact with HP iLO RestAPI using PowerShell 7 | 8 | ## Description 9 | 10 | * **New-HpSession** 11 | * Creates an ILO session and returns the session details 12 | * **Remove-HpSession** 13 | * Closes an existing ILO session 14 | * **Get-HPSetting** 15 | * Gets settings from the HP BIOS using the ILO API 16 | * **Test-Call** 17 | * Testing function only for interacting with various iLO API URI's 18 | * **Set-HPBIOSSettings** 19 | * Makes changes to the BIOS that are specified in the JSON payload 20 | 21 | ## Prerequisites 22 | 23 | * HP Gen9 Server with iLO capability 24 | 25 | ## How to run 26 | 27 | 1. Establish an iLO session 28 | * ```powershell 29 | $session = New-HpSession -ip $ip -username $username -password $password ``` 30 | * *Note: If your workstation isn't configured to trust the iLO cert the New-HpSession will prompt you if you wish to temporarily ignore the iLO cert warning* 31 | 2. Interact with the session 32 | * ```powershell 33 | Get-HPSetting -Session $session -Config "Boot" ``` 34 | * *This will retrieve the pending BIOS settings* 35 | * ```powershell 36 | Get-HPSetting -Session $session -Config "Running" ``` 37 | * *This will retrieve the current BIOS settings* 38 | * ```powershell 39 | Test-Call -IP $ip -Session $session ``` 40 | * *This will retrieve information for the non-commented URI. This test function contains several URI examples so you can experiment with retrieving info from each one by commenting out and un-commenting different addresses* 41 | * ```powershell 42 | Set-HPBIOSSettings -IP $ip -Json $json -Session $session ``` 43 | * *This will send the specified JSON payload and make real changes to the server based on options specified in the JSON payload* 44 | 3. Remove the iLO session 45 | * ```powershell 46 | Remove-HpSession -Session $Session ``` 47 | 48 | ### Contributors 49 | 50 | Authors: Jake Morrison 51 | 52 | http://techthoughts.info 53 | 54 | ### Notes 55 | 56 | http://techthoughts.info/ilo-restful-api-powershell 57 | -------------------------------------------------------------------------------- /iLORESTAPI.ps1: -------------------------------------------------------------------------------- 1 | <# 2 | .SYNOPSIS 3 | Creates an ILO session 4 | .DESCRIPTION 5 | Creates an ILO session and returns the session details 6 | .PARAMETER ip 7 | The IP of the ILO device you are trying to establish a session to 8 | .PARAMETER username 9 | The username that will be used to authenticate for the iLO session 10 | .PARAMETER password 11 | The password that will be used to authenticate for the iLO session 12 | .EXAMPLE 13 | $session = New-HpSession -ip $ip -username $username -password $password 14 | #> 15 | function New-HpSession { 16 | param 17 | ( 18 | [Parameter(Mandatory = $true, 19 | HelpMessage = 'IP of iLO device')] 20 | [string]$ip, 21 | [Parameter(Mandatory = $true, 22 | HelpMessage = 'Username for iLO')] 23 | [string]$username, 24 | [Parameter(Mandatory = $true, 25 | HelpMessage = 'Password for iLO')] 26 | [string]$password 27 | ) 28 | # Create the JSON request to pass the ILO credentials to the API 29 | $CredentialsJson = "{ 30 | `"UserName`": `"$username`", 31 | `"Password`": `"$password`" 32 | }" 33 | 34 | $cert = $false 35 | #first attempt 36 | try { 37 | # Send the request 38 | $Script:SessionJson = Invoke-WebRequest -Uri "https://$ip/rest/v1/Sessions" -Method Post -Body $CredentialsJson -ContentType "application/json" -UseBasicParsing -ErrorAction Stop 39 | # Return the session details 40 | Return $Script:SessionJson 41 | } 42 | catch { 43 | if ($_ -like "*trust relationship*") { 44 | Write-Host "The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel." -ForegroundColor Red 45 | $choice = $null 46 | while ("yes", "no" -notcontains $choice) { 47 | $choice = Read-Host "Would you like to temp disable certificate checking for the iLO device? (yes/no)" 48 | } 49 | if ($choice -eq "yes") { 50 | # Disable certificate checking as the ILO certificate is not trusted 51 | if ([System.Net.ServicePointManager]::CertificatePolicy -ne "IDontCarePolicy") { 52 | add-type @" 53 | using System.Net; 54 | using System.Security.Cryptography.X509Certificates; 55 | 56 | public class IDontCarePolicy : ICertificatePolicy { 57 | public IDontCarePolicy() {} 58 | public bool CheckValidationResult( 59 | ServicePoint sPoint, X509Certificate cert, 60 | WebRequest wRequest, int certProb) { 61 | return true; 62 | } 63 | } 64 | "@ 65 | [System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 66 | } 67 | # Send the request to the API 68 | $Script:SessionJson = Invoke-WebRequest -Uri "https://$ip/rest/v1/Sessions" -Method Post -Body $CredentialsJson -ContentType "application/json" -UseBasicParsing 69 | } 70 | else { 71 | Write-Host "Could not establish iLO session due to Certificate verficaition errors." -ForegroundColor Magenta 72 | } 73 | } 74 | else { 75 | Write-Error $_ 76 | } 77 | } 78 | 79 | # Return the session details 80 | Return $Script:SessionJson 81 | } 82 | <# 83 | .SYNOPSIS 84 | Closes an ILO session 85 | .DESCRIPTION 86 | Closes an existing ILO session 87 | .PARAMETER Session 88 | An object representing the details of the session to close 89 | .EXAMPLE 90 | Remove-HpSession -Session $Session 91 | #> 92 | Function Remove-HpSession { 93 | Param ( 94 | [Parameter(Mandatory = $true)] 95 | [object]$Session 96 | ) 97 | 98 | # Create the auth header 99 | $AuthHeaders = @{ "X-Auth-Token" = $Session.Headers.'X-Auth-Token' } 100 | 101 | # Send the request to the API 102 | $EndSessionJson = Invoke-WebRequest -Uri $Session.Headers.Location -Method Delete -Headers $AuthHeaders -UseBasicParsing 103 | 104 | # Return the response from the API 105 | Return $EndSessionJson 106 | } 107 | <# 108 | .SYNOPSIS 109 | Gets settings from the HP BIOS 110 | .DESCRIPTION 111 | Gets settings from the HP BIOS using the ILO API 112 | .PARAMETER Config 113 | Specifies whether to retrieve the boot or running config 114 | .PARAMETER Session 115 | An object representing the details of the session to use - created by New-HpSession 116 | .PARAMETER IP 117 | Specifies the iLO IP that you are connecting to 118 | .EXAMPLE 119 | Get-HPSetting -Session $session -Config "Boot" 120 | Requires a previously established iLO session and the desired congiguration (Boot or Running) 121 | .NOTES 122 | BOOT : BIOS Pending Settings 123 | RUNNING : BIOS Current Settings 124 | #> 125 | function Get-HPSetting { 126 | param 127 | ( 128 | [Parameter(Mandatory = $true)] 129 | [ValidateSet("Boot", "Running")] 130 | [string]$Config, 131 | [Parameter(Mandatory = $true)] 132 | [object]$Session, 133 | [Parameter(Mandatory = $true)] 134 | [string]$IP 135 | ) 136 | 137 | # Create the auth header 138 | $AuthHeaders = @{ "X-Auth-Token" = $Session.Headers.'X-Auth-Token' } 139 | 140 | # Check which config needs to be retrieved and send the request as appropriate 141 | if ($Config -eq "Boot") { 142 | $BiosSettingsJson = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios/Settings" -Method Get -Headers $AuthHeaders 143 | } 144 | elseif ($Config -eq "Running") { 145 | $BiosSettingsJson = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios" -Method Get -Headers $AuthHeaders 146 | } 147 | 148 | Return $BiosSettingsJson 149 | } 150 | <# 151 | .SYNOPSIS 152 | Testing function only for interacting with various iLO API URI's 153 | .DESCRIPTION 154 | Testing function only for interacting with various iLO API URI's 155 | .PARAMETER Session 156 | An object representing the details of the session to use - created by New-HpSession 157 | .PARAMETER IP 158 | Specifies the iLO IP that you are connecting to 159 | .EXAMPLE 160 | Test-Call -IP $ip -Session $session 161 | #> 162 | function Test-Call { 163 | param 164 | ( 165 | [Parameter(Mandatory = $true)] 166 | [object]$Session, 167 | [Parameter(Mandatory = $true)] 168 | [string]$IP 169 | ) 170 | # Create the auth header 171 | $AuthHeaders = @{ "X-Auth-Token" = $session.Headers.'X-Auth-Token' } 172 | #************************************************************************************ 173 | Try { 174 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Chassis/1/PowerMetrics" -Method Get -Headers $AuthHeaders -ErrorAction Stop 175 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/systems/1" -Method Get -Headers $AuthHeaders 176 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1" -Method Get -Headers $AuthHeaders 177 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios/Settings" -Method Get -Headers $AuthHeaders 178 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios" -Method Get -Headers $AuthHeaders 179 | #$json = Invoke-WebRequest -Uri "https://$ip/rest/v1/systems/1/bios/Boot" -Method Get -Headers $AuthHeaders 180 | $json = Invoke-WebRequest -Uri "https://$ip/rest/v1/Chassis/1" -Method Get -Headers $AuthHeaders -UseBasicParsing -ErrorAction Stop 181 | } 182 | Catch { 183 | Write-Host $_ 184 | } 185 | #************************************************************************************ 186 | Return $json 187 | } 188 | <# 189 | .SYNOPSIS 190 | Posts changes to the BIOS 191 | .DESCRIPTION 192 | Makes changes to the BIOS that are specified in the JSON payload 193 | .PARAMETER Session 194 | An object representing the details of the session to use - created by New-HpSession 195 | .PARAMETER IP 196 | Specifies the iLO IP that you are connecting to 197 | .EXAMPLE 198 | Set-HPBIOSSettings -IP $ip -Json $json -Session $session 199 | .NOTES 200 | Returns a true/false if settings were succesfully changed 201 | #> 202 | Function Set-HPBIOSSettings { 203 | Param ( 204 | [Parameter(Mandatory = $true, ParameterSetName = "IP")] 205 | [string]$IP, 206 | [Parameter(Mandatory = $true)] 207 | [string]$Json, 208 | [object]$Session 209 | ) 210 | 211 | # Create the auth header 212 | $AuthHeaders = @{ "X-Auth-Token" = $Session.Headers.'X-Auth-Token' } 213 | 214 | $results = $false 215 | # Send the request to the API 216 | try { 217 | $HyperthreadingJson = Invoke-WebRequest -Uri "https://$ip/rest/v1/Systems/1/Bios/Settings" -Method Patch -Headers $AuthHeaders -Body $Json -ContentType "application/json" -ErrorAction Stop 218 | $results = $true 219 | } 220 | catch { 221 | $results = $false 222 | } 223 | return $results 224 | } 225 | ########################################################## 226 | #some examples of how to run 227 | ########################################################## 228 | <# 229 | #1. Pushing BIOS setting changes 230 | #declare the changes to be made in JSON: 231 | $noNICBootingJSON = "{ 232 | `"NicBoot1`": `"Disabled`", 233 | `"NicBoot2`": `"Disabled`", 234 | `"NicBoot3`": `"Disabled`", 235 | `"NicBoot4`": `"Disabled`", 236 | `"NicBoot5`": `"Disabled`", 237 | `"NicBoot6`": `"Disabled`" 238 | }" 239 | $ip = '172.17.0.17' #ip of iLO 240 | #get a session 241 | $session = New-HpSession -ip $ip -username username -password password 242 | Set-HPBIOSSettings -IP $ip -Json $noNICBootingJSON -Session $session 243 | Remove-HpSession -Session $session 244 | #____________________________________________ 245 | #2. Get BIOS settings 246 | $ip = '172.17.0.17' #ip of iLO 247 | #get a session 248 | $session = New-HpSession -ip $ip -username username -password password 249 | Get-HPSetting -Config Boot -Session $session -IP $ip 250 | $biosBootSettings = ConvertFrom-Json (Get-HPSetting -Session $session -Config "Boot" -IP $ip) 251 | $biosRunSettings = ConvertFrom-Json (Get-HPSetting -Session $session -Config "Running" -IP $ip) 252 | Remove-HpSession -Session $session 253 | #> 254 | ########################################################## 255 | ########################################################## --------------------------------------------------------------------------------