Smart Proxy - Onboard

The Smart Proxy Onboard Plugin (smart_proxy_onboard) exposes useful API methods for the earliest part of the server lifecycle management process: onboarding new servers into Foreman.

This plugin is used for the onboarding process before server discovery. It plugs into Smart Proxy to cover the same network ranges as the Smart Proxy.

Rails DCIM Portal uses the API methods in this plugin to scan a range of IP addresses to see which ones respond to IPMI. Rails DCIM Portal then iterates over the list, finding IPMI credentials that work for each IP address. These IPMI hosts are then considered scanned and can subsequently be discovered into Foreman by PXE booting into the discovery image from foreman_discovery. Finally, while Foreman provisions the discovered hosts, Rails DCIM Portal can write inventory facts into the provisioned hosts to complete the onboarding process.

Installation

Follow the "Advanced Installation from Gems" instructions in the Foreman plugins documentation to install this plugin.

The gem name is smart_proxy_onboard.

Configuration

All configurable options for this plugin are documented at settings.d/onboard.yml.example and should be copied to /etc/foreman-proxy/settings.d/onboard.yml.

Compatible Software

This plugin is made for the following combination of software:

Features

Currently Implemented

Scan IP ranges for IPMI appliances
Clear FreeIPMI sensor data repository (SDR) cache

Planned

No additional features have been planned so far.

API

`GET /onboard/bmc/scan`

Shows available resources /onboard/bmc/scan/range and /onboard/bmc/scan/cidr

{
  "available_resources": [
    "range",
    "cidr"
  ]
}

`GET /onboard/bmc/scan/range`

Shows usage on specifying a beginning IP address and an ending IP address for making a scan request

{
  "message": "You need to supply a range with /onboard/bmc/scan/range/:address_first/:address_last"
}

`GET /onboard/bmc/scan/cidr`

Shows usage on specifying an IP address and its netmask in dot decimal format or prefixlen format for making a scan request

{
  "message": "You need to supply a CIDR with /onboard/bmc/scan/cidr/:address/:netmask (e.g. \"192.168.1.1/24\" or \"192.168.1.1/255.255.255.0\")"
}

`GET /onboard/bmc/scan/range/:address_first/:address_last`

Performs an IPMI ping scan from :address_first to :address_last and returns the result in key "result" of a JSON hash

Sample output for /onboard/bmc/scan/range/10.246.0.65/10.246.0.71:

{
  "result": [
    "10.246.0.65",
    "10.246.0.69",
    "10.246.0.70",
    "10.246.0.66",
    "10.246.0.68",
    "10.246.0.71",
    "10.246.0.67"
  ]
}

`GET /onboard/bmc/scan/cidr/:address/:netmask`

Performs an IPMI ping scan in the CIDR range of :address/:netmask, where :netmask is in decimal format (e.g. "255.255.255.0") or in prefixlen format (e.g. "24")

Sample output for /onboard/bmc/scan/cidr/10.246.0.65/29:

{
  "result": [
    "10.246.0.69",
    "10.246.0.70",
    "10.246.0.65",
    "10.246.0.66",
    "10.246.0.67",
    "10.246.0.68",
    "10.246.0.71"
  ]
}

`DELETE /onboard/bmc/sdr_cache`

(FreeIPMI only) Deletes the sensor data repository (SDR) cache from the Smart Proxy. This is useful when you run something like GET /bmc/10.246.0.69/fru/list with bmc_provider=freeipmi and you get a reply like this:

{
  "action": "list",
  "result": {
    "": {
      "sdr_cache_'/tmp/.freeipmi-foreman-proxy/.freeipmi/sdr-cache/sdr-cache-smartproxyhostname.10.246.0.69'_invalid": "Please flush the cache and regenerate it"
    }
  }
}

Instead of manually logging in to the Smart Proxy and deleting /tmp/.freeipmi-foreman-proxy/.freeipmi/sdr-cache, just run this method, and you'll get this reply:

{
  "result": true,
  "message": "SDR cache deleted"
}

If there's no SDR cache present, you'll see:

{
  "result": true,
  "message": "No SDR cache to delete"
}

If the deletion failed, you'll see something like this:

{
  "errors": [
    "Permission denied @ dir_s_rmdir - /tmp/.freeipmi-foreman-proxy/.freeipmi/sdr-cache"
  ],
  "result": false,
  "message": "Failed to delete one or more SDR cache location candidates"
}

As long as {"result":true}, you will not encounter the sdr_cache_…_invalid error next time.