DMTF/python-redfish-library DMTF/python-redfish-library

  • Stars
    star
    149
  • Rank 248,619 (Top 5 %)
  • Language
    Python
  • License
    Other
  • Created almost 8 years ago
  • Updated 10 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
DMTF/python-redfish-library
github

DMTF

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python3 library for interacting with devices that support a Redfish service

python-redfish-library

https://img.shields.io/pypi/v/redfish.svg?maxAge=2592000 https://img.shields.io/github/release/DMTF/python-redfish-library.svg?maxAge=2592000 https://img.shields.io/pypi/pyversions/redfish.svg?maxAge=2592000

Contents

Description

As of version 3.0.0, Python2 is no longer supported. If Python2 is required, redfish<3.0.0 can be specified in a requirements file.

REST (Representational State Transfer) is a web based software architectural style consisting of a set of constraints that focuses on a system's resources. The Redfish library performs GET, POST, PUT, PATCH and DELETE HTTP operations on resources within a Redfish service. Go to the wiki for more details.

Installing

pip install redfish

Building from zip file source

python setup.py sdist --formats=zip (this will produce a .zip file)
cd dist
pip install redfish-x.x.x.zip

Requirements

Ensure the system does not have the OpenStack "python-redfish" module installed on the target system. This module is using a conflicting package name that this library already uses. The module in question can be found here: https://pypi.org/project/python-redfish/

Usage

A set of examples is provided under the examples directory of this project. In addition to the directives present in this paragraph, you will find valuable implementation tips and tricks in those examples.

Import the relevant Python module

For a Redfish conformant application import the relevant Python module.

For Redfish conformant application:

import redfish

Create a Redfish object

The Redfish object contains three required parameters:

  • base_url: The address of the Redfish service (with scheme). Example: https://192.168.1.100. For Unix sockets, use the scheme http+unix://, followed by the percent-encoded filepath to the socket.
  • username: The username for authentication.
  • password: The password for authentication.

There are several optional parameters:

  • default_prefix: The path to the Redfish service root. This is only used for initial connection and authentication with the service. The default value is /redfish/v1/.
  • sessionkey: The session key to use with subsequent requests. This can be used to bypass the login step. The default value is None.
  • cafile: The file path to the CA certificate that issued the Redfish service's certificate. The default value is None.
  • timeout: The number of seconds to wait for a response before closing the connection. The default value is None.
  • max_retry: The number of retries to perform an operation before giving up. The default value is 10.
  • proxies: A dictionary containing protocol to proxy URL mappings. The default value is None. See Using proxies.

To create a Redfish object, call the redfish_client method:

REDFISH_OBJ = redfish.redfish_client(base_url=login_host, username=login_account, \
                      password=login_password, default_prefix='/redfish/v1/')

Login to the service

After creating the REDFISH_OBJ, perform the login operation to authenticate with the service. The auth parameter allows you to specify the login method. Possible values are:

  • session: Creates a Redfish session with a session token.
  • basic: Uses HTTP Basic authentication for all requests.
REDFISH_OBJ.login(auth="session")

Perform a GET operation

A simple GET operation can be performed to obtain the data present in any valid path. An example of GET operation on the path "/redfish/v1/Systems/1" is shown below:

response = REDFISH_OBJ.get("/redfish/v1/Systems/1")

Perform a POST operation

A POST operation can be performed to create a resource or perform an action. An example of a POST operation on the path "/redfish/v1/Systems/1/Actions/ComputerSystem.Reset" is shown below:

body = {"ResetType": "GracefulShutdown"}
response = REDFISH_OBJ.post("/redfish/v1/Systems/1/Actions/ComputerSystem.Reset", body=body)

Notes about HTTP methods and arguments

The previous sections showed example GET and POST requests. The following is a list of the different methods supported:

  • get: Performs an HTTP GET operation to retrieve a resource from a URI.
  • head: Performs an HTTP HEAD operation to retrieve response headers from a URI, but no body.
  • post: Performs an HTTP POST operation to perform an action or create a new resource.
  • put: Performs an HTTP PUT operation to replace an existing resource.
  • patch: Performs an HTTP PATCH operation to update an existing resource.
  • delete: Performs an HTTP DELETE operation to remove a resource.

Each of the previous methods allows for the following arguments:

  • path: Required. String. The URI in which to invoke the operation.
    • Example: "/redfish/v1/Systems/1"
  • args: Dictionary. Query parameters to supply with the request.
    • The key-value pairs in the dictionary are the query parameter name and the query parameter value to supply.
    • Example: {"$select": "Reading,Status"}
  • body: Dictionary, List, Bytes, or String. The request body to provide with the request.
    • Not supported for get, head, or delete methods.
    • The data type supplied will dictate the encoding.
    • A dictionary is the most common usage, which results in a JSON body.
    • Example: {"ResetType": "GracefulShutdown"}
    • A list is used to supply multipart forms, which is useful for multipart HTTP push updates.
    • Bytes is used to supply an octet stream.
    • A string is used to supply an unstructed body, which may be used in some OEM cases.
  • headers: Dictionary. Additional HTTP headers to supply with the request.
    • The key-value pairs in the dictionary are the HTTP header name and the HTTP header value to supply.
    • Example: {"If-Match": etag_value}

Working with tasks

POST, PATCH, PUT, and DELETE operations may result in a task, describing an operation with a duration greater than the span of a single request. The action message object that is_processing will return a task that can be accessed reviewed when polled with monitor. An example of a POST operation with a possible task is shown below.

body = {"ResetType": "GracefulShutdown"}
response = REDFISH_OBJ.post("/redfish/v1/Systems/1/Actions/ComputerSystem.Reset", body=body)
if(response.is_processing):
    task = response.monitor(context)

    while(task.is_processing):
        retry_time = task.retry_after
        task_status = task.dict['TaskState']
        time.sleep(retry_time if retry_time else 5)
        task = response.monitor(context)

Logout the created session

Ensure you perform a logout operation when done interacting with the Redfish service. If this step isn't performed, the session will remain active until the Redfish service decides to close it.

REDFISH_OBJ.logout()

The logout operation deletes the current sesssion from the service. The redfish_client object destructor includes a logout statement.

Using proxies

There are two methods for using proxies: configuring environment variables or directly providing proxy information.

Environment variables

You can use a proxy by specifying the HTTP_PROXY and HTTPS_PROXY environment variables. Hosts to be excluded from the proxy can be specified using the NO_PROXY environment variable.

export HTTP_PROXY="http://192.168.1.10:8888"
export HTTPS_PROXY="http://192.168.1.10:8888"

Directly provided

You can use a proxy by building a dictionary containing the proxy information and providing it to the proxies argument when creating the redfish_client object. The key-value pairs of the dictionary contain the protocol and the proxy URL for the protocol.

proxies = {
    'http': 'http://192.168.1.10:8888',
    'https': 'http://192.168.1.10:8888',
}
REDFISH_OBJ = redfish.redfish_client(base_url=login_host, username=login_account, \
                      password=login_password, proxies=proxies)

SOCKS proxy support

An additional package is required to use SOCKS proxies.

pip install -U requests[socks]

Once installed, the proxy can be configured using environment variables or directly provided like any other proxy. For example:

export HTTP_PROXY="socks5h://localhost:8123"
export HTTPS_PROXY="socks5h://localhost:8123"

Release Process

  1. Go to the "Actions" page
  2. Select the "Release and Publish" workflow
  3. Click "Run workflow"
  4. Fill out the form
  5. Click "Run workflow"

Copyright and License

Copyright Notice: Copyright 2016-2022 DMTF. All rights reserved. License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/python-redfish-library/blob/main/LICENSE.md

More Repositories

1

Redfishtool

A Python34 program that implements a command line tool for accessing the Redfish API.
Python
211
star
2

libspdm

C
80
star
3

Redfish-Tools

DMTF-produced tools to support the Redfish Specification
Python
78
star
4

Redfish-Mockup-Server

A simple Python 3.4 program that can be copied into a folder at the top of any Redfish mockup and can serve Redfish requests on the specified IP/port.
Python
61
star
5

Redfish-Interface-Emulator

The Redfish Interface Emulator can emulate a Redfish-based interface statically (GET) or dynamically (POST, PATCH, DELETE)
Python
50
star
6

libredfish

libRedfish is a C client library that allows for Creation of Entities (POST), Read of Entities (GET), Update of Entities (PATCH), Deletion of Entities (DELETE), running Actions (POST), receiving events, and providing some basic query abilities.
C
47
star
7

Redfish-Tacklebox

Python based utilities for performing common management operations with Redfish
Python
46
star
8

Redfish-Mockup-Creator

A Python3 program that creates a Redfish Mockup folder structure from a real live Redfish service.
Python
45
star
9

Redfish-Service-Validator

The Redfish Service Validator is a Python3 tool for checking conformance of any "device" with a Redfish service interface against Redfish CSDL schema
Python
36
star
10

Redfish-Event-Listener

The Redfish Event Listener is a lightweight HTTPS server that can be deployed to read and record events from Redfish services.
Python
29
star
11

spdm-emu

C
25
star
12

Redfish-Profile-Simulator

A Flask-based simulator of a Redfish Service implementing the proposed OCP feature Profile.
Python
20
star
13

python-redfish-utility

Python-based utility for interacting with devices supporting a Redfish Service
Python
16
star
14

Redfish-Ansible-Playbooks

A set of example Ansible playbooks for invoking the Redfish Ansible modules.
11
star
15

Redfish-Protocol-Validator

The Redfish Protocol Validator tests the HTTP protocol behavior of a Redfish service to validate that it conforms to the Redfish specification.
Python
11
star
16

Redfish-Interop-Validator

The Redfish Interop Validator is a python3 tool that will validate a service based on a profile given to the tool.
Python
9
star
17

spdm-dump

C
7
star
18

SPDM-Responder-Validator

C
6
star
19

Redfish-Publications

Read-only copies of DMTF Redfish schemas and message registries
HTML
5
star
20

Redfish-Service-Conformance-Check

This tool checks an operational Redfish Service to see that it conforms to the normative statements from the Redfish specification
Python
4
star
21

Redfish-Test-Framework

The Redfish Test Framework is a python3 tool and a model for organizing and running a set of Redfish interoperability tests against a target system.
Python
4
star
22

RDE-Dictionary

Dictionary generator for Redfish Device Enablement
Python
4
star
23

YANG-to-Redfish-Converter

This tool converts a YANG model file to the corresponding Redfish schema, specified in OData CSDL, in accordance with the YANG-to-CSDL Mapping Specification.
Python
4
star
24

Redfish-Schema-Creator

Creates a Redfish CSDL schema file from an annotated JSON file
Python
4
star
25

Redfish-JsonSchema-ResponseValidator

The Redfish JSON Schema Response Validator is a Python3 utility used to validate any JSON resource against DMTF provided JSON schemas
Python
3
star
26

Redfish-Reference-Checker

RedfishReferenceTool.py is a python3 tool that checks for valid reference URLs in CSDL xml files.
Python
2
star
27

Redfish-Schema-C-Struct-Generator

Python
1
star
28

Redfish-URI-Validator

The Redfish URI Validator is a Python3 tool which scans all resources on a given service and verifies the URIs on the service match the patterns described in a provided OpenAPI specification.
Python
1
star