redfish

Redfish module.

exception spicerack.redfish.RedfishError[source]

Bases: SpicerackError

General errors raised by this module.

exception spicerack.redfish.RedfishTaskNotCompletedError[source]

Bases: RedfishError

Raised when a Redfish task is not found on the server.

class spicerack.redfish.ChassisResetPolicy(value)[source]

Bases: Enum

Subset of available Chassis.Reset policies compatible with all supported vendors (at this moment only Dell).

FORCE_OFF: str = 'ForceOff'

Turn off the unit immediately (nongraceful shutdown).

FORCE_RESTART: str = 'ForceRestart'

Shut down immediately and nongracefully and restart the system.

GRACEFUL_RESTART: str = 'GracefulRestart'

Shut down gracefully and power on.

GRACEFUL_SHUTDOWN: str = 'GracefulShutdown'

Shut down gracefully and power off.

ON: str = 'On'

Turn on the unit.

class spicerack.redfish.DellSCP(config: dict, target: spicerack.redfish.DellSCPTargetPolicy, *, allow_new_attributes: bool = False)[source]

Bases: object

Represent a Dell System Configuration Profile configuration as returned by Redfish API.

Parse the Redfish API response.

Parameters:

  • config (dict) -- the configuration as returned by Redfish API.

  • target (spicerack.redfish.DellSCPTargetPolicy) -- describe which sections of the configuration are represented in the loaded configuration.

  • allow_new_attributes (bool, default: False) -- when set to True it allows the creation of new attributes not already present in the provided configuration that otherwise would raise an exception. This is useful for example when changing the boot mode between Uefi and Bios that changes the keys present.

empty_components() → None[source]

Empty the current Components from the configuration, allowing to create a new configuration from scratch.

After calling this method is possible to set values for non-existing components that would otherwise raise an exception.

Return type:

None

set(component_name: str, attribute_name: str, attribute_value: str) → bool[source]

Update the current configuration setting to the new value for the given key in the given component.

Notes

This updates only the instance representation of the instance. To push and apply the changes to the server see spicerack.redfish.RedfishDell.scp_push(). In order to add attributes not present the instance must have been created with allow_new_attributes set to True or the spicerack.redfish.DellSCP.empty_component() method called. This last one allows to automatically create any missing component while setting attributes.

Parameters:

  • component_name (str) -- the name of the component the settings belongs to.

  • attribute_name (str) -- the attribute name whose value needs to be updated.

  • attribute_value (str) -- the new value for the attribute to set.

Return type:

bool

Returns:

True if the value was added or changed, False if it had already the correct value.

Raises:
update(changes: dict[str, dict[str, str]]) → bool[source]

Bulk update the current configuration with the set of changes provided.

Notes

This updates only the instance representation of the instance. To push and apply the changes to the server see spicerack.redfish.RedfishDell.scp_push().

Parameters:

changes (dict[str, dict[str, str]]) -- a dictionary of changes to apply in the same format of the one returned by spicerack.redfish.DellSCP.components().

Return type:

bool

Returns:

True if any of the values produced a change, False if no change was made.

Raises:

spicerack.redfish.RedfishError -- if unable to apply all the changes.

property comments: list[str]

Getter for the comments associated with the configuration.

property components: dict[str, dict[str, str]]

Getter for the components present in the configuration in a simplified view.

The returned dictionary where all the keys are recursively sorted and has the following format:

{
    '<component name>': {
        'key1': 'value1',
        'key2': 'value2',
    },
}
property config: dict

Getter for the whole configuration in Dell's format.

property model: str

Getter for the device Dell's model.

property service_tag: str

Getter for the device Dell's Service Tag.

property target: DellSCPTargetPolicy

Getter for the target that the current configuration represents.

property timestamp: datetime

Getter for the timestamp when the configuration dump was generated.

class spicerack.redfish.DellSCPPowerStatePolicy(value)[source]

Bases: Enum

Available Dell SCP (Server Configuration Profiles) final power state after an operation policies.

OFF: str = 'Off'

Keep the host powered off after the operation.

ON: str = 'On'

Turn the host power back on after the operation.

class spicerack.redfish.DellSCPRebootPolicy(value)[source]

Bases: Enum

Available Dell SCP (Server Configuration Profiles) reboot policies.

FORCED: str = 'Forced'

Issue an immediate hard reboot without notifying the operating system.

GRACEFUL: str = 'Graceful'

Issue a reboot notifying the operating system.

NO_REBOOT: str = 'NoReboot'

Do not reboot right now, the Redfish task will be pending the next reboot to apply the changes.

class spicerack.redfish.DellSCPTargetPolicy(value)[source]

Bases: Enum

Available sections of the Dell SCP (Server Configuration Profiles) to target.

ALL = 'ALL'

All settings.

BIOS = 'BIOS'

Only BIOS settings.

IDRAC = 'IDRAC'

Only iDRAC settings.

NIC = 'NIC'

Only network interfaces settings.

RAID = 'RAID'

Only RAID controller settings.

class spicerack.redfish.Redfish(hostname: str, interface: ipaddress.IPv4Interface | ipaddress.IPv6Interface, username: str, password: str, *, dry_run: bool = True)[source]

Bases: object

Manage Redfish operations on a specific device.

Initialize the instance.

Parameters:
change_user_password(username: str, password: str) → None[source]

Change the password for the account with the given username.

If the username matches the one used by the instance to connect to the API, automatically updates the instance value so that the instance will keep working.

Parameters:

  • username (str) -- the username to search for.

  • password (str) -- the new password to set.

Raises:

spicerack.redfish.RedfishError -- if unable to find the user or update its password.

Return type:

None

chassis_reset(action: spicerack.redfish.ChassisResetPolicy) → None[source]

Perform a reset of the chassis power status.

Parameters:

action (spicerack.redfish.ChassisResetPolicy) -- the reset policy to use.

Raises:

spicerack.redfish.RedfishError -- if unable to perform the reset.

Return type:

None

check_connection() → None[source]

Check the connection with the Redfish API.

Raises:

spicerack.redfish.RedfishError -- if unable to connect to Redfish API.

Return type:

None

find_account(username: str) → tuple[str, str][source]

Find the account for the given username and return its URI.

Parameters:

username (str) -- the username to search for.

Return type:

tuple[str, str]

Returns:

A 2-element tuple with the URI for the account and the ETag header value of the GET response.

Raises:

spicerack.redfish.RedfishError -- if unable to find the account.

force_http_boot_once() → None[source]

Force the host to boot over UEFI HTTP at the next reboot.

Raises:

spicerack.redfish.RedfishError -- if unable to perform the config change or not UEFI host.

Return type:

None

abstract get_power_state() → str[source]

Return the current power state of the device.

Return type:

str

last_reboot() → datetime.datetime[source]

Get the the last reboot time.

Return type:

datetime.datetime

static most_recent_member(members: list[dict], key: str) → dict[source]

Return the most recent member of members result from dell api.

Members will be sorted on key and the most recent value is returned. The value of key is assumed to be an iso date.

Parameters:

  • members (list[dict]) -- A list of dicts returned from the dell api.

  • key (str) -- The key to search on.

Return type:

dict

multipush_upload(file_handle: _io.BufferedReader, filename: str, reboot: bool = False) → str[source]

Upload a file via redfish and return its job_id URI.

Parameters:

  • file_handle (io.BufferedReader) -- On open file handle to the object to upload.

  • filename (str) -- filename name to use for upload.

  • reboot (bool, default: False) -- if true immediately reboot the server.

Return type:

str

poll_task(uri: str) → dict[source]

Poll a Redfish task until the results are available and return them.

Parameters:

uri (str) -- the URI of the task, usually returned as Location header by the originating API call.

Raises:

  • spicerack.redfish.RedfishError -- if the response from the server is outside the expected values of HTTP

  • 200 or 202. --

  • spicearck.redfish.RedfishTaskNotCompletedError -- if the task is not yet completed.

Return type:

dict

request(method: str, uri: str, **kwargs: Any) → requests.models.Response[source]

Perform a request against the target Redfish instance with the provided HTTP method and data.

See spicerack.apiclient.APIClient.request() for the arguments documentation.

Raises:

  • spicerack.redfish.RedfishError -- if the response status code is

  • between 400 and 600 or if the given uri does not start with a slash --

  • (/) or if the request couldn't be performed. --

Return type:

requests.models.Response

submit_files(files: dict) → str[source]

Submit a upload file request that generates a task, return the URI of the submitted task.

Parameters:

  • uri -- the relative URI to request.

  • files (dict) -- the files to upload to send in the request.

Return type:

str

submit_task(uri: str, data: dict | None = None, method: str = 'post') → str[source]

Submit a request that generates a task, return the URI of the submitted task.

Parameters:

  • uri (str) -- the relative URI to request.

  • data (typing.Optional[dict], default: None) -- the data to send in the request.

  • method (str, default: 'post') -- the HTTP method to use, if not the default one.

Return type:

str

upload_file(file_path: pathlib.Path, reboot: bool = False) → str[source]

Upload a file to the firmware directory via redfish and return the job_id URI.

Parameters:

  • file_path (pathlib.Path) -- The file path to upload.

  • reboot (bool, default: False) -- if true immediately reboot the server.

Return type:

str

wait_reboot_since(since: datetime.datetime) → None[source]

Wait for idrac/redfish to become responsive.

Parameters:

since (datetime.datetime) -- The datetime of the last reboot.

Return type:

None

property account_manager: str

Property to return the Storage manager.

property bios_version: Version

Property to return a instance representing the Bios version.

boot_mode_attribute = ''

The boot mode key in the Bios attributes.

property firmware_version: Version

Property to return a version instance representing the firmware version.

property hostname: str

Getter for the device hostname.

http_boot_target = ''

The value to the BootSourceOverrideTarget key for HTTP boot.

property interface: IPv4Interface | IPv6Interface

Getter for the management interface address with netmask.

property is_uefi: bool

Return weather the host is legacy BIOS or UEFI.

property log_entries: str

Property to return the uri for the log entries.

log_service = ''

The name of the Log service.

manager = ''

The name of the Out of Band manager.

property manufacturer: str

Property to return a string representing the model.

property model: str

Property to return a string representing the model.

property multipushuri: str

Property representing the MultipartHttpPushUri of the idrac for uploading firmwares to it.

property oob_info: dict

Property to return the oob info as a dict.

property oob_manager: str

Property to return the Out of Band manager.

property oob_model: str

Property to return a string representing the model.

property pushuri: str

Property representing the HttpPushUri of the idrac for uploading firmwares to it.

reboot_message_id = ''

The message ID for a reboot event.

property storage_manager: str

Property to return the Storage manager.

system = ''

The name of the System manager.

property system_info: dict

Property to return the system info as a dict.

property system_manager: str

Property to return the System manager.

property update_service: str

Property to return the Out of Band manager.

property updateservice_info: dict

Property to return a dict of manager metadata.

class spicerack.redfish.RedfishDell(hostname: str, interface: ipaddress.IPv4Interface | ipaddress.IPv6Interface, username: str, password: str, *, dry_run: bool = True)[source]

Bases: Redfish

Dell specific Redfish support.

Override parent's constructor.

get_power_state() → str[source]

Return the current power state of the device.

Return type:

str

scp_dump(target: spicerack.redfish.DellSCPTargetPolicy = DellSCPTargetPolicy.ALL, *, allow_new_attributes: bool = False) → spicerack.redfish.DellSCP[source]

Dump and return the SCP (Server Configuration Profiles) configuration.

Parameters:

  • target (spicerack.redfish.DellSCPTargetPolicy, default: <DellSCPTargetPolicy.ALL: 'ALL'>) -- choose which sections to dump.

  • allow_new_attributes (bool, default: False) -- when set to True it allows the creation of new attributes not already present in the retrieved configuration that otherwise would raise an exception. This is useful for example when changing the boot mode between Uefi and Bios that changes the keys present.

Raises:
Return type:

spicerack.redfish.DellSCP

scp_push(scp: spicerack.redfish.DellSCP, *, reboot: spicerack.redfish.DellSCPRebootPolicy = DellSCPRebootPolicy.NO_REBOOT, power_state: spicerack.redfish.DellSCPPowerStatePolicy = DellSCPPowerStatePolicy.ON, preview: bool = True) → dict[source]

Push the SCP (Server Configuration Profiles) configuration.

Parameters:
Return type:

dict

Returns:

The results of the push operation.

Raises:
wait_reboot_since(since: datetime.datetime) → None[source]

Wait for idrac/redfish to become responsive.

Parameters:

since (datetime.datetime) -- the datetime of the last reboot.

Return type:

None

boot_mode_attribute = 'BootMode'

The boot mode key in the Bios attributes.

property generation: int

Property representing the generation of the idrac.

This is often 13 for idrac8 and 14 for idrac9. This property allows us to add workarounds for older idrac models

http_boot_target = 'UefiHttp'

The value to the BootSourceOverrideTarget key for HTTP boot.

property log_entries: str

String representing the log entries uri.

log_service = 'Lclog'

The name of the Log service.

manager = 'iDRAC.Embedded.1'

The name of the Out of Band manager.

reboot_message_id = 'RAC0182'

The message ID for a reboot event.

scp_base_uri: str = '/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EID_674_Manager'

The Dell's SCP push base URI.

system = 'System.Embedded.1'

The name of the System manager.

class spicerack.redfish.RedfishSupermicro(hostname: str, interface: ipaddress.IPv4Interface | ipaddress.IPv6Interface, username: str, password: str, *, dry_run: bool = True)[source]

Bases: Redfish

Redfish class for SuperMicro servers.

Initialize the instance.

Parameters:
add_account(username: str, password: str, role: spicerack.redfish.RedfishUserRoles = RedfishUserRoles.ADMINISTRATOR) → None[source]

Create a new account with username and password.

Parameters:
Raises:

spicerack.redfish.RedfishError -- if unable to create the account.

Return type:

None

get_power_state() → str[source]

Return the current power state of the device.

Return type:

str

boot_mode_attribute = 'BootModeSelect'

The boot mode key in the Bios attributes.

http_boot_target = 'Pxe'

The value to the BootSourceOverrideTarget key for HTTP boot.

log_service = 'Log1'

The name of the Log service.

manager = '1'

The name of the Out of Band manager.

reboot_message_id = 'Event.1.0.SystemPowerAction'

The message ID for a reboot event.

system = '1'

The name of the System manager.

class spicerack.redfish.RedfishUserRoles(value)[source]

Bases: Enum

Allowed role values for new Redfish users.

ADMINISTRATOR = 'Administrator'

Administrator user role for Redfish.

OPERATOR = 'Operator'

Operator user role for Redfish.

READONLY = 'ReadOnly'

ReadOnly user role for Redfish.