You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

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

Note

This plugin is part of the community.general collection (version 3.8.3).

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
Parameters
Examples
Return Values

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 0.2.0 of community.general	properties of account service to update
auth_token string added in 2.3.0 of community.general	Security token for authentication with OOB controller
baseuri string / required	Base URI of OOB controller
boot_next string	BootNext target when bootdevice is “UefiBootNext”
boot_override_mode string added in 3.5.0 of community.general	Boot mode when using an override. Choices: Legacy UEFI
bootdevice string	bootdevice when setting boot configuration
category string / required	Category to execute on OOB controller
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
password string	Password for authentication with OOB controller
resource_id string added in 0.2.0 of community.general	The 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 2.3.0 of community.general	URI of the session resource
strip_etag_quotes boolean added in 3.7.0 of community.general	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: no ← (default) yes
timeout integer	Timeout in seconds for URL requests to OOB controller Default: 10
uefi_target string	UEFI target when bootdevice is “UefiTarget”
update_creds dictionary added in 0.2.0 of community.general	The credentials for retrieving the update image
password string	The password for retrieving the update image
username string	The username for retrieving the update image
update_image_uri string added in 0.2.0 of community.general	The URI of the image for the update
update_protocol string added in 0.2.0 of community.general	The protocol for the update
update_targets list / elements=string added in 0.2.0 of community.general	The list of target resource URIs to apply the update to
update_username aliases: account_updatename string added in 0.2.0 of community.general	new update user name for account_username
username string	Username for authentication with OOB controller
virtual_media dictionary added in 0.2.0 of community.general	The options for VirtualMedia commands
image_url string	The URL od the image the insert or eject
inserted boolean	Indicates if the image is treated as inserted on command completion Choices: no yes ← (default)
media_types list / elements=string	The list of media types appropriate for the image
password string	The password for accessing the image URL
transfer_method string	The transfer method to use with the image
transfer_protocol_type string	The network protocol to use with the image
username string	The username for accessing the image URL
write_protected boolean	Indicates if the media is treated as write-protected Choices: no yes ← (default)

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: 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 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: 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: 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: 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
  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

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”

Authors

Jose Delarosa (@jose-delarosa)

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

Synopsis

Parameters

Examples

Return Values