22.28. ipmi - Multi-API OOB/BMC Control

The following documentation is for Multi-API OOB/BMC Control (ipmi) content package at version v4.8.0-alpha00.23+g0d8d59e518bbf87d75d8b1d2b105750e54b3edbb.

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://youtu.be/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.

22.28.1. 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 thid 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.

22.28.1.1. 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.

22.28.1.2. 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).

22.28.1.3. Finalization

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

22.28.2. 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 paramters, 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.

22.28.2.1. powerstatus

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

22.28.2.2. poweron

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

22.28.2.3. poweroff

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

22.28.2.4. powercycle

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

22.28.2.5. 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.

22.28.2.6. 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.

22.28.2.7. 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).

22.28.2.8. 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.28.3. Object Specific Documentation

22.28.3.1. tasks

The content package provides the following tasks.

22.28.3.1.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:
ipmi/configure/address = unset ipmi/configure/gateway = unset ipmi/configure/ip-mode = dhcp ipmi/configure/netmask = unset ipmi/configure/network = false ipmi/configure/no-bmc-fatal = false ipmi/configure/reserve-ip = true ipmi/configure/port = unset ipmi/configure/user = false ipmi/configure/username = root ipmi/configure/password = cr0wBar! ipmi/configure/userid = unset

22.28.3.1.2. ipmi-discover

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

22.28.3.1.3. ipmi-install

A task to make sure that IPMI tool is installed.

22.28.3.1.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:
ipmi/configure/certificate = unset ipmi/configure/key = unset

22.28.3.1.5. ipmi-inventory

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

22.28.3.1.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.

22.28.3.2. params

The content package provides the following params.

22.28.3.2.1. ipmi/configure/hostname

Hostname to apply to the BMC

22.28.3.2.2. ipmi/configure/password

Password to create on the BMC for the configured user.

22.28.3.2.3. ipmi/configure/timezone

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

22.28.3.2.4. ipmi/csr

The Certificate Signing Request for this system’s BMC

22.28.3.2.5. ipmi/force-lan-chan

The IPMI Lan Chan to use regardless of detection

22.28.3.2.6. ipmi/netmask-v4

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

22.28.3.2.7. 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.28.3.2.8. ipmi/configure/certificate

The Certificate Signing Request for this system’s BMC

22.28.3.2.9. ipmi/port-redfish

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

22.28.3.2.10. 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.28.3.2.11. 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.28.3.2.12. ipmi/ipsrc-v4

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

22.28.3.2.13. ipmi/ipsrc-v6

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

22.28.3.2.14. 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.28.3.2.15. 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.28.3.2.16. ipmi/configure/cert-country

The Country part of the CSR

22.28.3.2.17. ipmi/port-lpar

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

22.28.3.2.18. ipmi/virtual-media-boot

Should the virtual media be set to next boot

22.28.3.2.19. ipmi/configure/cert-locality

The Locality part of the CSR

22.28.3.2.20. 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
  • redfish
  • lpar
  • racadmn is a typo that is propagated currently
  • 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.28.3.2.21. ipmi/configure/gateway

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

22.28.3.2.22. 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.28.3.2.23. 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.28.3.2.24. ipmi/password

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

22.28.3.2.25. ipmi/gateway

This parameter shows the current default gateway of the BMC.

22.28.3.2.26. 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.28.3.2.27. ipmi/configure/username

Username to create on the BMC

22.28.3.2.28. ipmi/configure/cert-province

The Province part of the CSR

22.28.3.2.29. ipmi/configure/generate-csr

During configuration the system should generate a CSR

22.28.3.2.30. 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.28.3.2.31. ipmi/configure/post-csr-task

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

22.28.3.2.32. ipmi/lpar-id

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

22.28.3.2.33. ipmi/gateway-v6

This parameter shows the current default gateway of the BMC.

22.28.3.2.34. ipmi/virtual-media-url

URL to attach to the BMC for virtual media.

22.28.3.2.35. 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.28.3.2.36. 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.28.3.2.37. ipmi/configure/userid

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

22.28.3.2.38. 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.28.3.2.39. ipmi/configure/key

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

22.28.3.2.40. 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.28.3.2.41. ipmi/netmask-v6

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

22.28.3.2.42. ipmi/gateway-v4

This parameter shows the current default gateway of the BMC.

22.28.3.2.43. ipmi/configure/cert-org-unit

The OrganizationalUnit part of the CSR

22.28.3.2.44. 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.28.3.2.45. ipmi/netmask

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

22.28.3.2.46. 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.28.3.2.47. 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.28.3.2.48. ipmi/enabled

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

22.28.3.2.49. ipmi/macaddr

This parameter shows the MAC Address of the BMC.

22.28.3.2.50. ipmi/identify-duration

Duration in seconds to leave the identify light on

22.28.3.2.51. ipmi/username

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

22.28.3.2.52. ipmi/configure/no-bmc-fatal

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

22.28.3.2.53. ipmi/configure/ntp-servers

A list of NTP Servers for the BMC to use

22.28.3.2.54. ipmi/configure/user

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

22.28.3.2.55. ipmi/configure/cert-org

The Organization part of the CSR

22.28.3.2.56. ipmi/configure/network

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

22.28.3.2.57. ipmi/ipsrc

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

22.28.3.2.58. ipmi/configure/dns-servers

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

22.28.3.2.59. ipmi/configure/domain

Domain of the hostname to apply to the BMC