IPMI Plugin Usage¶

The ipmi plugin adds the ability to do multi-vendor out-of band management (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. The plugin can also create machines from their BMC presence if the feature is enabled.

Installation¶

You must install (from the Catalog), the following items:

ipmi plugin

The above items can be installed from the Catalog in the Portal, or via the following command line installation:

drpcli catalog item install ipmi

OOBM Discovery and Creation¶

Note

Autodiscovery and range scan today only supports Redfish.

This section covers the Out-of-Band Management (OOBM) discovery and creation feature in the IPMI plugin. There are two primary methods for discovering and creating machines for OOBM controllers: autodiscovery and range-scan.

Autodiscovery (From lease events)¶

Autodiscovery today is done from lease events that are generated by the DRP server when a new DHCP lease is generated.

Setup¶

In order to enable auto-discovery of OOBM controllers, the ipmi/discover/enabled and the ipmi/discover/from-lease params should be set to true on the ipmi plugin.

In addition to this you will need to provide IPMI credentials which can be used to login to these controllers. This can be done in two ways:

Using the ipmi/discover/oobm-default-credentials param which is a list of default credentials which will be used for all controllers
Using the ipmi/discover/oobm-user-provided-credentials which are credentials specific to a machine. The list uses an identifier per machine to determine what machine to try the credentials with. This identifier can be an IP address or the MAC address of the machine.

Optionally, you can also define the following params for further configuration:

ipmi/discover/parallel: The number of events that can be processed in parallel. Defaults to 200.
ipmi/discover/buffer-size: The number of events that are held in the queue at a given time. Defaults to 20000. If the number of events exceeds the queue size, they will be lost.
ipmi/discover/workflow: The workflow that needs to be set on the machine once it has been created. It defaults to universal-discover.

Process¶

The machine discovery and creation process consists of the following steps:

Ensure that a machine with the same IP address or MAC address does not already exist. If a machine is found, the process stops.
Ensure that the Redfish API is up and running and that we are able to login using the machine specific or the default credentials. We are unable to proceed without a successful login/connection.
Retrieve necessary information from the controller using redfish APIs.
Create a machine object with the retrieved information, IPMI information and the specified/default workflow.

Note

If any errors occur during this process, an error message is logged, and the process stops.

Range scan¶

The scan-range action allows you to perform a forced discovery of OOBM controllers within a specific IP range. It takes the start and end IP addresses as input and scans the list of IPs for OOBM controllers.

Setup¶

The ipmi/discover/enabled param should be set to true on the ipmi plugin.

In addition to this you will need to provide IPMI credentials which can be used to login to these controllers. This can be done in two ways:

Using the ipmi/discover/oobm-default-credentials param which is a list of default credentials which will be used for all controllers
Using the ipmi/discover/oobm-user-provided-credentials which are credentials specific to a machine. The list uses an identifier per machine to determine what machine to try the credentials with. This identifier can be an IP address or the MAC address of the machine.

Additionally, the follow params must be passed in as a part of the scan-range runaction call

ipmi/discover/scan-start-address: This parameter specifies the starting address of the scan.
ipmi/discover/scan-end-address: This parameter indicates the ending address of the scan.

The range scan will automatically generate and scan all the IPs between the start and end addresses. Please note that there is a limit of 256 addresses per range scan.

Optionally, you can also define the following parameters for further configuration:

ipmi/discover/scan-wait-for-complete: This parameter determines whether to wait for the scan to complete before returning the result. Setting it to false means the process will not wait for the scan to finish and will return an IpmiScanResult object with an ID that can be used later to track the progress. If set to true, the process will wait until the scan is completed and return an IpmiScanResult object populated with the UUIDs of the created machines and any encountered errors.
ipmi/discover/scan-timeout-minutes: This parameter, along with ipmi/discover/scan-wait-for-complete, is used to determine how long the process should wait for the scan to complete. If the scan is not finished before the timeout, the process will timeout and return an IpmiScanResult object in the current state. It will contain the ID, which can then be used to retrieve information about the scan.

Response¶

Here is an example of an immediate response, showcasing the structure of the IpmiScanResult. Pay attention to the ID field, which can be used to track the progress of the range scan. The State field indicates whether the scan is complete.

{
  "Available": true,
  "Bundle": "",
  "CreatedUuids": [],
  "Description": "",
  "Documentation": "",
  "Endpoint": "",
  "Errors": [],
  "Id": "1edfb37c-8024-6abe-b944-a510e3082bc4",
  "LowestScannedIndex": -1,
  "Meta": {},
  "Params": {},
  "ReadOnly": false,
  "ScanActionJobId": "1edfb37c-8024-6abe-b944-a510e3082bc4",
  "ScanEndAddress": "1.1.1.5",
  "ScanEndTime": "",
  "ScanErrors": [],
  "ScanStartAddress": "1.1.1.0",
  "ScanStartTime": "2023-05-25T16:07:31.581052-04:00",
  "ScanUpdatedTime": "2023-05-25T16:08:31.606942-04:00",
  "State": "running",
  "Type": "ipmi_scan_results",
  "Validated": true
}

Here is an example of a completed ipmi range scan response

{
  "Available": true,
  "Bundle": "",
  "CreatedUuids": [
    "d26a14ec-c66e-4f03-ab1b-9acd85d9a557",
    "8342786d-620c-404d-b204-af969e734c0d",
    "57edfec3-1f54-42d4-9c05-69d74a54f712",
    "898f7033-bc5f-4665-bba9-abe0599c332f"
  ],
  "Description": "",
  "Documentation": "",
  "Endpoint": "",
  "Errors": [],
  "Id": "1edfb37c-8024-6abe-b944-a510e3082bc4",
  "LowestScannedIndex": 5,
  "Meta": {},
  "Params": {},
  "ReadOnly": false,
  "ScanActionJobId": "1edfb37c-8024-6abe-b944-a510e3082bc4",
  "ScanEndAddress": "1.1.1.5",
  "ScanEndTime": "2023-05-25T16:08:31.606942-04:00",
  "ScanErrors": [
    "there was an error processing the scan for ip: 1.1.1.2 due to rpc: plugin/ipmi: error 1",
    "there was an error processing the scan for ip: 1.1.1.1 due to rpc: plugin/ipmi: error 2"
  ],
  "ScanStartAddress": "1.1.1.0",
  "ScanStartTime": "2023-05-25T16:07:31.581052-04:00",
  "ScanUpdatedTime": "2023-05-25T16:08:31.606942-04:00",
  "State": "finished",
  "Type": "ipmi_scan_results",
  "Validated": true
}

Usage¶

Beginning the scan¶

drpcli plugins runaction ipmi scan-range ipmi/discover/scan-start-address "1.1.1.0" ipmi/discover/scan-end-address "1.1.1.5"

API¶

Get all scan results from the database¶

Command line:

drpcli extended -l ipmi_scan_results list

curl:

curl -k -u username:password -X GET https://drp-endpoint/api/v3/ipmi_scan_results

Get specific scan result using the ID¶

Command line:

drpcli extended -l ipmi_scan_results show 1edfb37c-8024-6abe-b944-a510e3082bc4

curl:

curl -k -u username:password -X GET https://drp-endpoint/api/v3/ipmi_scan_results/1edfb37c-8024-6abe-b944-a510e3082bc4

Cron trigger for nightly scans¶

To automate a range scan in Digital Rebar at a specific time, you can create a cron job. This job will trigger a blueprint that initiates the batch scan on the batch of IPs provided according to the schedule you set. Here are the steps to set this up:

Create a Profile for the Range-Scan:
- Start by creating a new profile. Navigate to the "Profiles" section and click on the plus sign to create a new profile.
- Give your profile a meaningful name, such as nightly-ipmi-range-scan-batch.
- Next, add the necessary parameters to your profile:
  1. ipmi/discover/batch-scan-ips this will be your list of start and end ip pairs
  2. ipmi/discover/scan-wait-for-complete whether this will be a blocking or non-blocking task. If set to true it will wait for each scan to complete, else it will fire off the scans and be done.
  3. ipmi/discover/scan-timeout-minutes to determine how long the task should wait for the scan to complete
Clone and Modify the Blueprint:
- We have a pre-existing blueprint called ipmi-start-batch-scan that accepts the parameters you just defined and initiates a range scan. Clone this blueprint and attach the profile you created in the previous step. This will create a blueprint with the required input parameters which can we used in your cron trigger.
Create a Cron Trigger:
- Now, you need to set up a trigger for the task. Navigate to the "Triggers" section, click on the plus sign to create a new trigger.
- Name your trigger appropriately, select cron-trigger as the trigger provider, and choose the blueprint you modified in the previous step.
- Edit the filter to select the machines that this trigger will run on.
- Then, set up the cron time. You can use a resource like https://crontab.guru/ to help you configure the cron schedule.
- Finally, click "Save" to create the trigger.

Your cron trigger is now set up. It will run the batch scan task according to the cron schedule you set, automating your IP range scans.

Conducting a range-scan using the Batches framework¶

The Batches framework in Digital Rebar allows you to create a batch job for conducting range-scans on a provided list of IPs. This guide will walk you through the process.

Prerequisites:

Ensure you have machines available to run the batch job, or create a temporary cluster of machines with only the context broker.
Set up the IPMI plugin for discovery and input the necessary credentials. Refer to this section for more information.
Use the provided blueprints for this process:
- ipmi-initiate-batch-scan: Takes your IP list and spawns work orders for each start and end IP pair.
- ipmi-start-batch-scan-from-wo: Submits a scan request for each IP pair.
- process-ipmi-batch-scan-results: Waits for all scans in the batch job to complete.

Batch Object Example:

---
SetupWorkOrderTemplate:
  Blueprint: ipmi-initiate-batch-scan
  Filter: '<your filter>'
  Params:
    ipmi/discover/batch-scan-ips:
      - end_ip: 0.0.0.0
        start_ip: 0.0.0.0
    ipmi/discover/scan-wait-for-complete: false
WorkOrderTemplate:
  Blueprint: ipmi-start-batch-scan-from-wo
  Filter: '<your filter>'
PostWorkOrderTemplate:
  Blueprint: process-ipmi-batch-scan-results
  Filter: '<your filter>'

Notes:

You can create a profile as described here instead of passing in params individually
The ipmi/discover/batch-scan-ips parameter should be your list of start and end IP pairs.
The ipmi/discover/scan-wait-for-complete parameter determines whether this will be a blocking or non-blocking task. If set to true, it will wait for each scan to complete; otherwise, it will initiate the scans and finish.
The ipmi/discover/scan-timeout-minutes parameter determines how long the task should wait for the scan to complete.
You can explore all available options by looking for all parameters that start with ipmi/discovery.
After creating your batch job, click Save to start it.
The batch job follows the Setup, Work, and Post phases:
- The Setup phase creates one work order (where individual work orders are created for each IP pair).
- The Work phase creates as many work orders as there are IP pairs.
- The Post phase creates one work order that handles all the polling.
You can navigate to ux://ipmi_scan_results to see a list of range-scans that were processed

Process¶

Ensure the IP addresses are in the right format
Check that the start IP is lesser than the end IP
Iterate over the list of IPs and for each IP follow the same process as auto discovery process