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