|
Post by jautor on Feb 4, 2019 23:47:45 GMT
Thanks for the feedback and we'll discuss this, as we take any security concerns seriously.
A couple of points about those properties:
First, the "@odata.id" is essentially a "self" pointer containing the URI of the resource. The "@odata.id" is provided so that the source URI is included in the JSON payload response - so that the source location is not lost if client software passes the payload on separate from the HTTP details. Since a client has to know the URI to read it - this value provides no new information from a security perspective. The fact that the Service replies to the "/redfish/v1" URI means that Redfish v1.x is supported.
The "RedfishVersion" indicates the version of the Redfish Specification that the Service supports. This is NOT the firmware / software version of the implementation, only the protocol version. That would only be useful if a flaw in the protocol was discovered (while that has happened in other protocols/specifications - it's unlikely in Redfish as the bulk of the protocol definition is just HTTP/HTTPS).
That said, the "RedfishVersion" property is not required, and so may be omitted from the payload. It is placed here primarily as a means for software to detect functionality that was added in minor 1.x versions of the specification. We've also defined the "ProtocolFeaturesSupported" object to better answer those software questions, as the Version doesn't tell a client if the service actually implements the (optional) features of the specification.
Thanks,
Jeff
|
|
|
Post by jautor on Feb 4, 2019 23:27:08 GMT
Thanks for explaining it, I understand that I can't perform the PATCH request from AccountService but can I perform the following request from accounts property? Content-Type: application/json PATCH /redfish/v1/AccountService/Accounts HTTP/1.1 { "Oem": { " MyVendorName": { "OEMProp2": "New Value" } } } That would be a PATCH to an "Oem" object within the ManagerAccountCollection resource. The Collections are marked as "updateable=false" so no, a PATCH would fail. While placing OEM properties in a Collection resource is allowed by the specification, as defined currently they must be read-only. Regardless, I would recommend that you place those OEM properties in the AccountService resource instead. As account management is the purpose of that resource/service, it should be clear to the client/user that any OEM properties there would be related to the Accounts... Jeff
|
|
|
Post by jautor on Jan 30, 2019 16:00:42 GMT
The readonly annotation indicates that the property itself is read-only, which means the link to the ManagerAccountCollection cannot be changed.
But yes, what you want to do is create/modify/delete a member of that collection, which is done using POST/DELETE operations on the collection. If you look at the schema definition for ManagerAccountCollection, you'll see "insertable=true" in the JSON-schema (and under "InsertRestrictions" in the CSDL).
I'll take a look to see if there's a way to better surface those Collection capability details in the schema documentation. As there aren't a lot of collections that users can add/modify/delete, perhaps we just need to add statements to the descriptions in the links to them that say something like "ManagerAccounts can be created or deleted by performing operations on the Collection."
Jeff
|
|
|
Post by jautor on Jan 19, 2019 17:35:37 GMT
DMTF’s Redfish®, version 2018.3, is now available for public download, featuring 10 important new schemas and other significant updates. An API designed to deliver simple and secure management for hybrid IT and the Software Defined Data Center (SDDC), this release includes new versions of the Redfish schema and specification, as well as additional developer resources. Redfish 2018.3 adds interoperable management of certificates via the Redfish interface, with new schemas for CertificateService (which includes Properties and Actions to manage security certificates), CertificateLocations, and Certificate (with a description of each security certificate). In addition, this latest version of Redfish includes a Sensor schema, which will serve as an architectural foundation for sensor resource definitions for future Data Center Infrastructure Management (DCIM) and Internet of Things (IoT) resources. For more information, the items released as part of the new Redfish 2018.3 update include: • 2018.3 Redfish Schema Bundle – a .zip file that contains the current versions of all Redfish schema. In addition to Certificate and Sensor management, this file also includes new schemas for AccelerationFunction and ProcessorMetrics, as well as RedfishError (useful for validating error response payloads). • Redfish Specification v1.6.1– this updated version of the specification includes minor updates with numerous clarifications. • Redfish 2018.3 Overview– a presentation that provides detailed descriptions of each revision in the latest version of the Redfish Schema and Specification. • Redfish Resource and Schema Guide – Designed to help educate users of Redfish, this human-readable guide to the Redfish Schema has been updated for version 2018.3. Application developers and DevOps personnel creating client-side software to communicate with a Redfish service, as well as other consumers of the API, will benefit from the explanations in this resource. • Redfish History – December 2018 – updated with each new release, this presentation offers a comprehensive view of each revision to Redfish since 2016. To learn more about Redfish, click here or - for developers - visit the Redfish Developer Hub today. A one-stop, in-depth technical resource – by developers, for developers – the Redfish Developer Hub provides all the files, tools, community support, tutorials and other advanced education you may need to help you use Redfish. Technical work on the Redfish standard takes place in DMTF’s Redfish Forum (the group formerly known as the Scalable Platforms Management Forum). To find out how you can join and contribute to this standard, click here.
|
|
|
Post by jautor on Jan 19, 2019 17:27:40 GMT
Ratan,
We knew that for the majority of implementations that the service would only support one instance of LDAP / ActiveDirectory, so we made the decision to have the "first" instance within the AccountService so that you could easily PATCH using a script, etc. that would always find that first instance.
It's only if the service provides the ability for multiple external account providers that the link to the collection of "additional" (those beyond the first instance) would exist.
So yes, for those LDAP/AD objects within the AccountService, you use PATCH to update them.
Jeff
|
|
|
Post by jautor on Jan 10, 2019 23:13:26 GMT
I may be mistaken here (I am still a noob and learning), but Redfish arrays are fixed length, right? The client cannot patch back a shorter or longer list for the array. For true lists that grow/shrink I would use a collection, right? No, if the implementation (and the property) are read-write, a PATCH can be used to shrink or grow the array as follows: "MyProperty": [ "a", "b", "c", "d"] PATCH "MyProperty": [ "a", null, "c", "d" ] will remove "b" from the array ==> ["a", "c", "d"] PATCH "MyProperty": [ "a", "b", "c", "d", "pineapple" ] will add 'pineapple' to the array And for doing changes where you don't want to affect other items, you can use empty JSON objects instead of filling in the full contents: PATCH "MyProperty": [ "Elephant", {}, {}, {} ] will change 'a' to 'Elephant' and leave the other items as-is: ==> ["Elephant", "b", "c", "d" ] And I agree with mraineri that null should be allowed in the StaticNameServers array... Jeff
|
|
|
Post by jautor on Dec 16, 2018 19:13:34 GMT
The only read-write requirement I believe in the entire specification is for the creation of a Session. Otherwise, the Service is not required to provide read-write support on any properties. The schema only specifies the capabilities allowed.
I'll bring this one with the group, but I believe it is correctly defined - the intent was to allow a user (Admin-level most likely) the ability to enable/disable authentication modes of the Host Interface. So that while a Service may support an un-authenticated session from the Host, the user could decide to require authentication for their environment.
Jeff
|
|
|
Post by jautor on Dec 16, 2018 19:07:55 GMT
We discussed that question and didn't think we could get a consistent answer for all implementations because of the different behaviors of the various software stacks. So either response is allowed, but my preference would be to reject the request - because that would provide a more consistent error behavior for the user.
Jeff
|
|
|
Post by jautor on Dec 14, 2018 21:12:54 GMT
So does that mean it is best to hardcode URIs. For example: the processor uri should be hardcoded to /redfish/v1/Systems/{vendor_format}/Processors/CPU.1 How is the code generic then. Will the URIs never change across versions?? No, you should NOT hard-code URIs. Starting with Redfish v1.6, many URIs will be defined by the specification, at least to a point. The Processor collection, from your example, would always follow the format of: /redfish/v1/Systems/{vendor_format}/Processors/{vendor_format} Note that I corrected your example - the name of the CPU instance is also chosen by the vendor/implementation. But v1.6 is a very new version of the specification, and probably not supported yet in any shipping products. Now, most implementation generally followed the formats specified in the schema release 2018.2 (part of the v1.6 release) - which is how we decided what URIs to use... But there are some exceptions, so until the Service reports "RedfishVersion" of "1.6.0" or above, it's not a guarantee. The right way to discover these links is to read the ServiceRoot (which must be at \redfish\v1) and then use the hypermedia links to the other resources, and repeat that for each link as you traverse the tree. Jeff
|
|
|
Post by jautor on Dec 14, 2018 21:04:39 GMT
First, the "Redfish Version" is only describing the protocol specification version, and doesn't tell you what data is available or what version of each schema/resource is supported. Each schema (resource) also contains its own version. This is a very useful part of the specification (separate versions for each resource), but it can be confusing, too. The service can support protocol v1.6, but may still only support the Memory schema v1.0.2, for example.
But regardless of the version of the specification, each implementation can choose to include those resources or not. If an implementation doesn't support a resource you want - contact the manufacturer and give them that feedback!
The MemoryCollection was added to the ComputerSystem schema in v1.1.0 and you can tell if the Service supports that Collection by checking for the link called "Memory" within the ComputerSystem resource.
As for upgrading your server to a later version - that is a question for the manufacturer of your server. If they upgraded their management (BMC) firmware with additional Redfish support, you should be able to apply that to your system without touching anything else.
Jeff
|
|
|
Post by jautor on Dec 14, 2018 20:53:47 GMT
Hello, I have briefly used Redfish services from a client perspective for Rack-mounted Servers so I understand some of the resources mentioned under the specification. However, I do not understand the use of schemas, for both the client as well as the vendor that's providing the service. Going through the schemas I do understand that they define what the client should ask for; and for those requests, what a service might respond with. As a client, I used the service to get information from very few resources, I didn't necessarily had to deal with these schemas. Correct. The schemas define the properties that may appear in each resource (URI) - so that both the Service knows what to implement, and what a client can expect to be in the JSON response. It's essentially a specification for each data structure. We designed Redfish so that the properties and resource layout are mostly obvious - that for many cases, you can figure out what they all mean without ever looking at the schema. But now, as I have to implement one, I think schemas play a big part in designing a service. How the really common ResourceCollections (Managers, Systems, Chassis etc.) and Services (SessionService, AccountService, etc.) are mandatory, and there are other ResourceCollections and Resources that a vendor might use as per their discretion. Q1: There are schemas for various resources under the Redfish Specification, does a vendor have to include them all? For example, my system is not a Blade Server, do I still have to use that Resource as a part of my Redfish implementation? Or I can pick and choose, which resources I need and then for those resources, I provide information for each property? No, very few things are actually required to be there. Obviously you need the SessionService so that users can create a session, and you need the ServiceRoot so they can find other resources and/or figure out what the Service is supporting. Before we go any further, let me point you to the Redfish Resource and Schema Guide, which is a document that converts the "human and machine readable" schema files into something that is really human-readable. That document has example payloads for most resource types, and puts all the important data about each property into tables. The document gets updated every time we do a schema bundle release (three times a year), and can be downloaded from the Redfish Standards Page under the document "DSP2046". Here's a direct link for the 2018.2 version, which is the most recently published: www.dmtf.org/sites/default/files/standards/documents/DSP2046_2018.2_0.pdfIn that guide you'll see some properties marked as "required". That means that if that resource is implemented, then those properties MUST be implemented as well. But you only implement the resources that make sense for your product. You should NOT implement anything your product doesn't support - you just leave those things out. Q2: Do I have to use the schemas JUST AS A REFERENCE for creating this service? To better understand the Service, I used Redfish-Mockup-Creator on the Rack-mounter Server I talked about earlier. This created a recursive directory under redfish/ with index.json for each REST endpoint that the Mockup-Creator hit. I then used Redfish-Profile-Simulator to host a Python-Flask based server pointing to the directory I obtained earlier. I was able to get the Resource information from each REST endpoint. This was the index.json content There are tools that can use the schema files (especially the OpenAPI conforming .yaml files) to create code for you based on the schemas that you might find useful. But no, otherwise, the schema files themselves are just for your reference to ensure your implementation meets the specification. Q3: How do I create a Redfish Service? Do I maintain a similar recursive folder structure for each Resource I implement? I read the entire document - Redfish API Specification Nowhere is it mentioned how a schema is tied to a resource apart from using it as a guideline when creating a Service. It's just like any other web server or service - you have a resource (URI) tree that gets populated by various routines that understand that resource. The schemas are tied to a resource in two ways (starting with Redfish v1.6.0). First, each resource tells you which schema it implements - this is the required "@odata.type" property. Second, the URIs for each resource are now defined for each schema. So the URI \redfish\v1\Chassis will return a ChassisCollection (if the service implements one). Q4: If It is done that way, and I decide to add some OEM properties or Resources, I would have to maintain my source-code and the schema separately. I guess my concern was If there's a way to dynamically create a schema from a resource or the other way around. Thank you for reading through. Any help is appreciated. Best, Chinmay If you create OEM resources or properties you'll want to create schema files to describe them, so that anyone building applications can use those schema files in the same way they would the standard Redfish-defined ones. And yes, those are separate from your source code. As I said above, there are tools that can convert schema files (OpenAPI tools being the most popular of the three schema languages we support, although there are JSON schema tools available as well) into data structures or code blocks to help you get started. What is left is for your code to populate the values for each of the properties - no one else can do that for you... Hope that helps, Jeff
|
|
|
Post by jautor on Dec 14, 2018 20:13:15 GMT
The answer will likely depend on the implementation, as the Redfish Service may not even get called if the web service/stack handles the certificate/authentication.
But regardless I think you're better off responding with an error if the certificate is invalid (even for resources that don't require authentication), so that the user gets a consistent failure. Otherwise, they may not understand or know the distinction about the Service Root - and will get confused as to why it "works here but not there"...
Jeff
|
|
|
Post by jautor on Oct 16, 2018 18:46:27 GMT
We're having some conversations about this to make sure there's agreement on what the approach was supposed to be... Stay tuned, I want to survey some implementations before we declare a single, correct answer on this.
Jeff
|
|
|
Post by jautor on Oct 4, 2018 20:15:19 GMT
Good suggestion! As IBM is a member of the Redfish Forum, I'll ask them to provide their input on this and give us the most appropriate definitions and descriptions for architecture and the instruction set enumeration(s).
Jeff
|
|
|
Post by jautor on Sept 4, 2018 19:47:25 GMT
The payload should return the "error" object (which comes from the OData specification definition...) but you can use the "Base.1.0.Success" message in the "code" so that it's at least not buried in something related to GeneralError. So:
But it's a very good point that this is not shown in the Redfish specification as an example, so I've asked that an example of Success be added to the document for clarification.
Jeff
|
|