Skip to content

Using the RESTful Interface Tool

Getting started with iLOrest

The first action to perform before being able to use iLOrest, is to open a Redfish session in a remote iLO (out-of-band management) or, in the local iLO (in-band management). Refer to the generic Redfish authentication methods as well as the login global command for more details.

As mentioned in this blog post, the Redfish® data model is based upon schemas. The HPE iLOrest Redfish client also uses schemas to get or set properties in the Redfish tree. Schemas are referenced as data types, types or selectors in the iLOrest terminology.

To manage a single property, you need first to identify and select its data type (schema file).

The exhaustive list of schemas (selectors) can be retrieved with the types atomic command as shown in the following example.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest types
ilorest logout

If you don't know which schema describes the property you want to manage, follow this method:

  1. Try to identify a schema name close to the property. If the property belongs to the storage subsystem, look for all selectors having "storage" in their name. Here are few example performed against an iLO 6 based system.

    Storage: controllers, drives, logical volumes

ilorest login <ilo-ip> -u <ilo-username> -p password
ilorest types | grep -i -E "storage|drive|volume"
ilorest logout

Thermal: Fans, temperature

ilorest login <ilo-ip> -u <ilo-username> -p password
ilorest types | grep -i thermal
ilorest logout
TIP

For each iLO firmware, you can browse the types from the resource map .

  1. If the above method fails, enter the property string in the search box of this portal (top right corner). In the proposed list, select a section mentioning "Resource Definition". The type is displayed after string "Member of".

    As an example, if you want to view the firmware version of the iLO, type "FirmwareVersion" in the search box and click on "Manager resource definitions > FirmwareVersion". This displays the iLO's FirmwareVersion property, part of the Manager.v schema.

  2. Select the found schema to manage your property.

    ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest select Manager.

ilorest select
Current selection: Manager.v1_5_1

ilorest get FirmwareVersion
FirmwareVersion=iLO 6 v1.59
    TIP

    iLOrest can select multiple types at once.

    The above example appends a . character to the selected type to avoid selecting the other types starting with string Manager like: ManagerCollection, ManagerAccount, etc.

HPE iLOrest operation modes

HPE iLOrest has three modes of operation. By default, the interactive mode is started when you launch it. With the scriptable mode, you can use a script that calls the program followed by commands and arguments. The file-based mode allows you to use a script that calls the program followed by commands, arguments file(s) to load or save settings.

In addition HPE iLOrest provides a debug mode very helpful for learning and troubleshooting.

Interactive mode

Interactive mode is started when you run the RESTful Interface Tool without any command-line parameters. An ilorest > prompt is displayed and you can enter commands one at a time. Interactive mode provides immediate feedback for an entered command. You can also use this mode to validate a script.

Use the following instructions to start an interactive session on the different operating systems:

  • Microsoft Windows: Go to C:\Program Files\Hewlett Packard Enterprise\RESTful Interface Tool and double-click ilorest.exe. You must be an administrator to run ilorest.exe.
  • Linux and Ubuntu: Enter the following command : /usr/sbin/ilorest
  • MAC: Enter the following command as administrator: /Applications/ilorest
  • VMware ESXi 7.0: Enter the following command as administrator: /opt/tools/ilorest
  • VMware ESXi 8.0: Enter the following command as administrator: /opt/ilorest/bin/ilorest.sh
NOTE

In ESXi 7.0/8.0, HPE iLOrest is integrated with the esxcli utility

Here are some Examples:

esxcli ilorest cmd -q login
esxcli ilorest cmd -q types
esxcli ilorest cmd -q "select Bios."
esxcli ilorest cmd -q logout
esxcli ilorest help
esxcli ilorest debug -q login
esxcli ilorest debug -q logout

Use the exit command at the prompt to exit from the interactive mode.

Interactive Mode

Tab command completion

Tab command completion is available for interactive mode in multiple capacities. See the features below.

Completing commands

Tab command completion is available for viewing and completing commands.

Tab complete commands

Completing types

Redfish resources and properties are associated to a data type also called resource type or just type. To view or modify a resource, you must first select its type.

TIP

Resource types are listed in the resource map section of the iLO Redfish reference document.

Tab command completion is also available for viewing and completing types.

  • You must be logged in a remote or local managed server.

Tab complete types

Completing properties and sub-properties

Tab command completion is also available for viewing and completing properties.

  • You must be logged in and have a type selected.
  • Also available for set and list commands.

Tab complete props

Completing schema properties information

Tab command completion can also show schema information for properties.

  • You must be logged in and have a type selected
  • Also available for set and list

Tab complete schema

Scriptable mode

You can use the scriptable mode to script all the commands using an external input file. The script contains a list of HPE iLOrest command lines that let users get and set properties of server objects.

The following example retrieves information regarding the Bios type:

:: This is a batch file that logs into a remote server,
:: selects the Bios type, and gets the BootMode value

:: Usage ::
:: selectget.bat [URI] [USERNAME] [PASSWORD]
@echo off

set argC=0
for %%x in (%*) do Set /A argC+=1
if %argC% LSS 3 goto :failCondition
goto :main

:failCondition
@echo Usage:
@echo selectget.bat [URI] [USERNAME] [PASSWORD]
goto :EOF

:main
@echo *****************************************
@echo ************* Logging in... *************
@echo *****************************************
ilorest.exe login %1 -u %2 -p %3
@echo *****************************************
@echo ******* selecting Bios type... ********
@echo *****************************************
ilorest.exe select Bios.
@echo *****************************************
@echo ********** getting BootMode... **********
@echo *****************************************
ilorest.exe get BootMode
pause

File-based mode

File-based mode allows you to save and load settings from a file. This is similar to the conrep.dat files used by CONREP. File-based mode supports the JSON format.

The following script allows you to save, edit, and load a file to the server.

The resources and properties of the Bios type is saved to a file called ilorest1.json. Then, after you modify any properties, the load command is used to make these changes on the server. Changes to read-only values are not reflected.

:: This is a file-based edit mode helper for RESTful Interface Tool
:: 1. Run to download selected type to a file called ilorest.json
:: 2. Edit the ilorest.json file to make changes.
:: 3. Press any key running batch program to continue with program,
::    uploading the newly edited program to the server.

:: Usage ::
:: saveload.bat [SELECTOR] [FILENAME]
:: Specify a type with the SELECTOR tag, and
:: save to a file called FILENAME
@echo off
set argC=0
for %%x in (%*) do Set /A argC+=1
if %argC% LSS 2 goto :failCondition
goto :main

:failCondition
@echo Usage:
@echo saveload.bat [SELECTOR] [FILENAME]
@echo specify a type with the SELECTOR tag, and
@echo save to a file called FILENAME
goto :EOF

:main
ilorest.exe login
ilorest.exe save --selector=%1 --json -f %2
@echo Edit the file, then:
pause
ilorest.exe load -f %2

When the example script is run, the following output is produced:

File Mode example

Atomic, macro commands and raw commands

HPE iLOrest provides three types of commands:

  1. Atomic commands also referred as global commands. The most common are select, get, set and commit. They are mostly used to manage individual properties or resources.
  2. Macro commands used to manage groups of resources or perform complex actions involving several properties. BIOS, iLO, and Storage controller commands are just a few examples.
  3. Raw commands: They are the equivalent of HTTP PATCH, GET, POST, PUT, DELETE, and HEAD requests.

Executing commands in parallel

HPE iLOrest uses a caching method to locally save servers' data. To send HPE iLOrest commands to many different remotely systems at once, you need to specify a different cache directory for each of them. The following example uses clush, the ClusterShell, but any method of parallel scripting will work as long as you specify different cache directories.

The following example executes clush commands to start HPE iLOrest sessions against ten different iLO based servers. Each session is composed of the login, a chassis serial number retrieval and the logout.

For each session, HPE iLOrest saves cached data in a different location: server1 data is cached in directory ilo-server1, server2 data is cached in directory ilo-server2....

The --nostdin parameter tells clush not to wait for standard inputs. The --worker=exec parameter executes the HPE iLOrest local executable. The -w server[1-10] part of the example replaces the string %h in the rest of the command with 1, 2, ..., 10.

clush --nostdin --worker=exec -w 'server[1-10]' ilorest --cache-dir=ilo-%h login ilo-%h -u ilo-user -p password
clush --nostdin --worker=exec -w 'server[1-10]' ilorest --cache-dir=ilo-%h get --json SerialNumber --selector Chassis.
clush --nostdin --worker=exec -w 'server[1-10]' ilorest --cache-dir=ilo-%h logout

Running HPE iLOrest against multiple managed systems can also be done using automation tools such as Ansible, Chef, and Puppet.

Configuration file

The HPE iLOrest configuration file (redfish.conf) contains the default settings for the tool. You can use a text editor to change the behavior of the tool such as adding a server IP address, username, and password. The settings that you add or update in the configuration file are automatically loaded each time you start the tool.

Configuration file locations (only present for Windows/Linux/Ubuntu OS):

  • Windows OS: The same location as the ilorest.exe executable.
  • Linux/Ubuntu OS: /etc/ilorest/redfish.conf
[ilorest]
#iLOrest reads the following environment variables, and applies them at runtime.  
#Note that they can be overridden by command line switches.

#####          Log Settings          #####
##########################################
# directory where iLOrest writes its log file
# logdir = .\ilorest_logs

#####         Cache Settings         #####
##########################################
# option to disable caching of all data
# cache = False

#####       Credential Settings      #####
##########################################
# option to use the provided url to login
# url = https://127.0.0.1

# option to use the provided username to login
# username = admin

# option to use the provided password to login
# password = password

# option to use the provided SSL certificate or certificate bundle for HTTPS validation
#sslcert = .\

#####         Commit Settings        #####
##########################################
# flag to commit in all places where applicable
# commit = True

#####    Output Default Settings     #####
##########################################
# flag to change output format in all places where applicable
# format = json

#####    Schema Default Settings     #####
##########################################
# directory where iLOrest will look for ilo schemas
# iloschemadir = .\

# directory where iLOrest will look for bios schemas
# biosschemadir = .\

#####  Default Save/Load Settings    #####
##########################################
# option to set default save output file
# savefile = ilorest.json

# option to set default load input file
# loadfile = ilorest.json
Previous page
Next page