As OpenBMC is intended to be deployed on an embedded system, care should be taken to avoid expensive constructs, and memory usage. In general, our performance and metric targets are:
Care should be taken to ensure that all code is written to be asynchronous in nature, to avoid blocking methods from stopping the processing of other tasks. At this time the webserver uses boost::asio for it async framework. Threads should be avoided if possible, and instead use async tasks within boost::asio.
Secure coding practices should be followed in all places in the webserver
In general, this means:
Error handling should be constructed in such a way that all possible errors return valid HTTP responses. The following HTTP codes will be used commonly
Where possible, 307 and 308 redirects should be avoided, as they introduce the possibility for subtle security bugs.
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:
The webserver shall provide the following authentication mechanisms.
There shall be connection between the authentication mechanism used and resources that are available over it. The webserver shall employ an authentication scheme that is in line with the rest of OpenBMC, and allows users and privileges to be provisioned from other interfaces.
The OpenBMC webserver shall follow the latest OWASP recommendations for authentication, session management, and security.
The performance priorities for the OpenBMC webserver are (in order):
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.
The webserver should be capable of hosting webui-vue, and implementing the required flows to host the application. In general, all access methods should be available to the webui.
bmcweb's Redfish implementation, including Redfish OEM Resources, shall conform to the Redfish specification. Please keep bmcweb's Redfish support document updated. OEM schemas should conform and be developed in line with the rules in OEM SCHEMAS.
A number of examples of common errors are captured in the common errors doc. It is recommended that developers read and understand all of them before starting any openbmc development. Common Errors.
Project commit message formatting should be obeyed link
Commit messages should answer the following questions:
Why are the changes useful? Given that bmcweb is a user-facing daemon, commits adding new functionality should include statements about how the commit in question is useful to the user.
What changes would a user expect to see? This includes new parameters, new resources, and new or changed properties. Any route changes should be explicitly called out.
Are there compatibility concerns? Is this change backward compatible for clients? If not, what commit would be broken, and how old is it? Have clients been warned? (ideally on the mailing list) link the discussion.
Commit messages should be line wrapped 50/72.
Don't make your users mad - Greg K-H
The kernel has very similar rules around compatibility that we should aspire to follow in the footsteps of.
To that end, bmcweb will do its' best to insulate clients from breaking api changes. Being explicit about this ensures that clients can upgrade their OpenBMC version without issue, and resolves a significant bottleneck in getting security patches deployed to users. Any change that's visible to a user is potentially a breaking change, but requiring all visible changes to be configurable would increase the software complexity, therefore bmcweb makes exceptions for things which a client is reasonably expected to code against:
Special note: Code exists in bmcweb that is missing upstream backends to make it function. Given that compatibility requires the ability to use and test the feature in question, changes to these methods, including outright removal, does not constitute a breaking change.
Security: There may be cases where maintainers make explicit breaking changes in the best interest of security; In these rare cases, the maintainers and contributors will endeavor to avoid breaking clients as much as is technically possible, but as with all security, impact will need to be weighed against the security impact of not making changes, and judgment calls will be made, with options to allow providing the old behavior.
clang-tidy is a tool that can be used to identify coding style violations, bad design patterns, and bug prone constructs. The checks are implemented in the .clang-tidy file in the root of bmcweb, and are expected to be passing. openbmc-build-scripts implements clang-tidy checks and is the recommended way to run these checks
Five bmcweb logging levels are supported, from least to most severity:
And their use cases:
bmcweb by default is compiled with runtime logging disabled, as a performance consideration. To enable it in a standalone build, add the logging level
-Dlogging='debug'
option to your configure flags. If building within Yocto, add the following to your local.conf.
EXTRA_OEMESON:pn-bmcweb:append = "-Dbmcweb-logging='debug'"
bmcweb also supports setting logging level at runtime. The bmcweb CLI application can be used to set the daemon's logging level on target. For example, to set logging level to INFO:
bmcweb loglevel info