# Using Sushy

To use sushy in a project:

## Specifying an authentication type

There are three authentication objects. By default we use SessionOrBasicAuth.

Authentication Modes:

- auth.SessionOrBasicAuth: Use session based authentication. If we are unable to create a session we will fallback to basic authentication.

- auth.BasicAuth: Use basic authentication only.

- auth.SessionAuth: Use session based authentication only.

    import logging

    import sushy
    from sushy import auth

    # Enable logging at DEBUG level
    LOG = logging.getLogger('sushy')
    LOG.setLevel(logging.DEBUG)
    LOG.addHandler(logging.StreamHandler())

    basic_auth = auth.BasicAuth(username='foo', password='bar')
    session_auth = auth.SessionAuth(username='foo', password='bar')
    session_or_basic_auth = auth.SessionOrBasicAuth(username='foo',
                                                    password='bar')

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    auth=basic_auth)

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    auth=session_auth)

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    auth=session_or_basic_auth)

    # It is important to note that you can
    # call sushy without supplying an
    # authentication object. In that case we
    # will use the SessionOrBasicAuth authentication
    # object in an attempt to connect to all different
    # types of redfish servers.
    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    username='foo',
                    password='bar')

## Creating and using a sushy system object

    import logging

    import sushy

    # Enable logging at DEBUG level
    LOG = logging.getLogger('sushy')
    LOG.setLevel(logging.DEBUG)
    LOG.addHandler(logging.StreamHandler())

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    username='foo', password='bar')

    # Get the Redfish version
    print(s.redfish_version)

    # Instantiate a system object
    sys_inst = s.get_system('/redfish/v1/Systems/437XR1138R2')

    # Using system collections

    # Instantiate a SystemCollection object
    sys_col = s.get_system_collection()

    # Print the ID of the systems available in the collection
    print(sys_col.members_identities)

    # Get a list of systems objects available in the collection
    sys_col_insts = sys_col.get_members()

    # Instantiate a system object, same as getting it directly
    # from the s.get_system()
    sys_inst = sys_col.get_member(sys_col.members_identities[0])

    # Refresh the system collection object
    #
    # See below for more options on how to refresh resources.
    sys_col.refresh()

    # Using system actions

    # Power the system ON
    sys_inst.reset_system(sushy.ResetType.ON)

    # Get a list of allowed reset values
    print(sys_inst.get_allowed_reset_system_values())

    # Refresh the system object (with all its sub-resources)
    sys_inst.refresh()

    # Alternatively, you can only refresh the resource if it is stale by passing
    # force=False:
    sys_inst.refresh(force=False)

    # A resource can be marked stale by calling invalidate. Note that its
    # subresources won't be marked as stale, and thus they won't be refreshed by
    # a call to refresh(force=False)
    sys_inst.invalidate()

    # Get the current power state
    print(sys_inst.power_state)

    # Set the next boot device to boot once from PXE in UEFI mode
    sys_inst.set_system_boot_source(sushy.BootSource.PXE,
                                    enabled=sushy.BootSourceOverrideEnabled.ONCE,
                                    mode=sushy.BootSourceOverrideMode.UEFI)

    # Get the current boot source information
    print(sys_inst.boot)

    # Get a list of allowed boot source target values
    print(sys_inst.get_allowed_system_boot_source_values())

    # Get the memory summary
    print(sys_inst.memory_summary)

    # Get the processor summary
    print(sys_inst.processors.summary)

## Creating and using a sushy manager object

    import logging

    import sushy

    # Enable logging at DEBUG level
    LOG = logging.getLogger('sushy')
    LOG.setLevel(logging.DEBUG)
    LOG.addHandler(logging.StreamHandler())

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    username='foo', password='bar')

    # Instantiate a manager object
    mgr_inst = s.get_manager('BMC')

    # Get the manager name & description
    print(mgr_inst.name)
    print(mgr_inst.description)

    # Using manager collections

    # Instantiate a ManagerCollection object
    mgr_col = s.get_manager_collection()

    # Print the ID of the managers available in the collection
    print(mgr_col.members_identities)

    # Get a list of manager objects available in the collection
    mgr_insts = mgr_col.get_members()

    # Instantiate a manager object, same as getting it directly
    # from the s.get_manager()
    mgr_inst = mgr_col.get_member(mgr_col.members_identities[0])

    # Refresh the manager collection object
    mgr_col.invalidate()
    mgr_col.refresh()

    # Using manager actions

    # Get supported graphical console types
    print(mgr_inst.get_supported_graphical_console_types())

    # Get supported serial console types
    print(mgr_inst.get_supported_serial_console_types())

    # Get supported command shell types
    print(mgr_inst.get_supported_command_shell_types())

    # Get a list of allowed manager reset values
    print(mgr_inst.get_allowed_reset_manager_values())

    # Reset the manager
    mgr_inst.reset_manager(sushy.ResetType.FORCE_RESTART)

    # Refresh the manager object (with all its sub-resources)
    mgr_inst.refresh(force=True)

    # Using Virtual Media

    # Instantiate a VirtualMediaCollection object
    virtmedia_col = mgr_inst.virtual_media

    # Print the ID of the VirtualMedia available in the collection
    print(virtmedia_col.members_identities)

    # Get a list of VirtualMedia objects available in the collection
    virtmedia_insts = virtmedia_col.get_members()

    # Instantiate a VirtualMedia object
    virtmedia_inst = virtmedia_col.get_member(
        virtmedia_col.members_identities[0])

    # Print out some of the VirtualMedia properties
    print(virtmedia_inst.name,
          virtmedia_inst.media_types)

    # Insert virtual media (invalidates virtmedia_inst contents)
    virtmedia_inst.insert_media('https://www.dmtf.org/freeImages/Sardine.img')

    # Refresh the resource to load actual contents
    virtmedia_inst.refresh()

    # Print out some of the VirtualMedia properties
    print(virtmedia_inst.image,
          virtmedia_inst.image_path,
          virtmedia_inst.inserted,
          virtmedia_inst.write_protected)

    # ... Boot the system off the virtual media...

    # Eject virtual media (invalidates virtmedia_inst contents)
    virtmedia_inst.eject_media()

## Creating and using a sushy client with Sessions

    import logging

    import sushy

    # Enable logging at DEBUG level
    LOG = logging.getLogger('sushy')
    LOG.setLevel(logging.DEBUG)
    LOG.addHandler(logging.StreamHandler())

    s = sushy.Sushy('http://localhost:8000/redfish/v1',
                    username='foo', password='bar')

    # Get the ComputerSystem object (if there is only one), otherwise
    # the identity must be provided as a path to the system.
    system = s.get_system()

    # A session is created automatically for you.
    # Print the boot field in the ComputerSystem.
    print(system.boot)

    # Upon session timeout, Sushy recreates the session based upon
    # provided credentials. If this fails, an exception is raised.

    # Explicitly request a session_key and session_uri.
    # This is not stored, but may be useful.
    session_key, session_uri = s.create_session(username='foo',
                                                password='bar')

    # Retrieve the session
    session = s.get_session(session_uri)

    # Delete the session
    session.delete()

## Using OEM extensions

Before running this example, please make sure you have a Redfish BMC that includes the OEM piece for a specific vendor, as well as the Sushy OEM extension package installed in the system for the same vendor.

You can check the presence of the OEM extension within each Redfish resource by specifying the vendor ID and search for them.

In the following example, we are looking up “Acme” vendor extension to Redfish Manager resource.

    import sushy

    root = sushy.Sushy('http://localhost:8000/redfish/v1')

    # Instantiate a system object
    system = root.get_system('/redfish/v1/Systems/437XR1138R2')

    print('Working on system resource %s' % system.identity)

    for manager in system.managers:

        print('Using System manager %s' % manager.identity)

        # Get a list of OEM extension names for the system manager
        oem_vendors = manager.oem_vendors

        print('Listing OEM extension name(s) for the System '
              'manager %s' % manager.identity )

        print(*oem_vendors, sep="\n")

        try:
            manager_oem = manager.get_oem_extension('Acme')

        except sushy.exceptions.OEMExtensionNotFoundError:
            print('ERROR: Acme OEM extension not found in '
                  'Manager %s' % manager.identity)
            continue

        print('%s is an OEM extension of Manager %s'
               % (manager_oem.get_extension(), manager.identity))

        # set boot device to a virtual media device image
        manager_oem.set_virtual_boot_device(sushy.VirtualMediaType.CD,
                                            manager=manager)

If you do not have any real baremetal machine that supports the Redfish protocol you can look at the Contributing to Sushy page to learn how to run a Redfish emulator.

For the OEM extension example, presently, both of the emulators (static/dynamic) do not expose any OEM; as a result, users may need to add manually some OEM resources to emulators’ templates. It may be easier to start with a static emulator.

this page last updated: 2025-02-27 12:56:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.