22.30. ipmi - Multi-API OOB/BMC Control

The following documentation is for Multi-API OOB/BMC Control (ipmi) content package at version .

The ipmi plugin adds the ability to do multi-vendor out-of band managment (e.g. IPMI, Redfish, iDRAC, ILO, etc) actions on machines. Additionally, the plugin provides a stage, tasks, and parameters to facilitate the configuration of the BMC as part of a workflow.

Training Video: <https://www.youtube-nocookie.com/embed/Zs6KvwBvZYQ>

!!! note

To use this plugin, ipmitool needs to be installed on the DRP endpoint. The plugin will fail to load/configure if missing.

The following actions have become a loose API across all IPMI plugins.

  • poweron

  • poweroff

  • powercycle

  • nextbootpxe

  • nextbootdisk

  • identify - not implemented by all

  • powerstatus - not implemented by all

Each of these will be described more below. The actions trigger through the normal API conventions for machine actions. API access is through the /api/v3/machines/UUID/actions/ACTION POST endpoint. The drpcli actions call drpcli machines runaction UUID ACTION. Or UX as them on a dropdown in the Bulk Action section. See the other sections of documenation for action information.

The configuration / discovery stage, ipmi-configure, can be added to a workflow to at a minimum discover the machine’s BMC address, but additionally configure the BMC’s networking and a single access user. There are parameters to describe this behavior.

Each of the methods will be described below.

## Configuration / Discovery

The ipmi-configure stage when applied through a workflow can configure the BMC’s network and configure a user for out-of-band management operations. These configuration operations can be toggled on or off depending upon your environment’s needs. The user will be configured first and then the network configured.

The ipmi-configure stage will take no actions by default. The stage has three task elements. The first is a task that will make sure that the ipmitool is available and install it if missing. This is included in sledgehammer by default and no action is required. The second task element is a quirks JSON file. This defines unique variations required to address the variances in BMCs by hardware type. In general, this file does not need to be altered by the user. If a BMC miss behaves, notify RackN with the problems. The third task element is the action configuration script itself. This does the actual work and processes the quirks file as needed.

The ipmi-configure stage can be told to fail if no BMC is detected. This is help if a BMC is broken or non-operative. The ipmi/configure/no-bmc-fatal boolean set to true will cause failure in this case.

Regardless of what configuration parts the stage is allowed to do, the stage will always record the current IPMI network address associated with the BMC and store that in the ipmi/address parameter for the operational actions.

### User Configuration

The ipmi-configure stage will by default take no configuration actions. To enable user configuration, the ipmi/configure/user boolean will need to be set to true. This can be done globally, in a profile attached to a machine, or directly on the machine’s parameters.

First, the ipmi-configure task will check to see if the requested username, ipmi/configure/username, is already defined. If this is present, the userid is recorded. If the userid is not found, the ipmi-configure task will check the ipmi/configure/userid parameter to see if a specific BMC numeric userid should be used for this control user. If the userid is still not specified, a free userid will be found to user. If no userids are found, the first user id will be overwritten.

Additional checks are performed to see if the first id (2) is editable. This is not the case on some BMCs.

Once a userid is selected or discovered, the user name, password, privileges, and remote access are enabled for that user. Once all those are success at the end of the task, the username and password are recorded in the ipmi/username and ipmi/password fields respectively.

### Network Configuration

The ipmi-configure stage will by default take no configuration actions. To enable network configuration, the ipmi/configure/network boolean will need to be set to true. This can be done globally, in a profile attached to a machine, or directly on the machine’s parameters.

Once set to enabled, the first thing will be for Dell-based BMCs to have whether or not they are shared or dedicated set.

The task will then check to see if specific address is requested by seeing if the ipmi/configure/address field is set. If so and the ipmi/configure/reserve-ip is set to true, the task will create a Reservation for that IP address with the BMC’s MAC address in the DRP DHCP server. The task will fail if requested to reserve an address whith no address specified and set to static mode. This means that DRP is an IPAM and that is not currently supported.

With the reservation in place if requested, the stage will run use the ipmi/configure/ip-mode to set which mode the BMC should operate in. The options are dhcp or static. dhcp mode will enable the BMC to get an address through DHCP. This address will recorded into the ipmi/address parameter.

If the mode is static, the ipmi/configure/address, ipmi/configure/netmask, and ipmi/configure/gateway parameters are used to set the BMC’s network information.

Upon completion of everything, the current IP address will be recorded in the ipmi/address parameters and a DRP DHCP reservation will be created if the address was not specified in the ipmi/configure/address parameter and DHCP mode was set.

The overall flow of network configuration is to allow for static configuration (static mode), DHCP with an existing reservation in the DHCP server (reserve-ip set to false and dhcp mode), DHCP with a known address that becomes a static DHCP address (reserve-ip set to true, address specified in ipmi/configure/address, and dhcp mode), and DHCP without a known address that becomes statically bound in the DHCP server (reserve-ip set to true, address NOT specified in ipmi/configure/address, and dhcp mode).

## Finalization

Once configuration is finished, some BMCs need to be reset to take effect. This can take up to a minute in some cases.

### Actions

Actions are enabled on the machines by have three parameters set. Actions will not be visible upon the machines if not present. The following parameters need to be set some how. If the ipmi-configure stage is NOT used, the IPMI actions can still function if the following three parameters are applied to the machine in some manner.

Parameters:

  • ipmi/address - The IP address to access the BMC

  • ipmi/username - The username to initiate BMC actions

  • ipmi/password - The password to initiate BMC actions

Optionally, the network Port to connect to can be defined if the specific ipmi/mode driver type has been configured to use non-standard Port numbers for the given protocol. For example, if the IPMI protocol has been relocated from default UDP port 623 to 1623, use the appropriate optional Param setting below. The options are as follows:

  • (optional) ipmi/port-ipmitool - sets the network Port for the IPMI protocol

  • (optional) ipmi/port-racadm - sets the network Port for the iDRAC RACADM commands

  • (optional) ipmi/port-redfish - sets the network Port for the Redfish API service

The configuration parts of the ipmi-configure stage will set all three if enabled. Without configuration enabled, the ipmi/address field will be populated regardless if the ipmi-configure stage is applied. This enables discovery of BMC addresses for existing or already configured systems.

The ipmi/address parameter should be unique to the machine and specified directly in the machine’s parameters. The ipmi/username and ipmi/password fields may be specified directly in the machine’s parameters, in a profile attached to the machine, or global profile depending upon the scope of the username and password in the environment.

Using those three parameters, the actions will use ipmitool do the following actions. The administrator will need to make sure that the DRP Endpoint can access the BMC addresses.

All actions will return a 200 HTTP return code and a string of the ipmitool output. Upon failure, a 409 HTTP return code is returned and the error output of the ipmitool command.

#### powerstatus

This will issue chassis power status and return the results as a string.

#### poweron

This will issue chassis power on and return the results as a string.

#### poweroff

This will issue chassis power off and return the results as a string.

#### powercycle

This will issue chassis power cycle and return the results as a string.

#### nextbootpxe

This will issue chassis bootdev pxe and return the results as a string. This will be a single next boot action to boot from the network. On most systems, this is not persistent.

#### nextbootdisk

This will issue chassis bootdev disk and return the results as a string. This will be a single next boot action to boot from the disk. On most systems, this is not persistent.

#### identify

This will issue chassis identify number and return the results as a string. The number is specified by the ipmi/identify-duration parameter and defaults to 60 (seconds).

### Potential Errors

In configuring various ipmi/mode types, you may receive errors when Actions are performed. Some of those errors may include the following, along with potential reasons for the error condition.

  • (404) plugin: ipmi out: Error: Unable to establish IPMI v2 / RMCP+ session

    Typically this error may be encountered, the IPMI protocol mode has not been enabled on the Baseboard Management Controller (BMC; Dell iDRAC, HPE iLO, etc.).

22.30.1. Object Specific Documentation

22.30.1.1. params

The content package provides the following params.

22.30.1.1.1. ipmi/address

This parameter is used by the IPMI Plugin to access the BMC.

This parameter can be set manually or discovered/configured by the ipmi-configure stage.

22.30.1.1.2. ipmi/address-v4

This parameter is used by the IPMI Plugin to access the BMC.

This parameter can be set manually or discovered/configured by the ipmi-configure stage.

22.30.1.1.3. ipmi/address-v6

This parameter is used by the IPMI Plugin to access the BMC.

This parameter can be set manually or discovered/configured by the ipmi-configure stage.

22.30.1.1.4. ipmi/configure-tasks

This parameter provides a list of tasks to run during the ipmi-configure phase of execution.

This defaults to the original ipmi-configure tasks for backwards compatability.

The three phases of execution are ipmi-inventory, ipmi-configure, ipmi-install-cert.

22.30.1.1.5. ipmi/configure/address

The ipmi-configure stage will use this value to set the BMC’s address to this value.

This is required for static ip-mode configuration.

22.30.1.1.6. ipmi/configure/cert-country

The Country part of the CSR

22.30.1.1.7. ipmi/configure/cert-locality

The Locality part of the CSR

22.30.1.1.8. ipmi/configure/cert-org

The Organization part of the CSR

22.30.1.1.9. ipmi/configure/cert-org-unit

The OrganizationalUnit part of the CSR

22.30.1.1.10. ipmi/configure/cert-province

The Province part of the CSR

22.30.1.1.11. ipmi/configure/certificate

The Certificate Signing Request for this system’s BMC

22.30.1.1.12. ipmi/configure/dns-servers

List of DNS Servers for the BMC to use (overrides dns-servers)

22.30.1.1.13. ipmi/configure/domain

Domain of the hostname to apply to the BMC

22.30.1.1.14. ipmi/configure/gateway

The Gateway IP for this machine’s BMC. This will be used if set for the static ip-mode configuration.

22.30.1.1.15. ipmi/configure/generate-csr

During configuration the system should generate a CSR

22.30.1.1.16. ipmi/configure/generate-random-password

ipmi/configure/generate-random-password when set to true, the system will be build a random password for the system and will ignore the ipmi/configure/password.

The parameter, ipmi/configure/random-password-settings, will be used to scope the password generation process.

22.30.1.1.17. ipmi/configure/hostname

Hostname to apply to the BMC

22.30.1.1.18. ipmi/configure/ignore-dns-servers

Set this value to true to have the system ignore the dns-servers parameter when configure the BMC’s dns servers.

22.30.1.1.19. ipmi/configure/ignore-ntp-servers

Set this value to true to have the system ignore the ntp-servers parameter when configure the BMC’s ntp servers.

22.30.1.1.20. ipmi/configure/ip-mode

This parameter defines which method the BMC should use to get its IP address.

Valid values are:

  • dhcp (default)

  • static

22.30.1.1.21. ipmi/configure/key

The Key for the certificate to install on this system’s BMC

22.30.1.1.22. ipmi/configure/netmask

This parameter specifics the netmask to use with the ipmi/configure/address when setting the networking information in static ip-mode.

This is required for static ip-mode.

22.30.1.1.23. ipmi/configure/network

Set to true to enable the IPMI configuring of network address.

22.30.1.1.24. ipmi/configure/no-bmc-fatal

Set to true to cause a failure if the BMC doesn’t exist.

22.30.1.1.25. ipmi/configure/ntp-servers

A list of NTP Servers for the BMC to use

22.30.1.1.26. ipmi/configure/password

Password to create on the BMC for the configured user.

22.30.1.1.27. ipmi/configure/port

For Dell servers, this optional parameter will set the iDrac port mode. Many values are supported. Validated values are shared or dedicated.

22.30.1.1.28. ipmi/configure/post-csr-task

A task to inject after successful CSR generation to allow for external notification of signing service.

22.30.1.1.29. ipmi/configure/random-password-settings

This string sets values that are used to control the format random generated strings by the ipmi-passgen.py.tmpl template. This is usually used to generate a random password string with a given set of rules.

Some notes about the rules:

  • chars can not be less than the sum of upper + lower + special_chars + req_nums)

  • The padding value type will “fill out” (i.e. pad) the password with characters of the specified type, if not enough chars are generated to fill the full length

  • Allowed values for padding are:

    • lowers

    • uppers

    • nums

  • Default set of special characters is set to VMware “safe” values of:

    • [!%@$^]

  • You can override the special_char_list - however, you must be aware of the processing pipeline, as some special characters will cause Workflow errors when trying to marshal from JSON to YAML, etc.

  • You only need to override a given value to make a change to it, all remaning values not specified will use the below defaults

The default settings are as follows:

length=10, chars=7, req_nums=2, special_chars=1, special_char_list=None, upper=2, lower=5, padding=None

It is necessary that the leading and trailing character is a lowercase letter, due to internal processing. By default the passgen-settings processing will select a random character as leading and a random trailing value. You can alter this behavior and specify the exact leading and/or trailing character by setting:

  • leading_char=”z”

  • trailing_char=”a”

Note that the double quotes are required.

### Examples

To set custom values for ipmi-passgen.py.tmpl; create a Param named “ipmi/configure/random-password-settings”, add it to a Machine Object (via global profile, a custom profile applied to the given Machine, or a Param directly applied to the Machine), with the values set as below.

If a value is not specified, then the listed default (above) will be used.

Setting the length to 14 chars, all other values to default:

length=14

Set length to 12, and the list of special characters that can be used:

length=12, special_char_list=’!%@$^;,_’

To change the special characters to always generate 3 special characters, instead of the default of only 1, do:

special_chars=2

!!! note

You must put commas between multiple settings values.

22.30.1.1.30. ipmi/configure/reserve-ip

Set to true to enable the DRP to create a Reservation for the BMC’s MAC address and IP. This is the default.

Set to false to skip the creation of a Reservation for the BMC’s MAC address and IP.

22.30.1.1.31. ipmi/configure/timezone

The timezone value for the BMC to use for time presenation.

22.30.1.1.32. ipmi/configure/user

Set this value to true to have the system setup a user on the BMC

22.30.1.1.33. ipmi/configure/userid

The user id (numeric) to use for the configured user

22.30.1.1.34. ipmi/configure/username

Username to create on the BMC

22.30.1.1.35. ipmi/configure/vendor-template

A template can be provided that overrides the system configuration functions based upon the system specific vendor tools.

The template needs to start from the ipmi-any-tools.sh.tmpl and fill in the functions using the vendor specific tools. All tools need to be installed from the functions or prior to calling this.

22.30.1.1.36. ipmi/csr

The Certificate Signing Request for this system’s BMC

22.30.1.1.37. ipmi/enabled

This parameter indicates if the ipmi-configure task enabled IPMI.

22.30.1.1.38. ipmi/extra-ipmi-commands

This parameter provides a list of commands to run after ipmi-configuration is done with the ipmi-run-commands task.

This parameter defaults to an empty set of commands.

If a command needs to ignore errors, you need to add ‘|| :’ to the end of the arguments.

22.30.1.1.39. ipmi/force-lan-chan

The IPMI Lan Chan to use regardless of detection

22.30.1.1.40. ipmi/force-protocol

This parameter can be used to force a choice on IPv4 or IPv6. By default, the system will attempt to choose between IPv4 or IPv6 by the presence of a default gateway. If IPv6 has a default gateway, it will be preferred, otherwise IPv4 is prefered.

Setting this parameter will force the path. It could lead to DRP not be able to connect to the BMC.

The parameter defaults to unset.

22.30.1.1.41. ipmi/gateway

This parameter shows the current default gateway of the BMC.

22.30.1.1.42. ipmi/gateway-v4

This parameter shows the current default gateway of the BMC.

22.30.1.1.43. ipmi/gateway-v6

This parameter shows the current default gateway of the BMC.

22.30.1.1.44. ipmi/identify-duration

Duration in seconds to leave the identify light on

22.30.1.1.45. ipmi/install-cert-tasks

This parameter provides a list of tasks to run during the ipmi-install-cert phase of execution.

This defaults to the original ipmi-install-cert tasks for backwards compatability.

The three phases of execution are ipmi-inventory, ipmi-configure, ipmi-install-cert.

22.30.1.1.46. ipmi/inventory-tasks

This parameter provides a list of tasks to run during the ipmi-inventory phase of execution.

This defaults to the original ipmi-inventory tasks for backwards compatability.

The three phases of execution are ipmi-inventory, ipmi-configure, ipmi-install-cert.

22.30.1.1.47. ipmi/ipsrc

This parameter shows the method the BMC is using to configure the network.

22.30.1.1.48. ipmi/ipsrc-v4

This parameter shows the method the BMC is using to configure the network.

22.30.1.1.49. ipmi/ipsrc-v6

This parameter shows the method the BMC is using to configure the network.

22.30.1.1.50. ipmi/lpar-id

This parameter tells the ipmi plugin which LPAR to work on.

22.30.1.1.51. ipmi/macaddr

This parameter shows the MAC Address of the BMC.

22.30.1.1.52. ipmi/mode

This parameter tells the ipmi plugin which toolset to use for driving the machine. The default is: ipmitool

The options are:

  • ipmitool

  • racadm

    • racadmn is a typo that is propagated currently

  • redfish

  • lpar

    • lpar simulates ipmi control for IBM LPAR system. It requires additional parameters.

!!! note

For a given mode of operation, you must insure that protocol is enabled and supported on the platform you are attempting to execute Actions on.

22.30.1.1.53. ipmi/netmask

This parameter shows the netmask of the IP address of the BMC.

22.30.1.1.54. ipmi/netmask-v4

This parameter shows the netmask of the IP address of the BMC.

22.30.1.1.55. ipmi/netmask-v6

This parameter shows the netmask of the IP address of the BMC.

22.30.1.1.56. ipmi/password

This parameter is used by the IPMI Plugin to access the BMC

22.30.1.1.57. ipmi/port-ipmitool

This parameter is used by the IPMI Plugin to access the BMC.

The default port used by the IPMI protocol is 623. If the IPMI protocol services are relocated to a different port number, then this value needs to be updated.

22.30.1.1.58. ipmi/port-lpar

This parameter is used by the IPMI Plugin to access the BMC. The default port value is 12443.

22.30.1.1.59. ipmi/port-racadm

This parameter is used by the IPMI Plugin to access the BMC.

This parameter can be set to define the Port on which the iDRAC RACADM commands should be issued to. The default value set is 0 which means to not pass any additional Port values through to the command.

The iDRAC RACADM commands are normally issued on port 443.

22.30.1.1.60. ipmi/port-redfish

This parameter is used by the IPMI Plugin to access the BMC. The default port value is 443.

22.30.1.1.61. ipmi/quirklist

This parameter shows the method the BMC is using to configure the network.

22.30.1.1.62. ipmi/service-user

Set this value to false to skip creating a service user on the IPMI controller on this machine Set it to true to create a service user named dr-provision with a randomly generated password

22.30.1.1.63. ipmi/skip-status-validation

This parameter indicates if the ipmi-status-validation task is enabled.

This parameter defaults to true until we can get better info about how useful it is.

22.30.1.1.64. ipmi/username

This parameter is used by the IPMI Plugin to access the BMC

22.30.1.1.65. ipmi/virtual-media-boot

Should the virtual media be set to next boot

22.30.1.1.66. ipmi/virtual-media-url

URL to attach to the BMC for virtual media.

22.30.1.2. tasks

The content package provides the following tasks.

22.30.1.2.1. ipmi-configure

This task uses the ipmi.configure parameters to configure the system BMC.

The administrator may choose to configure a user, the network pieces, or both.

Defaults:

22.30.1.2.2. ipmi-discover

This task attempts to discover an BMC controller and resets it if we are known hardware.

22.30.1.2.3. ipmi-install

A task to make sure that IPMI tool is installed.

22.30.1.2.4. ipmi-install-cert-or-key

This task uses the ipmi/configure parameters to install a certificate or key or both on the system BMC.

If the parameters are not preset, nothing is done.

Defaults:

22.30.1.2.5. ipmi-inventory

This task populates the ipmi parameters for discovery from the BMC.

22.30.1.2.6. ipmi-run-commands

This task runs additional IPMI commands specified in the command list.

The command is assumed to be a full command.

If the command needs to ignore errors, you need to add ‘|| :’ to the end of the arguments.