community.general.redfish_command module – Manages Out-Of-Band controllers using Redfish APIs

Note

This module is part of the community.general collection (version 10.7.5).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.redfish_command.

Synopsis

• Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action.

• Manages OOB controller ex. reboot, log management.

• Manages OOB controller users ex. add, remove, update.

• Manages system power ex. on, off, graceful and forced reboot.

Parameters

Parameter	Comments
account_properties dictionary added in community.general 0.2.0	Properties of account service to update. Default: {}
account_types aliases: account_accounttypes list / elements=string added in community.general 7.2.0	Array of account types to apply to a user account.
auth_token string added in community.general 2.3.0	Security token for authenticating to OOB controller.
baseuri string / required	Base URI of OOB controller.
bios_attributes dictionary added in community.general 6.4.0	BIOS attributes that needs to be verified in the given server.
boot_next string	BootNext target when bootdevice is “UefiBootNext”.
boot_override_mode string added in community.general 3.5.0	Boot mode when using an override. Choices: "Legacy" "UEFI"
bootdevice string	Boot device when setting boot configuration.
ca_path path added in community.general 10.6.0	PEM formatted file that contains a CA certificate to be used for validation. Only used if validate_certs=true.
category string / required	Category to execute on OOB controller.
ciphers list / elements=string added in community.general 9.2.0	TLS/SSL Ciphers to use for the request. When a list is provided, all ciphers are joined in order with :. See the OpenSSL Cipher List Format for more details. The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
command list / elements=string / required	List of commands to execute on OOB controller.
id aliases: account_id string	ID of account to delete/modify. Can also be used in account creation to work around vendor issues where the ID of the new user is required in the POST request.
new_password aliases: account_password string	New password of account to add/modify.
new_username aliases: account_username string	Username of account to add/delete/modify.
oem_account_types aliases: account_oemaccounttypes list / elements=string added in community.general 7.2.0	Array of OEM account types to apply to a user account.
password string	Password for authenticating to OOB controller.
reset_to_defaults_mode string added in community.general 8.6.0	Mode to apply when reseting to default. Choices: "ResetAll" "PreserveNetworkAndUsers" "PreserveNetwork"
resource_id string added in community.general 0.2.0	ID of the System, Manager or Chassis to modify.
roleid aliases: account_roleid string	Role of account to add/modify.
session_uri string added in community.general 2.3.0	URI of the session resource.
strip_etag_quotes boolean added in community.general 3.7.0	Removes surrounding quotes of etag used in If-Match header of PATCH requests. Only use this option to resolve bad vendor implementation where If-Match only matches the unquoted etag string. Choices: false ← (default) true
timeout integer	Timeout in seconds for HTTP requests to OOB controller. The default value for this parameter changed from 10 to 60 in community.general 9.0.0. Default: 60
uefi_target string	UEFI boot target when bootdevice is “UefiTarget”.
update_apply_time string added in community.general 6.1.0	Time when to apply the update. Choices: "Immediate" "OnReset" "AtMaintenanceWindowStart" "InMaintenanceWindowOnReset" "OnStartUpdateRequest"
update_creds dictionary added in community.general 0.2.0	Credentials for retrieving the update image.
password string	Password for retrieving the update image.
username string	Username for retrieving the update image.
update_custom_oem_header string added in community.general 10.1.0	Optional OEM header, sent as separate form-data for the Multipart HTTP push update. The header shall start with “Oem” according to DMTF Redfish spec 12.6.2.2. For more details, see https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.21.0.html. If set, then update_custom_oem_params is required too.
update_custom_oem_mime_type string added in community.general 10.1.0	MIME Type for custom OEM properties for HTTP Multipart Push updates.
update_custom_oem_params any added in community.general 10.1.0	Custom OEM properties for HTTP Multipart Push updates. If set, then update_custom_oem_header is required too. The properties are passed raw without any validation or conversion by Ansible. This means the content can be a file, a string, or any other data. If the content is a dictionary that should be converted to JSON, then the content must be converted to JSON before passing it to this module using the ansible.builtin.to_json filter.
update_handle string added in community.general 6.1.0	Handle to check the status of an update in progress.
update_image_file path added in community.general 7.1.0	Filename, with optional path, of the image for the update.
update_image_uri string added in community.general 0.2.0	URI of the image for the update.
update_oem_params dictionary added in community.general 7.5.0	Properties for HTTP Multipart Push Updates.
update_protocol string added in community.general 0.2.0	Protocol for the update.
update_targets list / elements=string added in community.general 0.2.0	List of target resource URIs to apply the update to. Default: []
update_username aliases: account_updatename string added in community.general 0.2.0	New user name for updating account_username.
username string	Username for authenticating to OOB controller.
validate_certs boolean added in community.general 10.6.0	If false, TLS/SSL certificates will not be validated. Set this to true to enable certificate checking. Should be used together with ca_path. Choices: false ← (default) true
virtual_media dictionary added in community.general 0.2.0	Options for VirtualMedia commands.
image_url string	URL of the image to insert or eject.
inserted boolean	Indicates that the image is treated as inserted on command completion. Choices: false true ← (default)
media_types list / elements=string	List of media types appropriate for the image. Default: []
password string	Password for accessing the image URL.
transfer_method string	Transfer method to use with the image.
transfer_protocol_type string	Network protocol to use with the image.
username string	Username for accessing the image URL.
write_protected boolean	Indicates that the media is treated as write-protected. Choices: false true ← (default)
wait boolean added in community.general 9.1.0	Block until the service is ready again. Choices: false ← (default) true
wait_timeout integer added in community.general 9.1.0	How long to block until the service is ready again before giving up. Default: 120

Attributes

Attribute	Support	Description
check_mode	Support: none	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Restart system power gracefully
  community.general.redfish_command:
    category: Systems
    command: PowerGracefulRestart
    resource_id: 437XR1138R2
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Turn system power off
  community.general.redfish_command:
    category: Systems
    command: PowerForceOff
    resource_id: 437XR1138R2

- name: Restart system power forcefully
  community.general.redfish_command:
    category: Systems
    command: PowerForceRestart
    resource_id: 437XR1138R2

- name: Shutdown system power gracefully
  community.general.redfish_command:
    category: Systems
    command: PowerGracefulShutdown
    resource_id: 437XR1138R2

- name: Turn system power on
  community.general.redfish_command:
    category: Systems
    command: PowerOn
    resource_id: 437XR1138R2

- name: Reboot system power
  community.general.redfish_command:
    category: Systems
    command: PowerReboot
    resource_id: 437XR1138R2

- name: Set one-time boot device to {{ bootdevice }}
  community.general.redfish_command:
    category: Systems
    command: SetOneTimeBoot
    resource_id: 437XR1138R2
    bootdevice: "{{ bootdevice }}"
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Set one-time boot device to UefiTarget of "/0x31/0x33/0x01/0x01"
  community.general.redfish_command:
    category: Systems
    command: SetOneTimeBoot
    resource_id: 437XR1138R2
    bootdevice: "UefiTarget"
    uefi_target: "/0x31/0x33/0x01/0x01"
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Set one-time boot device to BootNext target of "Boot0001"
  community.general.redfish_command:
    category: Systems
    command: SetOneTimeBoot
    resource_id: 437XR1138R2
    bootdevice: "UefiBootNext"
    boot_next: "Boot0001"
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Set persistent boot device override
  community.general.redfish_command:
    category: Systems
    command: EnableContinuousBootOverride
    resource_id: 437XR1138R2
    bootdevice: "{{ bootdevice }}"
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Set one-time boot to BiosSetup
  community.general.redfish_command:
    category: Systems
    command: SetOneTimeBoot
    boot_next: BiosSetup
    boot_override_mode: Legacy
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Disable persistent boot device override
  community.general.redfish_command:
    category: Systems
    command: DisableBootOverride

- name: Set system indicator LED to blink using security token for auth
  community.general.redfish_command:
    category: Systems
    command: IndicatorLedBlink
    resource_id: 437XR1138R2
    baseuri: "{{ baseuri }}"
    auth_token: "{{ result.session.token }}"

- name: Add user
  community.general.redfish_command:
    category: Accounts
    command: AddUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    new_username: "{{ new_username }}"
    new_password: "{{ new_password }}"
    roleid: "{{ roleid }}"

- name: Add user with specified account types
  community.general.redfish_command:
    category: Accounts
    command: AddUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    new_username: "{{ new_username }}"
    new_password: "{{ new_password }}"
    roleid: "{{ roleid }}"
    account_types:
      - Redfish
      - WebUI

- name: Add user using new option aliases
  community.general.redfish_command:
    category: Accounts
    command: AddUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    account_password: "{{ account_password }}"
    account_roleid: "{{ account_roleid }}"

- name: Delete user
  community.general.redfish_command:
    category: Accounts
    command: DeleteUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"

- name: Disable user
  community.general.redfish_command:
    category: Accounts
    command: DisableUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"

- name: Enable user
  community.general.redfish_command:
    category: Accounts
    command: EnableUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"

- name: Add and enable user
  community.general.redfish_command:
    category: Accounts
    command: AddUser,EnableUser
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    new_username: "{{ new_username }}"
    new_password: "{{ new_password }}"
    roleid: "{{ roleid }}"

- name: Update user password
  community.general.redfish_command:
    category: Accounts
    command: UpdateUserPassword
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    account_password: "{{ account_password }}"

- name: Update user role
  community.general.redfish_command:
    category: Accounts
    command: UpdateUserRole
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    roleid: "{{ roleid }}"

- name: Update user name
  community.general.redfish_command:
    category: Accounts
    command: UpdateUserName
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    account_updatename: "{{ account_updatename }}"

- name: Update user name
  community.general.redfish_command:
    category: Accounts
    command: UpdateUserName
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    update_username: "{{ update_username }}"

- name: Update AccountService properties
  community.general.redfish_command:
    category: Accounts
    command: UpdateAccountServiceProperties
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_properties:
      AccountLockoutThreshold: 5
      AccountLockoutDuration: 600

- name: Update user AccountTypes
  community.general.redfish_command:
    category: Accounts
    command: UpdateUserAccountTypes
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    account_username: "{{ account_username }}"
    account_types:
      - Redfish
      - WebUI

- name: Clear Manager Logs with a timeout of 20 seconds
  community.general.redfish_command:
    category: Manager
    command: ClearLogs
    resource_id: BMC
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    timeout: 20

- name: Create session
  community.general.redfish_command:
    category: Sessions
    command: CreateSession
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
  register: result

- name: Set chassis indicator LED to blink using security token for auth
  community.general.redfish_command:
    category: Chassis
    command: IndicatorLedBlink
    resource_id: 1U
    baseuri: "{{ baseuri }}"
    auth_token: "{{ result.session.token }}"

- name: Delete session using security token created by CreateSesssion above
  community.general.redfish_command:
    category: Sessions
    command: DeleteSession
    baseuri: "{{ baseuri }}"
    auth_token: "{{ result.session.token }}"
    session_uri: "{{ result.session.uri }}"

- name: Clear Sessions
  community.general.redfish_command:
    category: Sessions
    command: ClearSessions
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Simple update
  community.general.redfish_command:
    category: Update
    command: SimpleUpdate
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    update_image_uri: https://example.com/myupdate.img

- name: Simple update with additional options
  community.general.redfish_command:
    category: Update
    command: SimpleUpdate
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    update_image_uri: //example.com/myupdate.img
    update_protocol: FTP
    update_targets:
      - /redfish/v1/UpdateService/FirmwareInventory/BMC
    update_creds:
      username: operator
      password: supersecretpwd

- name: Multipart HTTP push update; timeout is 600 seconds to allow for a large image transfer
  community.general.redfish_command:
    category: Update
    command: MultipartHTTPPushUpdate
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    timeout: 600
    update_image_file: ~/images/myupdate.img

- name: Multipart HTTP push with additional options; timeout is 600 seconds to allow for a large image transfer
  community.general.redfish_command:
    category: Update
    command: MultipartHTTPPushUpdate
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    timeout: 600
    update_image_file: ~/images/myupdate.img
    update_targets:
      - /redfish/v1/UpdateService/FirmwareInventory/BMC
    update_oem_params:
      PreserveConfiguration: false

- name: Multipart HTTP push with custom OEM options
  vars:
    oem_payload:
      ImageType: BMC
  community.general.redfish_command:
    category: Update
    command: MultipartHTTPPushUpdate
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    update_image_file: ~/images/myupdate.img
    update_targets:
      - /redfish/v1/UpdateService/FirmwareInventory/BMC
    update_custom_oem_header: OemParameters
    update_custom_oem_mime_type: "application/json"
    update_custom_oem_params: "{{ oem_payload | to_json }}"

- name: Perform requested operations to continue the update
  community.general.redfish_command:
    category: Update
    command: PerformRequestedOperations
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    update_handle: /redfish/v1/TaskService/TaskMonitors/735

- name: Insert Virtual Media
  community.general.redfish_command:
    category: Systems
    command: VirtualMediaInsert
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    virtual_media:
      image_url: 'http://example.com/images/SomeLinux-current.iso'
      media_types:
        - CD
        - DVD
    resource_id: 1

- name: Insert Virtual Media
  community.general.redfish_command:
    category: Manager
    command: VirtualMediaInsert
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    virtual_media:
      image_url: 'http://example.com/images/SomeLinux-current.iso'
      media_types:
        - CD
        - DVD
    resource_id: BMC

- name: Eject Virtual Media
  community.general.redfish_command:
    category: Systems
    command: VirtualMediaEject
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    virtual_media:
      image_url: 'http://example.com/images/SomeLinux-current.iso'
    resource_id: 1

- name: Eject Virtual Media
  community.general.redfish_command:
    category: Manager
    command: VirtualMediaEject
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    virtual_media:
      image_url: 'http://example.com/images/SomeLinux-current.iso'
    resource_id: BMC

- name: Restart manager power gracefully
  community.general.redfish_command:
    category: Manager
    command: GracefulRestart
    resource_id: BMC
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"

- name: Restart manager power gracefully and wait for it to be available
  community.general.redfish_command:
    category: Manager
    command: GracefulRestart
    resource_id: BMC
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    wait: true

- name: Restart manager power gracefully
  community.general.redfish_command:
    category: Manager
    command: PowerGracefulRestart
    resource_id: BMC

- name: Turn manager power off
  community.general.redfish_command:
    category: Manager
    command: PowerForceOff
    resource_id: BMC

- name: Restart manager power forcefully
  community.general.redfish_command:
    category: Manager
    command: PowerForceRestart
    resource_id: BMC

- name: Shutdown manager power gracefully
  community.general.redfish_command:
    category: Manager
    command: PowerGracefulShutdown
    resource_id: BMC

- name: Turn manager power on
  community.general.redfish_command:
    category: Manager
    command: PowerOn
    resource_id: BMC

- name: Reboot manager power
  community.general.redfish_command:
    category: Manager
    command: PowerReboot
    resource_id: BMC

- name: Factory reset manager to defaults
  community.general.redfish_command:
    category: Manager
    command: ResetToDefaults
    resource_id: BMC
    reset_to_defaults_mode: ResetAll

- name: Verify BIOS attributes
  community.general.redfish_command:
    category: Systems
    command: VerifyBiosAttributes
    baseuri: "{{ baseuri }}"
    username: "{{ username }}"
    password: "{{ password }}"
    bios_attributes:
      SubNumaClustering: "Disabled"
      WorkloadProfile: "Virtualization-MaxPerformance"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
msg string	Message with action result or error description. Returned: always Sample: "Action was successful"
return_values dictionary added in community.general 6.1.0	Dictionary containing command-specific response data from the action. Returned: on success Sample: {"update_status": {"handle": "/redfish/v1/TaskService/TaskMonitors/735", "messages": [], "resets_requested": [], "ret": true, "status": "New"}}

Authors

• Jose Delarosa (@jose-delarosa)

• T S Kushal (@TSKushal)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication