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. ### Asynchronous programming 14 Care should be taken to ensure that all code is written to be asynchronous 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 535. ### Startup times 54 Given that the most common target of OpenBMC is an ARM11 processor, care 55 needs to be taken to ensure startup times are low. In general this means: 56 57 - Minimizing the number of files read from disk at startup. Unless a 58 feature is explicitly intended to be runtime configurable, its logic 59 should be "baked in" to the application at compile time. For cases where 60 the implementation is configurable at runtime, the default values should 61 be included in application code to minimize the use of nonvolatile 62 storage. 63 - Avoid excessive memory usage and mallocs at startup. 64 656. ### Compiler features 66 - At this point in time, the webserver sets a number of security flags in 67 compile time options to prevent misuse. The specific flags and what 68 optimization levels they are enabled at are documented in the 69 CMakeLists.txt file. 70 - Exceptions are currently enabled for webserver builds, but their use is 71 discouraged. Long term, the intent is to disable exceptions, so any use 72 of them for explicit control flow will likely be rejected in code review. 73 Any use of exceptions should be cases where the program can be reasonably 74 expected to crash if the exception occurs, as this will be the future 75 behavior once exceptions are disabled. 76 - Run time type information is disabled 77 - Link time optimization is enabled 78 797. ### Authentication 80 The webserver shall provide the following authentication mechanisms. 81 - Basic authentication 82 - Cookie authentication 83 - Token authentication 84 85 There shall be connection between the authentication mechanism used and 86 resources that are available over it. The webserver shall employ an 87 authentication scheme that is in line with the rest of OpenBMC, and allows 88 users and privileges to be provisioned from other interfaces. 89 908. ### Web security 91 The OpenBMC webserver shall follow the latest OWASP recommendations for 92 authentication, session management, and security. 93 949. ### Performance 95 TLS uses cipher suites from the "OWASP Cipher String 'B'" to maintain as 96 much compatibility as we can with modern browsers, while still keeping a 97 strong security posture. 98 99 The performance priorities for the OpenBMC webserver are (in order): 100 1. Code is readable and clear 101 2. Code follows secure guidelines 102 3. Code is performant, and does not unnecessarily abstract concepts at the 103 expense of performance 104 4. Code does not employ constructs which require continuous system 105 resources, unless required to meet performance targets. (example: 106 caching sensor values which are expected to change regularly) 107 10810. ### Abstraction/interfacing 109 In general, the OpenBMC webserver is built using the data driven design. 110 Abstraction and Interface guarantees should be used when multiple 111 implementations exist, but for implementations where only a single 112 implementation exists, prefer to make the code correct and clean rather than 113 implement a concrete interface. 114 11511. ### phosphor webui 116 The webserver should be capable of hosting phosphor-webui, and impelmenting 117 the required flows to host the application. In general, all access methods 118 should be available to the webui. 119 12012. ### Developing and Testing 121 There are a variety of ways to develop and test bmcweb software changes. 122 Here are the steps for using the SDK and QEMU. 123 124 - Follow all [development environment setup](https://github.com/openbmc/docs/blob/master/development/dev-environment.md) 125 directions in the development environment setup document. This will get 126 QEMU started up and you in the SDK environment. 127 - Follow all of the [gerrit setup](https://github.com/openbmc/docs/blob/master/development/gerrit-setup.md) 128 directions in the gerrit setup document. 129 - Clone bmcweb from gerrit 130 ``` 131 git clone ssh://openbmc.gerrit/bmcweb/ 132 ``` 133 134 - Ensure it compiles 135 ``` 136 cmake ./ && make 137 ``` 138 **Note:** If you'd like to enable debug traces in bmcweb, use the 139 following command for cmake 140 ``` 141 cmake ./ -DCMAKE_BUILD_TYPE:type=Debug 142 ``` 143 144 - Make your changes as needed, rebuild with `make` 145 146 - Reduce binary size by stripping it when ready for testing 147 ``` 148 arm-openbmc-linux-gnueabi-strip bmcweb 149 ``` 150 **Note:** Stripping is not required and having the debug symbols could be 151 useful depending on your testing. Leaving them will drastically increase 152 your transfer time to the BMC. 153 154 - Copy your bmcweb you want to test to /tmp/ in QEMU 155 ``` 156 scp -P 2222 bmcweb root@127.0.0.1:/tmp/ 157 ``` 158 **Special Notes:** 159 The address and port shown here (127.0.0.1 and 2222) reaches the QEMU session 160 you set up in your development environment as described above. 161 162 - Stop bmcweb service within your QEMU session 163 ``` 164 systemctl stop bmcweb 165 ``` 166 **Note:** bmcweb supports being started directly in parallel with the bmcweb 167 running as a service. The standalone bmcweb will be available on port 18080. 168 An advantage of this is you can compare between the two easily for testing. 169 In QEMU you would need to open up port 18080 when starting QEMU. Your curl 170 commands would need to use 18080 to communicate. 171 172 - If running within a system that has read-only /usr/ filesystem, issue 173 the following commands one time per QEMU boot to make the filesystem 174 writeable 175 ``` 176 mkdir -p /var/persist/usr 177 mkdir -p /var/persist/work/usr 178 mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr 179 ``` 180 181 - Remove the existing bmcweb from the filesystem in QEMU 182 ``` 183 rm /usr/bin/bmcweb 184 ``` 185 186 - Link to your new bmcweb in /tmp/ 187 ``` 188 ln -sf /tmp/bmcweb /usr/bin/bmcweb 189 ``` 190 191 - Test your changes. bmcweb will be started automatically upon your 192 first REST or Redfish command 193 ``` 194 curl -c cjar -b cjar -k -X POST https://127.0.0.1:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 195 curl -c cjar -b cjar -k -X GET https://127.0.0.1:2443/xyz/openbmc_project/state/bmc0 196 ``` 197 198 - Stop the bmcweb service and scp new file over to /tmp/ each time you 199 want to retest a change. 200 201 See the [REST](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md) 202 and [Redfish](https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md) cheatsheets for valid commands. 203 20413. ### Redfish 205 206 The redfish implementation shall pass the [Redfish Service 207 Validator](https://github.com/DMTF/Redfish-Service-Validator "Validator") with 208 no warnings or errors 209 210 The following redfish schemas and fields are targeted for OpenBMC. This is a 211 living document, and these schemas are subject to change. 212 213 The latest Redfish schemas can be found [here](https://redfish.dmtf.org/schemas/) 214 215 Fields common to all schemas 216 217 - @odata.context 218 - @odata.id 219 - @odata.type 220 - Id 221 - Name 222 223 224 #### /redfish/v1/ 225 ##### ServiceRoot 226 227 - RedfishVersion 228 - UUID 229 230 231 #### /redfish/v1/AccountService/ 232 ##### AccountService 233 234 - Description 235 - ServiceEnabled 236 - MinpasswordLength 237 - MaxPasswordLength 238 - Accounts 239 - Roles 240 241 #### /redfish/v1/AccountService/Accounts/ 242 ##### AccountCollection 243 244 - Description 245 - Members@odata.count 246 - Members 247 248 #### /redfish/v1/AccountService/Accounts/<AccountName> 249 ##### Account 250 251 - Description 252 - Enabled 253 - Password 254 - UserName 255 - RoleId 256 - Links/Role 257 258 #### /redfish/v1/AccountService/Roles/ 259 ##### RoleCollection 260 261 - Description 262 - Members@odata.count 263 - Members 264 - By default will contain 3 roles, "Administrator", "Operator", and "User" 265 266 #### /redfish/v1/AccountService/Roles/<RoleName> 267 ##### Role 268 269 - Description 270 - IsPredefined 271 - Will be set to true for all default roles. If the given role is 272 non-default, or has been modified from default, will be marked as false. 273 - AssignedPrivileges 274 - For the default roles, the following privileges will be assigned by 275 default 276 - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf, 277 ConfigureComponents 278 - Operator: Login, ConfigureComponents 279 - User: Login 280 281 282 #### /redfish/v1/Chassis 283 ##### ChassisCollection 284 285 - Members@odata.count 286 - Members 287 288 #### /redfish/v1/Chassis/<ChassisName> 289 ##### Chassis 290 291 - ChassisType 292 - Manufacturer 293 - Model 294 - SerialNumber 295 - PartNumber 296 - PowerState 297 - Thermal 298 - Shall be included if component contains temperature sensors, otherwise 299 shall be omitted. 300 - Power 301 - Shall be included if component contains voltage/current sensing 302 components, otherwise will be omitted. 303 304 #### /redfish/v1/Chassis/<ChassisName>/Thermal 305 ##### Thermal 306 Temperatures Fans Redundancy 307 308 #### /redfish/v1/Chassis/<ChassisName>/Thermal#/Temperatures/<SensorName> 309 ##### Temperature 310 - MemberId 311 - Status 312 - ReadingCelsius 313 - UpperThresholdNonCritical 314 - UpperThresholdCritical 315 - LowerThresholdNonCritical 316 - LowerThresholdCritical 317 - MinReadingRange 318 - MaxReadingRange 319 320 *threshold fields only present if defined for sensor, otherwise absent* 321 322 #### /redfish/v1/Chassis/<ChassisName>/Thermal#/Fans/<FanName> 323 ##### Fan 324 - MemberId 325 - Status 326 - Reading 327 - ReadingUnits 328 - UpperThresholdNonCritical 329 - UpperThresholdCritical 330 - LowerThresholdNonCritical 331 - LowerThresholdCritical 332 - MinReadingRange 333 - MaxReadingRange 334 - Redundancy 335 336 *threshold fields only present if defined for sensor, otherwise absent* 337 338 #### /redfish/v1/Chassis/<ChassisName>/Thermal#/Redundancy/<RedundancyName> 339 ##### Fan 340 - MemberId 341 - RedundancySet 342 - Mode 343 - Status 344 - MinNumNeeded 345 - MaxNumSupported 346 347 348 #### /redfish/v1/Chassis/<ChassisName>/Power/ 349 ##### Thermal 350 PowerControl Voltages PowerSupplies Redundancy 351 352 #### /redfish/v1/Chassis/<ChassisName>/Power#/PowerControl/<ControlName> 353 ##### PowerControl 354 - MemberId 355 - PowerConsumedWatts 356 - PowerMetrics/IntervalInMin 357 - PowerMetrics/MinConsumedWatts 358 - PowerMetrics/MaxConsumedWatts 359 - PowerMetrics/AverageConsumedWatts 360 - RelatedItem 361 - Should list systems and related chassis 362 363 #### /redfish/v1/Chassis/<ChassisName>/Power#/Voltages/<VoltageName> 364 ##### Voltage 365 - MemberId 366 - Status 367 - ReadingVolts 368 - UpperThresholdNonCritical 369 - UpperThresholdCritical 370 - LowerThresholdNonCritical 371 - LowerThresholdCritical 372 - MinReadingRange 373 - MaxReadingRange 374 - PhysicalContext 375 - RelatedItem 376 377 #### /redfish/v1/Chassis/<ChassisName>/Power#/PowerSupplies/<PSUName> 378 ##### PowerSupply 379 - MemberId 380 - Status 381 - LininputVoltage 382 - Model 383 - manufacturer 384 - FirmwareVersion 385 - SerialNumber 386 - PartNumber 387 - RelatedItem 388 - Redundancy 389 390 #### /redfish/v1/Chassis/{ChassisName}/Power#/Redundancy/<RedundancyName> 391 ##### Redundancy 392 - MemberId 393 - RedundancySet 394 - Mode 395 - Status 396 - MinNumNeeded 397 - MaxNumSupported 398 399 400 #### /redfish/v1/EventService 401 ##### EventService 402 - Id 403 - ServiceEnabled 404 - DeliveryRetryAttempts 405 - Defaults to 3 406 - EventTypesForSubscription 407 - Defaults to "Alert" 408 - Actions 409 - Subscriptions 410 411 #### /redfish/v1/EventService/Subscriptions 412 ##### EventDestinationCollection 413 - Members@odata.count 414 - Members 415 416 #### /redfish/v1/EventService/Subscriptions/{EventName}/ 417 ##### EventDestination 418 - Id 419 - Destination 420 - EventTypes 421 - Context 422 - OriginResources 423 - Protocol 424 425 426 #### /redfish/v1/Managers 427 ##### ManagerCollection 428 - Members 429 - Members@odata.count 430 431 #### /redfish/v1/Managers/BMC 432 ##### Manager 433 - Description 434 - LogServices 435 - GraphicalConsole 436 - UUID 437 - Model 438 - Links 439 - PowerState 440 - FirmwareVersion 441 - ManagerType 442 - ServiceEntryPointUUID 443 - DateTime 444 - NetworkProtocol 445 - Actions 446 - Status 447 - SerialConsole 448 - VirtualMedia 449 - EthernetInterfaces 450 451 #### /redfish/v1/Managers/BMC/EthernetInterfaces 452 ##### EthernetInterfaceCollection 453 - Members 454 - Members@odata.count 455 - Description 456 457 #### /redfish/v1/Managers/BMC/EthernetInterfaces/{InterfaceName} 458 ##### EthernetInterface 459 - Description 460 - VLAN 461 - MaxIPv6StaticAddresses 462 463 #### /redfish/v1/Managers/BMC/LogServices 464 ##### LogServiceCollection 465 - Members 466 - Members@odata.count 467 - Description 468 469 #### /redfish/v1/Managers/BMC/LogServices/RedfishLog 470 ##### LogService 471 - Entries 472 - OverWritePolicy 473 - Actions 474 - Status 475 - DateTime 476 - MaxNumberOfRecords 477 478 #### /redfish/v1/Managers/BMC/LogServices/RedfishLog/Entries/{entry} 479 ##### LogEntry 480 - Message 481 - Created 482 - EntryType 483 484 #### /redfish/v1/Managers/BMC/NetworkProtocol 485 ##### ManagerNetworkProtocol 486 - Description 487 - SSDP 488 - HTTPS 489 - SSH 490 - VirtualMedia 491 - KVMIP 492 - Status 493 494 495 #### /redfish/v1/Registries 496 ##### MessageRegistryFileCollection 497 - Members 498 - Should support Base, CommonMessages, and EventingMessages 499 - Members@odata.count 500 - Description 501 502 #### /redfish/v1/Registries/<MessageRegistry> 503 ##### MessageRegistryFile 504 - Location 505 - Description 506 - Location@odata.count 507 - Languages@odata.count 508 - Languages 509 - Registry 510 511 512 #### /redfish/v1/SessionService 513 ##### SessionService 514 - Description 515 - ServiceEnabled 516 - Status 517 - SessionTimeout 518 - Sessions 519 520 #### /redfish/v1/SessionService/Sessions 521 ##### SessionCollection 522 - Members 523 - Members@odata.count 524 - Description 525 526 527 #### /redfish/v1/Systems 528 ##### ComputerSystemCollection 529 - Members 530 - Should support one system 531 - Members@odata.count 532 533 #### /redfish/v1/Systems/{SystemName} 534 ##### ComputerSystem 535 - Boot 536 - PartNumber 537 - IndicatorLED 538 - UUID 539 - LogServices 540 - SystemType 541 - Manufacturer 542 - Description 543 - Model 544 - Links 545 - PowerState 546 - BiosVersion 547 - Storage 548 - SerialNumber 549 - Processors 550 - ProcessorSummary 551 - Memory 552 - Actions 553 - Status 554 - EthernetInterfaces 555 - MemorySummary 556 557 #### /redfish/v1/Systems/{SystemName}/EthernetInterfaces 558 ##### EthernetInterfaceCollection 559 - Members 560 - Members@odata.count 561 - Description 562 563 #### /redfish/v1/Systems/{SystemName}/LogServices 564 ##### LogServiceCollection 565 - Members 566 - Should default to one member, named SEL 567 - Members@odata.count 568 - Description 569 570 #### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries 571 ##### LogEntryCollection 572 - Members 573 - Members@odata.count 574 - Description 575 - @odata.nextLink 576 577 #### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries/{entryNumber} 578 ##### LogEntry 579 - MessageArgs 580 - Severity 581 - SensorType 582 - Message 583 - MessageId 584 - Created 585 - EntryCode 586 - EntryType 587 588 #### /redfish/v1/Systems/{SystemName}/Memory 589 ##### MemoryCollection 590 - Members 591 - Members@odata.count 592 593 #### /redfish/v1/Systems/{SystemName}/Memory/Memory1 594 ##### Memory 595 - MemoryType 596 - Description 597 - DeviceLocator 598 - Oem 599 - Metrics 600 - BaseModuleType 601 - Manufacturer 602 - MemoryDeviceType 603 - RankCount 604 - AllowedSpeedsMHz 605 - CapacityMiB 606 - DataWidthBits 607 - SerialNumber 608 - OperatingSpeedMhz 609 - ErrorCorrection 610 - PartNumber 611 - Status 612 - BusWidthBits 613 - MemoryMedia 614 615 #### /redfish/v1/Systems/{SystemName}/Memory/Memory1/MemoryMetrics 616 ##### MemoryMetrics 617 - Description 618 - HealthData 619 620 #### /redfish/v1/Systems/{SystemName}/Processors 621 ##### ProcessorCollection 622 - Members 623 - Should Support CPU1 and CPU2 for dual socket systems 624 - Members@odata.count 625 626 #### /redfish/v1/Systems/{SystemName}/Processors/{CPUName} 627 ##### Processor 628 - ProcessorArchitecture 629 - TotalCores 630 - ProcessorId 631 - MaxSpeedMHz 632 - Manufacturer 633 - Status 634 - Socket 635 - InstructionSet 636 - Model 637 - ProcessorType 638 - TotalThreads 639 640 #### /redfish/v1/Systems/{SystemName}/Storage 641 ##### StorageCollection 642 - Members 643 - Members@odata.count 644 645 #### /redfish/v1/Systems/{SystemName}/Storage/{storageIndex> 646 ##### Storage 647 - Drives 648 - Links 649 650 651 #### /redfish/v1/UpdateService 652 ##### UpdateService 653 - SoftwareInventory 654 655 #### /redfish/v1/UpdateService/SoftwareInventory 656 ##### SoftwareInventoryCollection 657 - Members 658 - Should Support BMC, ME, CPLD and BIOS 659 - Members@odata.count 660 661 #### /redfish/v1/UpdateService/SoftwareInventory/{MemberName} 662 ##### SoftwareInventory 663 - Version 664