1#OpenBMC Webserver Development 2 31. ### Performance targets 4 As OpenBMC is intended to be deployed on an embedded system, care should be 5 taken to avoid expensive constructs, and memory usage. In general, our 6 performance and metric targets are: 7 8 - Binaries and static files should take up < 1MB of filesystem size 9 - Memory usage should remain below 10MB at all times 10 - Application startup time should be less than 1 second on target hardware 11 (AST2500) 12 132. ### Asyncronous programming 14 Care should be taken to ensure that all code is written to be asyncronous in 15 nature, to avoid blocking methods from stopping the processing of other 16 tasks. At this time the webserver uses boost::asio for it async framework. 17 Threads should be avoided if possible, and instead use async tasks within 18 boost::asio. 19 203. ### Secure coding guidelines 21 Secure coding practices should be followed in all places in the webserver 22 23 In general, this means: 24 - All buffer boundaries must be checked before indexing or using values 25 - All pointers and iterators must be checked for null before dereferencing 26 - All input from outside the application is considered untrusted, and should 27 be escaped, authorized and filtered accordingly. This includes files in 28 the filesystem. 29 - All error statuses are checked and accounted for in control flow. 30 - Where applicable, noexcept methods should be preferred to methods that use 31 exceptions 32 - Explicitly bounded types should be preferred over implicitly bounded types 33 (like std::array<int, size> as opposed to int[size]) 34 - no use of [Banned 35 functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions 36 "Banned function list") 37 384. ### Error handling 39 Error handling should be constructed in such a way that all possible errors 40 return valid HTTP responses. The following HTTP codes will be used commonly 41 - 200 OK - Request was properly handled 42 - 201 Created - Resource was created 43 - 401 Unauthorized - Request didn't posses the necessary authentication 44 - 403 Forbidden - Request was authenticated, but did not have the necessary 45 permissions to accomplish the requested task 46 - 404 Not found - The url was not found 47 - 500 Internal error - Something has broken within the OpenBMC web server, 48 and should be filed as a bug 49 50 Where possible, 307 and 308 redirects should be avoided, as they introduce 51 the possibility for subtle security bugs. 52 53 544. ### Startup times 55 Given that the most common target of OpenBMC is an ARM11 processor, care 56 needs to be taken to ensure startup times are low. In general this means: 57 58 - Minimizing the number of files read from disk at startup. Unless a 59 feature is explicitly intended to be runtime configurable, its logic 60 should be "baked in" to the application at compile time. For cases where 61 the implementation is configurable at runtime, the default values should 62 be included in application code to minimize the use of nonvolatile 63 storage. 64 - Avoid excessive memory usage and mallocs at startup. 65 665. ### Compiler features 67 - At this point in time, the webserver sets a number of security flags in 68 compile time options to prevent misuse. The specific flags and what 69 optimization levels they are enabled at are documented in the 70 CMakeLists.txt file. 71 - Exceptions are currently enabled for webserver builds, but their use is 72 discouraged. Long term, the intent is to disable exceptions, so any use 73 of them for explicit control flow will likely be rejected in code review. 74 Any use of exceptions should be cases where the program can be reasonably 75 expected to crash if the exception occurs, as this will be the future 76 behavior once exceptions are disabled. 77 - Run time type information is disabled 78 - Link time optimization is enabled 79 805. ### Authentication 81 The webserver shall provide the following authentication mechanisms. 82 - Basic authentication 83 - Cookie authentication 84 - Token authentication 85 86 There shall be connection between the authentication mechanism used and 87 resources that are available over it. The webserver shall employ an 88 authentication scheme that is in line with the rest of OpenBMC, and allows 89 users and privileges to be provisioned from other interfaces. 90 916. ### Web security 92 The OpenBMC webserver shall follow the latest OWASP recommendations for 93 authentication, session management, and security. 94 957. ### Performance 96 The performance priorities for the OpenBMC webserver are (in order): 97 1. Code is readable and clear 98 2. Code follows secure guidelines 99 3. Code is performant, and does not unnecessarily abstract concepts at the 100 expense of performance 101 4. Code does not employ constructs which require continuous system 102 resources, unless required to meet performance targets. (example: 103 caching sensor values which are expected to change regularly) 104 1058. ### Abstraction/interfacing 106 In general, the OpenBMC webserver is built using the data driven design. 107 Abstraction and Interface gaurentees should be used when multiple 108 implementations exist, but for implementations where only a single 109 implementation exists, prefer to make the code correct and clean rather than 110 implement a concrete interface. 111 1129. ### phosphor webui 113 The webserver should be capable of hosting phosphor-webui, and impelmenting 114 the required flows to host the application. In general, all access methods 115 should be available to the webui. 116 11710. ### Redfish 118 119The redfish implementation shall pass the [Redfish Service 120Validator](https://github.com/DMTF/Redfish-Service-Validator "Validator") with 121no warnings or errors 122 123The following redfish schemas and fields are targeted for OpenBMC. This is a 124living document, and these schemas are subject to change. 125 126Fields common to all schemas 127 128- @odata.context 129- @odata.id 130- @odata.type 131- Id 132- Name 133 134 135#### /redfish/v1/ 136##### ServiceRoot 137 138- RedfishVersion 139- UUID 140 141#### /redfish/v1/AccountService/ 142##### AccountService 143 144- Description 145- ServiceEnabled 146- MinpasswordLength 147- MaxPasswordLength 148- Accounts 149- Roles 150 151#### /redfish/v1/AccountService/Accounts/ 152##### AccountCollection 153 154- Description 155- Members@odata.count 156- Members 157 158#### /redfish/v1/AccountService/Accounts/<AccountName> 159##### Account 160 161- Description 162- Enabled 163- Password 164- UserName 165- RoleId 166- Links/Role 167 168#### /redfish/v1/AccountService/Roles/ 169##### RoleCollection 170 171- Description 172- Members@odata.count 173- Members 174 - By default will contain 3 roles, "Administrator", "Operator", and "User" 175 176 177#### /redfish/v1/AccountService/Roles/<RoleName> 178##### Role 179 180- Description 181- IsPredefined 182 - Will be set to true for all default roles. If the given role is 183 non-default, or has been modified from default, will be marked as false. 184- AssignedPrivileges 185 - For the default roles, the following privileges will be assigned by 186 default 187 - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf, 188 ConfigureComponents 189 - Operator: Login, ConfigureComponents 190 - User: Login 191 192#### /redfish/v1/Chassis 193##### ChassisCollection 194 195- Members@odata.count 196- Members 197 198#### /redfish/v1/Chassis/<ChassisName> 199##### Chassis 200 201- ChassisType 202- Manufacturer 203- Model 204- SerialNumber 205- PartNumber 206- PowerState 207- Thermal 208 - Shall be included if component contains temperature sensors, otherwise 209 shall be omited. 210- Power 211 - Shall be included if component contains voltage/current sensing 212 components, otherwise will be omited. 213 214 215#### /redfish/v1/Chassis/<ChassisName>/Thermal 216##### Thermal 217Temperatures Fans Redundancy 218 219 220#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Temperatures/<SensorName> 221##### Temperature 222- MemberId 223- Status 224- ReadingCelsius 225- UpperThresholdNonCritical 226- UpperThresholdCritical 227- LowerThresholdNonCritical 228- LowerThresholdCritical 229- MinReadingRange 230- MaxReadingRange 231 232*threshold fields only present if defined for sensor, otherwise absent* 233 234#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Fans/<FanName> 235##### Fan 236- MemberId 237- Status 238- Reading 239- ReadingUnits 240- UpperThresholdNonCritical 241- UpperThresholdCritical 242- LowerThresholdNonCritical 243- LowerThresholdCritical 244- MinReadingRange 245- MaxReadingRange 246- Redundancy 247 248*threshold fields only present if defined for sensor, otherwise absent* 249 250#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Redundancy/<RedundancyName> 251##### Fan 252- MemberId 253- RedundancySet 254- Mode 255- Status 256- MinNumNeeded 257- MaxNumSupported 258 259 260#### /redfish/v1/Chassis/<ChassisName>/Power/ 261##### Thermal 262PowerControl Voltages PowerSupplies Redundancy 263 264#### /redfish/v1/Chassis/<ChassisName>/Power#/PowerControl/<ControlName> 265##### PowerControl 266- MemberId 267- PowerConsumedWatts 268- PowerMetrics/IntervalInMin 269- PowerMetrics/MinConsumedWatts 270- PowerMetrics/MaxConsumedWatts 271- PowerMetrics/AverageConsumedWatts 272- RelatedItem 273 - Should list systems and related chassis 274 275 276#### /redfish/v1/Chassis/<ChassisName>/Power#/Voltages/<VoltageName> 277##### Voltage 278- MemberId 279- Status 280- ReadingVolts 281- UpperThresholdNonCritical 282- UpperThresholdCritical 283- LowerThresholdNonCritical 284- LowerThresholdCritical 285- MinReadingRange 286- MaxReadingRange 287- PhysicalContext 288- RelatedItem 289 290#### /redfish/v1/Chassis/<ChassisName>/Power#/PowerSupplies/<PSUName> 291##### PowerSupply 292- MemberId 293- Status 294- LininputVoltage 295- Model 296- manufacturer 297- FirmwareVersion 298- SerialNumber 299- PartNumber 300- RelatedItem 301- Redundancy 302 303#### /redfish/v1/Chassis/{ChassisName}/Power#/Redundancy/<RedundancyName> 304##### Redundancy 305- MemberId 306- RedundancySet 307- Mode 308- Status 309- MinNumNeeded 310- MaxNumSupported 311 312 313#### /redfish/v1/EventService 314##### EventService 315- Id 316- ServiceEnabled 317- DeliveryRetryAttempts 318 - Defaults to 3 319- EventTypesForSubscription 320 - Defaults to "Alert" 321- Actions 322- Subscriptions 323 324#### /redfish/v1/EventService/Subscriptions 325##### EventDestinationCollection 326- Members@odata.count 327- Members 328 329#### /redfish/v1/EventService/Subscriptions/{EventName}/ 330##### EventDestination 331- Id 332- Destination 333- EventTypes 334- Context 335- OriginResources 336- Protocol 337 338#### /redfish/v1/Managers 339##### ManagerCollection 340- Members 341- Members@odata.count 342 343#### /redfish/v1/Managers/BMC 344##### Manager 345- Description 346- LogServices 347- GraphicalConsole 348- UUID 349- Model 350- Links 351- PowerState 352- FirmwareVersion 353- ManagerType 354- ServiceEntryPointUUID 355- DateTime 356- NetworkProtocol 357- Actions 358- Status 359- SerialConsole 360- VirtualMedia 361- EthernetInterfaces 362 363#### /redfish/v1/Managers/BMC/EthernetInterfaces 364##### EthernetInterfaceCollection 365- Members 366- Members@odata.count 367- Description 368 369#### /redfish/v1/Managers/BMC/EthernetInterfaces/{InterfaceName} 370##### EthernetInterface 371- Description 372- VLAN 373- MaxIPv6StaticAddresses 374 375#### /redfish/v1/Managers/BMC/LogServices 376##### LogServiceCollection 377- Members 378- Members@odata.count 379- Description 380 381#### /redfish/v1/Managers/BMC/LogServices/RedfishLog 382##### LogService 383- Entries 384- OverWritePolicy 385- Actions 386- Status 387- DateTime 388- MaxNumberOfRecords 389 390#### /redfish/v1/Managers/BMC/LogServices/RedfishLog/Entries/{entry} 391##### LogEntry 392- Message 393- Created 394- EntryType 395 396#### /redfish/v1/Managers/BMC/NetworkProtocol 397##### ManagerNetworkProtocol 398- Description 399- SSDP 400- HTTPS 401- SSH 402- VirtualMedia 403- KVMIP 404- Status 405 406#### /redfish/v1/Registries 407##### MessageRegistryFileCollection 408- Members 409 - Should support Base, CommonMessages, and EventingMessages 410- Members@odata.count 411- Description 412 413#### /redfish/v1/Registries/<MessageRegistry> 414##### MessageRegistryFile 415- Location 416- Description 417- Location@odata.count 418- Languages@odata.count 419- Languages 420- Registry 421 422#### /redfish/v1/SessionService 423##### SessionService 424- Description 425- ServiceEnabled 426- Status 427- SessionTimeout 428- Sessions 429 430#### /redfish/v1/SessionService/Sessions 431##### SessionCollection 432- Members 433- Members@odata.count 434- Description 435 436#### /redfish/v1/Systems 437##### ComputerSystemCollection 438- Members 439 - Should support one system 440- Members@odata.count 441 442#### /redfish/v1/Systems/{SystemName} 443##### ComputerSystem 444- Boot 445- PartNumber 446- IndicatorLED 447- UUID 448- LogServices 449- SystemType 450- Manufacturer 451- Description 452- Model 453- Links 454- PowerState 455- BiosVersion 456- Storage 457- SerialNumber 458- Processors 459- ProcessorSummary 460- Memory 461- Actions 462- Status 463- EthernetInterfaces 464- MemorySummary 465 466#### /redfish/v1/Systems/{SystemName}/EthernetInterfaces 467##### EthernetInterfaceCollection 468- Members 469- Members@odata.count 470- Description 471 472#### /redfish/v1/Systems/{SystemName}/LogServices 473##### LogServiceCollection 474- Members 475 - Should default to one member, named SEL 476- Members@odata.count 477- Description 478 479#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries 480##### LogEntryCollection 481- Members 482- Members@odata.count 483- Description 484- @odata.nextLink 485 486#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries/{entryNumber} 487##### LogEntry 488- MessageArgs 489- Severity 490- SensorType 491- Message 492- MessageId 493- Created 494- EntryCode 495- EntryType 496 497#### /redfish/v1/Systems/{SystemName}/Memory 498##### MemoryCollection 499- Members 500- Members@odata.count 501 502#### /redfish/v1/Systems/{SystemName}/Memory/Memory1 503##### Memory 504- MemoryType 505- Description 506- DeviceLocator 507- Oem 508- Metrics 509- BaseModuleType 510- Manufacturer 511- MemoryDeviceType 512- RankCount 513- AllowedSpeedsMHz 514- CapacityMiB 515- DataWidthBits 516- SerialNumber 517- OperatingSpeedMhz 518- ErrorCorrection 519- PartNumber 520- Status 521- BusWidthBits 522- MemoryMedia 523 524#### /redfish/v1/Systems/{SystemName}/Memory/Memory1/MemoryMetrics 525##### MemoryMetrics 526- Description 527- HealthData 528 529#### /redfish/v1/Systems/{SystemName}/Processors 530##### ProcessorCollection 531- Members 532 - Should Support CPU1 and CPU2 for dual socket systems 533- Members@odata.count 534 535#### /redfish/v1/Systems/{SystemName}/Processors/{CPUName} 536##### Processor 537- ProcessorArchitecture 538- TotalCores 539- ProcessorId 540- MaxSpeedMHz 541- Manufacturer 542- Status 543- Socket 544- InstructionSet 545- Model 546- ProcessorType 547- TotalThreads 548 549#### /redfish/v1/Systems/{SystemName}/Storage 550##### StorageCollection 551- Members 552- Members@odata.count 553 #### /redfish/v1/Systems/{SystemName}/Storage/{storageIndex> 554##### Storage 555- Drives 556- Links 557 558#### /redfish/v1/UpdateService 559##### UpdateService 560- SoftwareInventory 561 #### /redfish/v1/UpdateService/SoftwareInventory 562##### SoftwareInventoryCollection 563- Members 564- Should Support BMC, ME, CPLD and BIOS 565- Members@odata.count 566 #### /redfish/v1/UpdateService/SoftwareInventory/{MemberName} 567##### SoftwareInventory 568- Version 569