From dce4ccc69501dcfa25f023cb9888386559131b51 Mon Sep 17 00:00:00 2001 From: Andrew Geissler Date: Thu, 17 Jan 2019 13:56:20 -0600 Subject: Miscellaneous formatting clean up Fixed some numbering and tried to make the spacing between redfish sections consistent. Change-Id: Icda3ae4183d52a6f9fedf0e639a4111dabec3c40 Signed-off-by: Andrew Geissler --- DEVELOPING.md | 909 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 457 insertions(+), 452 deletions(-) (limited to 'DEVELOPING.md') diff --git a/DEVELOPING.md b/DEVELOPING.md index 895f50f63f..218747cef8 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -50,8 +50,7 @@ Where possible, 307 and 308 redirects should be avoided, as they introduce the possibility for subtle security bugs. - -4. ### Startup times +5. ### Startup times Given that the most common target of OpenBMC is an ARM11 processor, care needs to be taken to ensure startup times are low. In general this means: @@ -63,7 +62,7 @@ storage. - Avoid excessive memory usage and mallocs at startup. -5. ### Compiler features +6. ### Compiler features - At this point in time, the webserver sets a number of security flags in compile time options to prevent misuse. The specific flags and what optimization levels they are enabled at are documented in the @@ -77,7 +76,7 @@ - Run time type information is disabled - Link time optimization is enabled -5. ### Authentication +7. ### Authentication The webserver shall provide the following authentication mechanisms. - Basic authentication - Cookie authentication @@ -88,11 +87,11 @@ authentication scheme that is in line with the rest of OpenBMC, and allows users and privileges to be provisioned from other interfaces. -6. ### Web security +8. ### Web security The OpenBMC webserver shall follow the latest OWASP recommendations for authentication, session management, and security. -7. ### Performance +9. ### Performance The performance priorities for the OpenBMC webserver are (in order): 1. Code is readable and clear 2. Code follows secure guidelines @@ -102,467 +101,473 @@ resources, unless required to meet performance targets. (example: caching sensor values which are expected to change regularly) -8. ### Abstraction/interfacing +10. ### Abstraction/interfacing In general, the OpenBMC webserver is built using the data driven design. Abstraction and Interface guarantees should be used when multiple implementations exist, but for implementations where only a single implementation exists, prefer to make the code correct and clean rather than implement a concrete interface. -9. ### phosphor webui +11. ### phosphor webui The webserver should be capable of hosting phosphor-webui, and impelmenting the required flows to host the application. In general, all access methods should be available to the webui. -10. ### Redfish +12. ### Redfish -The redfish implementation shall pass the [Redfish Service -Validator](https://github.com/DMTF/Redfish-Service-Validator "Validator") with -no warnings or errors + The redfish implementation shall pass the [Redfish Service + Validator](https://github.com/DMTF/Redfish-Service-Validator "Validator") with + no warnings or errors -The following redfish schemas and fields are targeted for OpenBMC. This is a -living document, and these schemas are subject to change. + The following redfish schemas and fields are targeted for OpenBMC. This is a + living document, and these schemas are subject to change. + + Fields common to all schemas + + - @odata.context + - @odata.id + - @odata.type + - Id + - Name + + + #### /redfish/v1/ + ##### ServiceRoot + + - RedfishVersion + - UUID + + + #### /redfish/v1/AccountService/ + ##### AccountService + + - Description + - ServiceEnabled + - MinpasswordLength + - MaxPasswordLength + - Accounts + - Roles + + #### /redfish/v1/AccountService/Accounts/ + ##### AccountCollection + + - Description + - Members@odata.count + - Members + + #### /redfish/v1/AccountService/Accounts/ + ##### Account + + - Description + - Enabled + - Password + - UserName + - RoleId + - Links/Role + + #### /redfish/v1/AccountService/Roles/ + ##### RoleCollection + + - Description + - Members@odata.count + - Members + - By default will contain 3 roles, "Administrator", "Operator", and "User" + + #### /redfish/v1/AccountService/Roles/ + ##### Role + + - Description + - IsPredefined + - Will be set to true for all default roles. If the given role is + non-default, or has been modified from default, will be marked as false. + - AssignedPrivileges + - For the default roles, the following privileges will be assigned by + default + - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf, + ConfigureComponents + - Operator: Login, ConfigureComponents + - User: Login + + + #### /redfish/v1/Chassis + ##### ChassisCollection + + - Members@odata.count + - Members + + #### /redfish/v1/Chassis/ + ##### Chassis + + - ChassisType + - Manufacturer + - Model + - SerialNumber + - PartNumber + - PowerState + - Thermal + - Shall be included if component contains temperature sensors, otherwise + shall be omitted. + - Power + - Shall be included if component contains voltage/current sensing + components, otherwise will be omitted. + + #### /redfish/v1/Chassis//Thermal + ##### Thermal + Temperatures Fans Redundancy + + #### /redfish/v1/Chassis//Thermal#/Temperatures/ + ##### Temperature + - MemberId + - Status + - ReadingCelsius + - UpperThresholdNonCritical + - UpperThresholdCritical + - LowerThresholdNonCritical + - LowerThresholdCritical + - MinReadingRange + - MaxReadingRange + + *threshold fields only present if defined for sensor, otherwise absent* + + #### /redfish/v1/Chassis//Thermal#/Fans/ + ##### Fan + - MemberId + - Status + - Reading + - ReadingUnits + - UpperThresholdNonCritical + - UpperThresholdCritical + - LowerThresholdNonCritical + - LowerThresholdCritical + - MinReadingRange + - MaxReadingRange + - Redundancy + + *threshold fields only present if defined for sensor, otherwise absent* + + #### /redfish/v1/Chassis//Thermal#/Redundancy/ + ##### Fan + - MemberId + - RedundancySet + - Mode + - Status + - MinNumNeeded + - MaxNumSupported + + + #### /redfish/v1/Chassis//Power/ + ##### Thermal + PowerControl Voltages PowerSupplies Redundancy + + #### /redfish/v1/Chassis//Power#/PowerControl/ + ##### PowerControl + - MemberId + - PowerConsumedWatts + - PowerMetrics/IntervalInMin + - PowerMetrics/MinConsumedWatts + - PowerMetrics/MaxConsumedWatts + - PowerMetrics/AverageConsumedWatts + - RelatedItem + - Should list systems and related chassis + + #### /redfish/v1/Chassis//Power#/Voltages/ + ##### Voltage + - MemberId + - Status + - ReadingVolts + - UpperThresholdNonCritical + - UpperThresholdCritical + - LowerThresholdNonCritical + - LowerThresholdCritical + - MinReadingRange + - MaxReadingRange + - PhysicalContext + - RelatedItem + + #### /redfish/v1/Chassis//Power#/PowerSupplies/ + ##### PowerSupply + - MemberId + - Status + - LininputVoltage + - Model + - manufacturer + - FirmwareVersion + - SerialNumber + - PartNumber + - RelatedItem + - Redundancy + + #### /redfish/v1/Chassis/{ChassisName}/Power#/Redundancy/ + ##### Redundancy + - MemberId + - RedundancySet + - Mode + - Status + - MinNumNeeded + - MaxNumSupported + + + #### /redfish/v1/EventService + ##### EventService + - Id + - ServiceEnabled + - DeliveryRetryAttempts + - Defaults to 3 + - EventTypesForSubscription + - Defaults to "Alert" + - Actions + - Subscriptions + + #### /redfish/v1/EventService/Subscriptions + ##### EventDestinationCollection + - Members@odata.count + - Members + + #### /redfish/v1/EventService/Subscriptions/{EventName}/ + ##### EventDestination + - Id + - Destination + - EventTypes + - Context + - OriginResources + - Protocol + + + #### /redfish/v1/Managers + ##### ManagerCollection + - Members + - Members@odata.count + + #### /redfish/v1/Managers/BMC + ##### Manager + - Description + - LogServices + - GraphicalConsole + - UUID + - Model + - Links + - PowerState + - FirmwareVersion + - ManagerType + - ServiceEntryPointUUID + - DateTime + - NetworkProtocol + - Actions + - Status + - SerialConsole + - VirtualMedia + - EthernetInterfaces + + #### /redfish/v1/Managers/BMC/EthernetInterfaces + ##### EthernetInterfaceCollection + - Members + - Members@odata.count + - Description + + #### /redfish/v1/Managers/BMC/EthernetInterfaces/{InterfaceName} + ##### EthernetInterface + - Description + - VLAN + - MaxIPv6StaticAddresses + + #### /redfish/v1/Managers/BMC/LogServices + ##### LogServiceCollection + - Members + - Members@odata.count + - Description + + #### /redfish/v1/Managers/BMC/LogServices/RedfishLog + ##### LogService + - Entries + - OverWritePolicy + - Actions + - Status + - DateTime + - MaxNumberOfRecords + + #### /redfish/v1/Managers/BMC/LogServices/RedfishLog/Entries/{entry} + ##### LogEntry + - Message + - Created + - EntryType + + #### /redfish/v1/Managers/BMC/NetworkProtocol + ##### ManagerNetworkProtocol + - Description + - SSDP + - HTTPS + - SSH + - VirtualMedia + - KVMIP + - Status + + + #### /redfish/v1/Registries + ##### MessageRegistryFileCollection + - Members + - Should support Base, CommonMessages, and EventingMessages + - Members@odata.count + - Description + + #### /redfish/v1/Registries/ + ##### MessageRegistryFile + - Location + - Description + - Location@odata.count + - Languages@odata.count + - Languages + - Registry + + + #### /redfish/v1/SessionService + ##### SessionService + - Description + - ServiceEnabled + - Status + - SessionTimeout + - Sessions + + #### /redfish/v1/SessionService/Sessions + ##### SessionCollection + - Members + - Members@odata.count + - Description + + + #### /redfish/v1/Systems + ##### ComputerSystemCollection + - Members + - Should support one system + - Members@odata.count + + #### /redfish/v1/Systems/{SystemName} + ##### ComputerSystem + - Boot + - PartNumber + - IndicatorLED + - UUID + - LogServices + - SystemType + - Manufacturer + - Description + - Model + - Links + - PowerState + - BiosVersion + - Storage + - SerialNumber + - Processors + - ProcessorSummary + - Memory + - Actions + - Status + - EthernetInterfaces + - MemorySummary + + #### /redfish/v1/Systems/{SystemName}/EthernetInterfaces + ##### EthernetInterfaceCollection + - Members + - Members@odata.count + - Description + + #### /redfish/v1/Systems/{SystemName}/LogServices + ##### LogServiceCollection + - Members + - Should default to one member, named SEL + - Members@odata.count + - Description + + #### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries + ##### LogEntryCollection + - Members + - Members@odata.count + - Description + - @odata.nextLink + + #### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries/{entryNumber} + ##### LogEntry + - MessageArgs + - Severity + - SensorType + - Message + - MessageId + - Created + - EntryCode + - EntryType + + #### /redfish/v1/Systems/{SystemName}/Memory + ##### MemoryCollection + - Members + - Members@odata.count + + #### /redfish/v1/Systems/{SystemName}/Memory/Memory1 + ##### Memory + - MemoryType + - Description + - DeviceLocator + - Oem + - Metrics + - BaseModuleType + - Manufacturer + - MemoryDeviceType + - RankCount + - AllowedSpeedsMHz + - CapacityMiB + - DataWidthBits + - SerialNumber + - OperatingSpeedMhz + - ErrorCorrection + - PartNumber + - Status + - BusWidthBits + - MemoryMedia + + #### /redfish/v1/Systems/{SystemName}/Memory/Memory1/MemoryMetrics + ##### MemoryMetrics + - Description + - HealthData + + #### /redfish/v1/Systems/{SystemName}/Processors + ##### ProcessorCollection + - Members + - Should Support CPU1 and CPU2 for dual socket systems + - Members@odata.count + + #### /redfish/v1/Systems/{SystemName}/Processors/{CPUName} + ##### Processor + - ProcessorArchitecture + - TotalCores + - ProcessorId + - MaxSpeedMHz + - Manufacturer + - Status + - Socket + - InstructionSet + - Model + - ProcessorType + - TotalThreads + + #### /redfish/v1/Systems/{SystemName}/Storage + ##### StorageCollection + - Members + - Members@odata.count -Fields common to all schemas - -- @odata.context -- @odata.id -- @odata.type -- Id -- Name + #### /redfish/v1/Systems/{SystemName}/Storage/{storageIndex> + ##### Storage + - Drives + - Links -#### /redfish/v1/ -##### ServiceRoot - -- RedfishVersion -- UUID - -#### /redfish/v1/AccountService/ -##### AccountService - -- Description -- ServiceEnabled -- MinpasswordLength -- MaxPasswordLength -- Accounts -- Roles - -#### /redfish/v1/AccountService/Accounts/ -##### AccountCollection - -- Description -- Members@odata.count -- Members - -#### /redfish/v1/AccountService/Accounts/ -##### Account - -- Description -- Enabled -- Password -- UserName -- RoleId -- Links/Role - -#### /redfish/v1/AccountService/Roles/ -##### RoleCollection - -- Description -- Members@odata.count -- Members - - By default will contain 3 roles, "Administrator", "Operator", and "User" - - -#### /redfish/v1/AccountService/Roles/ -##### Role - -- Description -- IsPredefined - - Will be set to true for all default roles. If the given role is - non-default, or has been modified from default, will be marked as false. -- AssignedPrivileges - - For the default roles, the following privileges will be assigned by - default - - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf, - ConfigureComponents - - Operator: Login, ConfigureComponents - - User: Login - -#### /redfish/v1/Chassis -##### ChassisCollection - -- Members@odata.count -- Members - -#### /redfish/v1/Chassis/ -##### Chassis - -- ChassisType -- Manufacturer -- Model -- SerialNumber -- PartNumber -- PowerState -- Thermal - - Shall be included if component contains temperature sensors, otherwise - shall be omitted. -- Power - - Shall be included if component contains voltage/current sensing - components, otherwise will be omitted. - - -#### /redfish/v1/Chassis//Thermal -##### Thermal -Temperatures Fans Redundancy - - -#### /redfish/v1/Chassis//Thermal#/Temperatures/ -##### Temperature -- MemberId -- Status -- ReadingCelsius -- UpperThresholdNonCritical -- UpperThresholdCritical -- LowerThresholdNonCritical -- LowerThresholdCritical -- MinReadingRange -- MaxReadingRange - -*threshold fields only present if defined for sensor, otherwise absent* - -#### /redfish/v1/Chassis//Thermal#/Fans/ -##### Fan -- MemberId -- Status -- Reading -- ReadingUnits -- UpperThresholdNonCritical -- UpperThresholdCritical -- LowerThresholdNonCritical -- LowerThresholdCritical -- MinReadingRange -- MaxReadingRange -- Redundancy - -*threshold fields only present if defined for sensor, otherwise absent* - -#### /redfish/v1/Chassis//Thermal#/Redundancy/ -##### Fan -- MemberId -- RedundancySet -- Mode -- Status -- MinNumNeeded -- MaxNumSupported - - -#### /redfish/v1/Chassis//Power/ -##### Thermal -PowerControl Voltages PowerSupplies Redundancy - -#### /redfish/v1/Chassis//Power#/PowerControl/ -##### PowerControl -- MemberId -- PowerConsumedWatts -- PowerMetrics/IntervalInMin -- PowerMetrics/MinConsumedWatts -- PowerMetrics/MaxConsumedWatts -- PowerMetrics/AverageConsumedWatts -- RelatedItem - - Should list systems and related chassis - - -#### /redfish/v1/Chassis//Power#/Voltages/ -##### Voltage -- MemberId -- Status -- ReadingVolts -- UpperThresholdNonCritical -- UpperThresholdCritical -- LowerThresholdNonCritical -- LowerThresholdCritical -- MinReadingRange -- MaxReadingRange -- PhysicalContext -- RelatedItem - -#### /redfish/v1/Chassis//Power#/PowerSupplies/ -##### PowerSupply -- MemberId -- Status -- LininputVoltage -- Model -- manufacturer -- FirmwareVersion -- SerialNumber -- PartNumber -- RelatedItem -- Redundancy - -#### /redfish/v1/Chassis/{ChassisName}/Power#/Redundancy/ -##### Redundancy -- MemberId -- RedundancySet -- Mode -- Status -- MinNumNeeded -- MaxNumSupported - - -#### /redfish/v1/EventService -##### EventService -- Id -- ServiceEnabled -- DeliveryRetryAttempts - - Defaults to 3 -- EventTypesForSubscription - - Defaults to "Alert" -- Actions -- Subscriptions - -#### /redfish/v1/EventService/Subscriptions -##### EventDestinationCollection -- Members@odata.count -- Members - -#### /redfish/v1/EventService/Subscriptions/{EventName}/ -##### EventDestination -- Id -- Destination -- EventTypes -- Context -- OriginResources -- Protocol - -#### /redfish/v1/Managers -##### ManagerCollection -- Members -- Members@odata.count - -#### /redfish/v1/Managers/BMC -##### Manager -- Description -- LogServices -- GraphicalConsole -- UUID -- Model -- Links -- PowerState -- FirmwareVersion -- ManagerType -- ServiceEntryPointUUID -- DateTime -- NetworkProtocol -- Actions -- Status -- SerialConsole -- VirtualMedia -- EthernetInterfaces - -#### /redfish/v1/Managers/BMC/EthernetInterfaces -##### EthernetInterfaceCollection -- Members -- Members@odata.count -- Description - -#### /redfish/v1/Managers/BMC/EthernetInterfaces/{InterfaceName} -##### EthernetInterface -- Description -- VLAN -- MaxIPv6StaticAddresses - -#### /redfish/v1/Managers/BMC/LogServices -##### LogServiceCollection -- Members -- Members@odata.count -- Description - -#### /redfish/v1/Managers/BMC/LogServices/RedfishLog -##### LogService -- Entries -- OverWritePolicy -- Actions -- Status -- DateTime -- MaxNumberOfRecords - -#### /redfish/v1/Managers/BMC/LogServices/RedfishLog/Entries/{entry} -##### LogEntry -- Message -- Created -- EntryType - -#### /redfish/v1/Managers/BMC/NetworkProtocol -##### ManagerNetworkProtocol -- Description -- SSDP -- HTTPS -- SSH -- VirtualMedia -- KVMIP -- Status - -#### /redfish/v1/Registries -##### MessageRegistryFileCollection -- Members - - Should support Base, CommonMessages, and EventingMessages -- Members@odata.count -- Description - -#### /redfish/v1/Registries/ -##### MessageRegistryFile -- Location -- Description -- Location@odata.count -- Languages@odata.count -- Languages -- Registry - -#### /redfish/v1/SessionService -##### SessionService -- Description -- ServiceEnabled -- Status -- SessionTimeout -- Sessions - -#### /redfish/v1/SessionService/Sessions -##### SessionCollection -- Members -- Members@odata.count -- Description - -#### /redfish/v1/Systems -##### ComputerSystemCollection -- Members - - Should support one system -- Members@odata.count - -#### /redfish/v1/Systems/{SystemName} -##### ComputerSystem -- Boot -- PartNumber -- IndicatorLED -- UUID -- LogServices -- SystemType -- Manufacturer -- Description -- Model -- Links -- PowerState -- BiosVersion -- Storage -- SerialNumber -- Processors -- ProcessorSummary -- Memory -- Actions -- Status -- EthernetInterfaces -- MemorySummary - -#### /redfish/v1/Systems/{SystemName}/EthernetInterfaces -##### EthernetInterfaceCollection -- Members -- Members@odata.count -- Description - -#### /redfish/v1/Systems/{SystemName}/LogServices -##### LogServiceCollection -- Members - - Should default to one member, named SEL -- Members@odata.count -- Description - -#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries -##### LogEntryCollection -- Members -- Members@odata.count -- Description -- @odata.nextLink - -#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries/{entryNumber} -##### LogEntry -- MessageArgs -- Severity -- SensorType -- Message -- MessageId -- Created -- EntryCode -- EntryType - -#### /redfish/v1/Systems/{SystemName}/Memory -##### MemoryCollection -- Members -- Members@odata.count - -#### /redfish/v1/Systems/{SystemName}/Memory/Memory1 -##### Memory -- MemoryType -- Description -- DeviceLocator -- Oem -- Metrics -- BaseModuleType -- Manufacturer -- MemoryDeviceType -- RankCount -- AllowedSpeedsMHz -- CapacityMiB -- DataWidthBits -- SerialNumber -- OperatingSpeedMhz -- ErrorCorrection -- PartNumber -- Status -- BusWidthBits -- MemoryMedia - -#### /redfish/v1/Systems/{SystemName}/Memory/Memory1/MemoryMetrics -##### MemoryMetrics -- Description -- HealthData - -#### /redfish/v1/Systems/{SystemName}/Processors -##### ProcessorCollection -- Members - - Should Support CPU1 and CPU2 for dual socket systems -- Members@odata.count - -#### /redfish/v1/Systems/{SystemName}/Processors/{CPUName} -##### Processor -- ProcessorArchitecture -- TotalCores -- ProcessorId -- MaxSpeedMHz -- Manufacturer -- Status -- Socket -- InstructionSet -- Model -- ProcessorType -- TotalThreads - -#### /redfish/v1/Systems/{SystemName}/Storage -##### StorageCollection -- Members -- Members@odata.count - #### /redfish/v1/Systems/{SystemName}/Storage/{storageIndex> -##### Storage -- Drives -- Links + #### /redfish/v1/UpdateService + ##### UpdateService + - SoftwareInventory -#### /redfish/v1/UpdateService -##### UpdateService -- SoftwareInventory #### /redfish/v1/UpdateService/SoftwareInventory -##### SoftwareInventoryCollection -- Members -- Should Support BMC, ME, CPLD and BIOS -- Members@odata.count + ##### SoftwareInventoryCollection + - Members + - Should Support BMC, ME, CPLD and BIOS + - Members@odata.count + #### /redfish/v1/UpdateService/SoftwareInventory/{MemberName} -##### SoftwareInventory -- Version + ##### SoftwareInventory + - Version -- cgit v1.2.3