Copyright 2016-2018 DMTF. All rights reserved.

redfishtool

About

redfishtool is a commandline tool that implements the client side of the Redfish RESTful API for Data Center Hardware Management.

Redfish is the new RESTful API for hardware management defined by the DMTF Scalable Platform Management Forum (SPMF). It provides a modern, secure, multi-node, extendable interface for doing hardware management. The initial release included hardware inventory, server power-on/off/reset, reading power draw, setting power limits, reading sensors such as fans, read/write of ID LEDs, asset tags, and went beyond IPMI in functionality to include inventory of processors, storage, Ethernet controllers, and total memory. New Redfish extensions have now been added to the spec and include firmware update, BIOS config, memory inventory, direct attached storage control, and the list grows.

redfishtool makes it simple to use the Redfish API from a BASH script or interactively from a client command shell.

While other generic HTTP clients such as Linux curl can send and receive Redfish requests, redfishtool goes well beyond these generic HTTP clients by automatically handling many of the hypermedia and Redfish-specific protocol aspects of the Redfish API that require a client to often execute multiple queries to a redfish service to walk the hypermedia links from the redfish root down to the detailed URI of a specific resource (eg Processor-2 of Blade-4 in a computer blade system). Specifically, redfishtool provides the following functions over curl:

• implements Redfish Session Authentication as well as HTTP Basic Auth
• walks the Redfish schema following strict interoperpbility processors...] to find find the targeted instance based on Id, UUID, URL or other attributes
• handles GETs for collections that are returned in multiple pieces--requiring client to read in a loop until the full collection is returned
• handles ETag and If-Match headers when PATCHing a resource to write properties
• implements many common set or action operations with simple commandline syntax (eg server reset, setting LEDs, assetTag, powerLimits, etc)
• negotiates the latest redfish protocol version between client and service (demonstrating the proper way to do this)
• can read specific properties of a resource, or expand collections to include all members of the collection expanded
• supports adding and deleting users, and common Redfish account service operations
• For debug, provides multiple levels of verbose output to add descriptive headers, and show what HTTP requests are being executed
• For debug, includes multiple levels of status display showing HTTP status codes and headers returned and sent
• For easy parsing, outputs all responses in JSON format unless verbose or status debug options were specified

Why redfishtool?

1. redfishtool was originally written during the development of the Redfish specification to help find ambiguities in the spec.
2. redfishtool is now also being used to test interoperability between redfish service implementations.
3. In addition, redfishtool provides an example implementation for how a client can execute common server management functions like inventory; power-on/off/reset; setting power limits, indicator LEDs, and AssetTags, and searching a multi-node redfish service to find a specific node (with specific UUID, redfish Id, etc). redfishtool follows strict rules of interoperability. To support this goal, liberal comments are added throughout code to explain why each step is being executed.
4. As described above, it makes it easy to use the Redfish API from a BASH script, or as an easy-to-use interactive CLI -- but WITHOUIT creating a 'new API'. All (rather most) of the responses from redfishtool are Redfish-defined responses. The properties and resources are defined in the redfish spec. redfishtool is just a tool to access the Redfish API-not a new interface itself.
   • The exception is that a 'list' operation was added for all collections to display the key properties for each of the members--rather than just the URIs to the members.

Installation

redfishtool can be installed via pip.

pip install redfishtool

Requirements

redfishtool is based on Python 3 and the client system is required to have the Python framework installed before the tool can be installed and executed on the system.

If cloning the tool from Github, as opposed to performing the installation via pip, the following packages are required to be installed and accessible from the python environment:

• requests - https://github.com/psf/requests
• python-dateutil - https://github.com/dateutil/dateutil

You may install the required packages by running:

pip install -r requirements.txt

Usage

python redfishtool [ Options ] [ SubCommands ] [ Operation ] [ OtherArgs ]

• redfishtool is a python3.4+ program. It uses the python3 "requests" lib for sending HTTP requests, and a host of other standard libs in python3.4+
• The redfishtool option/optarg parsing strictly follows the well established linux/GNU getopt syntax where arguments and options can be specified in any order, and both short (eg -r <host>) or long (--rhost=<host>) syntax is supported.
• options are used to pass usernames, passwords, Host:port, authentication options, verbose/status flags, and also to specify how to search to find specific collection members (-I <Id>, -a (all), -M <prop>:<val> ).
• subCommands indicate the general area of the API (following ipmitool convention), and align with Redfish navigation property names like "Chassis", "Systems", "AccountService", etc.
• Operations are specify an action or operation you want to perform like Systems setBootOverride ..., or Systems reset.
• OtherArgs are any other arguments after the Operation that are sometimes required--like: Systems <setBootOverride> <enableValue> <targetValue>

Common OPTIONS:

-V,          --version           -- show redfishtool version, and exit
-h,          --help              -- show Usage, Options, and list of subCommands, and exit
-v,          --verbose           -- verbose level, can repeat up to 5 times for more verbose output
                           -v(header), -vv(+addl info), -vvv(Request trace), -vvvv(+subCmd dbg), -vvvvv(max dbg)
-s,          --status            -- status level, can repeat up to 5 times for more status output
                            -s(http_status), 
                            -ss(+r.url, +r.elapsed executionTime ), 
                            -sss(+request hdrs,data,authType, +response status_code, +response executionTime, 
                                 +login auth token/sessId/sessUri)
                            -ssss(+response headers), -sssss(+response data
-u <user>,   --user=<usernm>     -- username used for remote redfish authentication
-p <passwd>, --password=<passwd> -- password used for remote redfish authentication
-r <rhost>,  --rhost=<rhost>     -- remote redfish service hostname or IP:port
-t <token>,  --token=<token>     -- redfish auth session token-for sessions across multiple calls
-q,          --quiet             -- quiet mode--suppress error, warning, and diagnostic messages
-c <cfgFile>,--config=<cfgFile>  -- read options (including credentials) from file <cfgFile>
-T <timeout>,--Timeout=<timeout> -- timeout in seconds for each http request.  Default=10

-P <property>, --Prop=<property> -- return only the specified property. Applies only to all "get" operations
-E, --Entries                    -- Fetch the Logs entries. Applies to Logs sub-command of Systems, Chassis and Managers

Options used by "raw" subcommand:

-d <data>    --data=<data>       -- the http request "data" to send on PATCH,POST,or PUT requests

Options to specify top-level collection members: eg: Systems -I <sysId>

For Systems, Managers, and Chassis commands that require specifying a top-level collection member, if no option is specified the default is --One.

-I <Id>, --Id=<Id>               -- Use <Id> to specify the collection member
-M <prop>:<val> --Match=<prop>:<val>-- Use <prop>=<val> search to find the collection member
-F,  --First                     -- Use the 1st link returned in the collection or 1st "matching" link if used with -M
-1,  --One                       -- Use the single link returned in the collection. Return error if more than one member exists
-a,  --all                       -- Returns all members if the operation is a Get on a top-level collection like Systems
-L <Link>,  --Link=<Link>        -- Use <Link> (eg /redfish/v1/Systems/1) to reference the collection member. 
                                 --   If <Link> is not one of the links in the collection, and error is returned.

Options to specify 2nd-level collection members: eg: Systems -I<sysId> Processors -i<procId>

-i <id>, --id=<id>               -- use <id> to specify the 2nd-level collection member
-m <prop>:<val> --match=<prop>:val>--use <prop>=<val> search of 2nd-level collection to specify member
-l <link>  --link=<link>         -- Use <link> (eg /redfish/v1/SYstems/1/Processors/1) to reference a 2nd level resource
                                 --   A -I|M|F|1|L option is still required to specify the link to the top-lvl collection
-a,  --all                       -- Returns all members of the 2nd level collection if the operation is a Get on the 
                                 --   2nd level collection (eg Processors). -I|M|F|1|L still specifies the top-lvl collection.

Additional OPTIONS:

-W <num>:<connTimeout>,          -- Send up to <num> {GET /redfish} re