format: reformat with latest openbmc-build-scripts
Reformat the repository using the latest from openbmc-build-scripts.
Add the `static/redfish` directory to be ignored by prettier since
these files come from elsewhere and having the ability to do a direct
diff is handy.
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: I74464d6f97047b4888a591e0d8a4f5ca970ac69e
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 22c4a69..a1e190d 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,27 +1,24 @@
---
name: Bug report
about: Create a report
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
---
-**Describe the bug**
-A clear and concise description of what the bug is.
+**Describe the bug** A clear and concise description of what the bug is.
-**Environment**
-What OpenBMC platform was this found on? If this was tested in QEMU, please add
+**Environment** What OpenBMC platform was this found on? If this was tested in
+QEMU, please add
-What specific OpenBMC versions (SHA1) did you use?
-(note, SHA1 should be resolvable to https://github.com/openbmc/openbmc)
+What specific OpenBMC versions (SHA1) did you use? (note, SHA1 should be
+resolvable to https://github.com/openbmc/openbmc)
-**To Reproduce**
-Steps to reproduce the behavior:
+**To Reproduce** Steps to reproduce the behavior:
+
1. Run the command '....'
2. See error
3. Expected behavior was '....'
-**Is this a regression**
-Has this behavior worked in the past? If yes, on which commit did it work, and
-what commit was broken?
+**Is this a regression** Has this behavior worked in the past? If yes, on which
+commit did it work, and what commit was broken?
diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md
index 2ac0576..b168329 100644
--- a/.github/ISSUE_TEMPLATE/custom.md
+++ b/.github/ISSUE_TEMPLATE/custom.md
@@ -1,13 +1,12 @@
---
name: Custom issue template
about: Question
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
---
-Please do not use GitHub issues for submitting questions. Please submit your
+Please do not use GitHub issues for submitting questions. Please submit your
questions either to the OpenBMC mailing list, or to the OpenBMC discord channel.
https://github.com/openbmc/docs/blob/master/README.md#contact
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 6c77cef..86f8716 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,12 +1,11 @@
---
name: Feature request
about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
---
-Please do not submit feature requests to GitHub. Please indicate your interest
+Please do not submit feature requests to GitHub. Please indicate your interest
in particular projects or features on the mailing list at
https://lists.ozlabs.org/listinfo/openbmc
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..c2a1ee5
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1 @@
+static/redfish
diff --git a/CLIENTS.md b/CLIENTS.md
index 010be31..6e7091e 100644
--- a/CLIENTS.md
+++ b/CLIENTS.md
@@ -1,13 +1,13 @@
bmcweb being a user and network facing daemon, is subject to a vast array of
-tests and clients that could target it. The below attempts to provide a
+tests and clients that could target it. The below attempts to provide a
non-exhaustive list of tests and clients that bmcweb is expected to be
-compatible with, they are split into a couple categories. Entries in the test
+compatible with, they are split into a couple categories. Entries in the test
category are intended to be qualification tests to ensure the bmcweb meets the
-specification. Entries in the clients category are intended to host user-facing
+specification. Entries in the clients category are intended to host user-facing
functionality.
The base expectation is that for master versions of bmcweb, and master versions
-of these tools, the tests pass 100%. There may be cases where we workaround
+of these tools, the tests pass 100%. There may be cases where we workaround
limitations in the testing tools behavior within bmcweb to make the tools pass,
regardless of whether there is user impact.
@@ -17,35 +17,30 @@
properly implements the Redfish schemas in the responded Resource.
git@github.com:DMTF/Redfish-Service-Validator.git
-Status: 100% passing. Integrated with CI to ensure no regressions.
+Status: 100% passing. Integrated with CI to ensure no regressions.
Redfish-Protocol-Validator: A tool to verify the protocol-level interactions
with the Redfish wire-protocol, and checks those against the Redfish
-specification.
-git@github.com:DMTF/Redfish-Protocol-Validator.git
+specification. git@github.com:DMTF/Redfish-Protocol-Validator.git
-Status: 95+% of assertions passing. No CI integration.
-
+Status: 95+% of assertions passing. No CI integration.
OpenBMC-test-automation: A tool based on robot framework for testing some
portion of the OpenBMC Redfish use cases.
Status: Passing for some machines with CI integration.
-
-slowloris: A tool to verify timeouts and DOS attack mitigation is implemented properly.
-https://github.com/gkbrk/slowloris
+slowloris: A tool to verify timeouts and DOS attack mitigation is implemented
+properly. https://github.com/gkbrk/slowloris
Status: Passing, no automated enforcement.
-
testssl.sh: A tool for verifying the corectness of the bmcweb cipher suites
against current recommended security standards
https://github.com/drwetter/testssl.sh
Status: Unknown
-
## Clients
fwupd: Is a client implementation that allows updating firmware components in a
@@ -54,29 +49,22 @@
Status: Unknown
-
python-redfish-library: A python library used by a number of tools.
git@github.com:DMTF/python-redfish-library.git
Status: Compatible
-
Redfish-Event-Listener: An example client for testing and implementing
-EventService handlers.
-https://github.com/DMTF/Redfish-Event-Listener
+EventService handlers. https://github.com/DMTF/Redfish-Event-Listener
-Status: Compatible. No CI integration.
-
+Status: Compatible. No CI integration.
Redfish-Tacklebox: A collection of common utilities for managing redfish servers
git@github.com:DMTF/Redfish-Tacklebox.git
Status: Unknown.
-
redfishtool: A generic command line tool for reading and writing operations to
-the Redfish server.
-https://github.com/DMTF/Redfishtool
+the Redfish server. https://github.com/DMTF/Redfishtool
-Status: Compatible. No automated testing.
-
+Status: Compatible. No automated testing.
diff --git a/COMMON_ERRORS.md b/COMMON_ERRORS.md
index 8bb1288..317cef8 100644
--- a/COMMON_ERRORS.md
+++ b/COMMON_ERRORS.md
@@ -1,45 +1,52 @@
# Commonly recurring errors in bmcweb
What follows is a list of common errors that new users to bmcweb tend to make
-when operating within its bounds for the first time. If this is your first time
+when operating within its bounds for the first time. If this is your first time
developing in bmcweb, the maintainers highly recommend reading and understanding
-_all_ of common traps before continuing with any development. Every single one
+_all_ of common traps before continuing with any development. Every single one
of the examples below compile without warnings, but are incorrect in
not-always-obvious ways, or impose a pattern that tends to cause hard to find
-bugs, or bugs that appear later. Every one has been submitted to code review
+bugs, or bugs that appear later. Every one has been submitted to code review
multiple times.
### 1. Directly dereferencing a pointer without checking for validity first
+
```C++
int myBadMethod(const nlohmann::json& j){
const int* myPtr = j.get_if<int>();
return *myPtr;
}
```
+
This pointer is not guaranteed to be filled, and could be a null dereference.
### 2. String views aren't null terminated
+
```C++
int getIntFromString(const std::string_view s){
return std::atoi(s.data());
}
```
+
This will give the right answer much of the time, but has the possibility to
-fail when string\_view is not null terminated. Use from\_chars instead, which
+fail when string_view is not null terminated. Use from_chars instead, which
takes both a pointer and a length
### 3. Not handling input errors
+
```C++
int getIntFromString(const std::string& s){
return std::atoi(s.c_str());
}
```
+
In the case where the string is not representable as an int, this will trigger
-undefined behavior at system level. Code needs to check for validity of the
-string, ideally with something like from\_chars, and return the appropriate error
+undefined behavior at system level. Code needs to check for validity of the
+string, ideally with something like from_chars, and return the appropriate error
code.
### 4. Walking off the end of a string
+
```C++
std::string getFilenameFromPath(const std::string& path){
size_t index = path.find("/");
@@ -52,11 +59,13 @@
```
### 5. Using methods that throw (or not handling bad inputs)
+
```C++
int myBadMethod(nlohmann::json& j){
return j.get<int>();
}
```
+
This method throws, and bad inputs will not be handled
Commonly used methods that fall into this pattern:
@@ -70,13 +79,13 @@
- nlohmann::json::operator+=
- nlohmann::json::at
- nlohmann::json::get
-- nlohmann::json::get\_ref
-- nlohmann::json::get\_to
+- nlohmann::json::get_ref
+- nlohmann::json::get_to
- nlohmann::json::operator\<\<
- nlohmann::json::operator\>\>
-- std::filesystem::create\_directory
+- std::filesystem::create_directory
- std::filesystem::rename
-- std::filesystem::file\_size
+- std::filesystem::file_size
- std::stoi
- std::stol
- std::stoll
@@ -84,19 +93,20 @@
#### Special note: JSON
`nlohmann::json::parse` by default
-[throws](https://json.nlohmann.me/api/basic_json/parse/) on failure, but
-also accepts an optional argument that causes it to not throw: set the 3rd
-argument to `false`.
+[throws](https://json.nlohmann.me/api/basic_json/parse/) on failure, but also
+accepts an optional argument that causes it to not throw: set the 3rd argument
+to `false`.
`nlohmann::json::dump` by default
[throws](https://json.nlohmann.me/api/basic_json/dump/) on failure, but also
-accepts an optional argument that causes it to not throw: set the 4th
-argument to `replace`. Although `ignore` preserves content 1:1, `replace`
-is preferred from a security point of view.
+accepts an optional argument that causes it to not throw: set the 4th argument
+to `replace`. Although `ignore` preserves content 1:1, `replace` is preferred
+from a security point of view.
#### Special note: Boost
+
there is a whole class of boost asio functions that provide both a method that
-throws on failure, and a method that accepts and returns an error code. This is
+throws on failure, and a method that accepts and returns an error code. This is
not a complete list, but users should verify in the boost docs when calling into
asio methods, and prefer the one that returns an error code instead of throwing.
@@ -104,36 +114,37 @@
- boost::asio::ip::tcp::acceptor::cancel();
- boost::asio::ip::tcp::acceptor::close();
- boost::asio::ip::tcp::acceptor::listen();
-- boost::asio::ip::address::make\_address();
+- boost::asio::ip::address::make_address();
### 6. Blocking functions
-bmcweb uses a single reactor for all operations. Blocking that reactor for any
-amount of time causes all other operations to stop. The common blocking
+bmcweb uses a single reactor for all operations. Blocking that reactor for any
+amount of time causes all other operations to stop. The common blocking
functions that tend to be called incorrectly are:
- sleep()
- boost::asio::ip::tcp::socket::read()
-- boost::asio::ip::tcp::socket::read\_some()
+- boost::asio::ip::tcp::socket::read_some()
- boost::asio::ip::tcp::socket::write()
-- boost::asio::ip::tcp::socket::write\_some()
+- boost::asio::ip::tcp::socket::write_some()
- boost::asio::ip::tcp::socket::connect()
- boost::asio::ip::tcp::socket::send()
- boost::asio::ip::tcp::socket::wait()
-- boost::asio::steady\_timer::wait()
+- boost::asio::steady_timer::wait()
-Note: an exception is made for filesystem/disk IO read and write. This is
-mostly due to not having great abstractions for it that mate well with the async
+Note: an exception is made for filesystem/disk IO read and write. This is mostly
+due to not having great abstractions for it that mate well with the async
system, the fact that most filesystem accesses are into tmpfs (and therefore
should be "fast" most of the time) and in general how little the filesystem is
used in practice.
### 7. Lack of locking between subsequent calls
+
While global data structures are discouraged, they are sometimes required to
-store temporary state for operations that require it. Given the single
-threaded nature of bmcweb, they are not required to be explicitly threadsafe,
-but they must be always left in a valid state, and checked for other uses
-before occupying.
+store temporary state for operations that require it. Given the single threaded
+nature of bmcweb, they are not required to be explicitly threadsafe, but they
+must be always left in a valid state, and checked for other uses before
+occupying.
```C++
std::optional<std::string> currentOperation;
@@ -149,6 +160,7 @@
currentOperation is not already being used.
### 8. Wildcard reference captures in lambdas
+
```
std::string x; auto mylambda = [&](){
x = "foo";
@@ -157,39 +169,42 @@
```
Numerous times, lifetime issues of const references have been injected into
-async bmcweb code. While capturing by reference can be useful, given how
+async bmcweb code. While capturing by reference can be useful, given how
difficult these types of bugs are to triage, bmcweb explicitly requires that all
code captures variables by name explicitly, and calls out each variable being
-captured by value or by reference. The above prototypes would change to
+captured by value or by reference. The above prototypes would change to
[&x]()... Which makes clear that x is captured, and its lifetime needs tracked.
-
### 9. URLs should end in "/"
+
```C++
BMCWEB("/foo/bar");
```
-Unless you explicitly have a reason not to (as there is one known exception
-where the behavior must differ) all URL handlers should end in "/". The bmcweb
-route handler will detect routes ending in slash and generate routes for both
-the route ending in slash and the one without. This allows both URLs to be
-used by users. While many specifications do not require this, it resolves a
-whole class of bug that we've seen in the past.
+Unless you explicitly have a reason not to (as there is one known exception
+where the behavior must differ) all URL handlers should end in "/". The bmcweb
+route handler will detect routes ending in slash and generate routes for both
+the route ending in slash and the one without. This allows both URLs to be used
+by users. While many specifications do not require this, it resolves a whole
+class of bug that we've seen in the past.
### 10. URLs constructed in aggregate
+
```C++
std::string routeStart = "/redfish/v1";
BMCWEB_ROUTE(routestart + "/SessionService/")
```
+
Very commonly, bmcweb maintainers and contributors alike have to do audits of
all routes that are available, to verify things like security and documentation
-accuracy. While these processes are largely manual, they can mostly be
-conducted by a simple grep statement to search for urls in question. Doing the
-above makes the route handlers no longer greppable, and complicates bmcweb
-patchsets as a whole.
+accuracy. While these processes are largely manual, they can mostly be conducted
+by a simple grep statement to search for urls in question. Doing the above makes
+the route handlers no longer greppable, and complicates bmcweb patchsets as a
+whole.
### 11. Not responding to 404
+
```C++
BMCWEB_ROUTE("/myendpoint/<str>",
[](Request& req, Response& res, const std::string& id){
@@ -208,18 +223,20 @@
"xyz.MyInterface", "GetAll", "");
});
```
+
All bmcweb routes should handle 404 (not found) properly, and return it where
-appropriate. 500 internal error is not a substitute for this, and should be
-only used if there isn't a more appropriate error code that can be returned.
-This is important, because a number of vulnerability scanners attempt injection
-attacks in the form of /myendpoint/foobar, or /myendpoint/#$*(%)&#%$)(*& in an
-attempt to circumvent security. If the server returns 500 to any of these
-requests, the security scanner logs it as an error for followup. While in
-general these errors are benign, and not actually a real security threat, having
-a clean security run allows maintainers to minimize the amount of time spent
-triaging issues reported from these scanning tools.
+appropriate. 500 internal error is not a substitute for this, and should be only
+used if there isn't a more appropriate error code that can be returned. This is
+important, because a number of vulnerability scanners attempt injection attacks
+in the form of /myendpoint/foobar, or /myendpoint/#$*(%)&#%$)(\*& in an attempt
+to circumvent security. If the server returns 500 to any of these requests, the
+security scanner logs it as an error for followup. While in general these errors
+are benign, and not actually a real security threat, having a clean security run
+allows maintainers to minimize the amount of time spent triaging issues reported
+from these scanning tools.
An implementation of the above that handles 404 would look like:
+
```C++
BMCWEB_ROUTE("/myendpoint/<str>",
[](Request& req, Response& res, const std::string& id){
@@ -245,9 +262,11 @@
Note: A more general form of this rule is that no handler should ever return 500
on a working system, and any cases where 500 is found, can immediately be
-assumed to be [a bug in either the system, or bmcweb.](https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#error-handling)
+assumed to be
+[a bug in either the system, or bmcweb.](https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#error-handling)
### 12. Imprecise matching
+
```C++
void isInventoryPath(const std::string& path){
if (path.find("inventory")){
@@ -256,29 +275,30 @@
return false;
}
```
+
When matching dbus paths, HTTP fields, interface names, care should be taken to
-avoid doing direct string containment matching. Doing so can lead to errors
+avoid doing direct string containment matching. Doing so can lead to errors
where fan1 and fan11 both report to the same object, and cause behavior breaks
in subtle ways.
-When using dbus paths, rely on the methods on sdbusplus::message::object\_path.
+When using dbus paths, rely on the methods on sdbusplus::message::object_path.
When parsing HTTP field and lists, use the RFC7230 implementations from
boost::beast.
-Other commonly misused methods are:
-boost::iequals. Unless the standard you're implementing (as is the case in some
-HTTP fields) requires case insensitive comparisons, casing should be obeyed,
-especially when relying on user-driven data.
+Other commonly misused methods are: boost::iequals. Unless the standard you're
+implementing (as is the case in some HTTP fields) requires case insensitive
+comparisons, casing should be obeyed, especially when relying on user-driven
+data.
-- boost::starts\_with
-- boost::ends\_with
-- std::string::starts\_with
-- std::string::ends\_with
+- boost::starts_with
+- boost::ends_with
+- std::string::starts_with
+- std::string::ends_with
- std::string::rfind
The above methods tend to be misused to accept user data and parse various
-fields from it. In practice, there tends to be better, purpose built methods
-for removing just the field you need.
+fields from it. In practice, there tends to be better, purpose built methods for
+removing just the field you need.
### 13. Complete replacement of the response object
@@ -289,10 +309,10 @@
```
In many cases, bmcweb is doing multiple async actions in parallel, and
-orthogonal keys within the Response object might be filled in from another
-task. Completely replacing the json object can lead to convoluted situations
-where the output of the response is dependent on the _order_ of the asynchronous
-actions completing, which cannot be guaranteed, and has many time caused bugs.
+orthogonal keys within the Response object might be filled in from another task.
+Completely replacing the json object can lead to convoluted situations where the
+output of the response is dependent on the _order_ of the asynchronous actions
+completing, which cannot be guaranteed, and has many time caused bugs.
```
void getMembers(crow::Response& res){
@@ -305,6 +325,5 @@
binaries.
Note, another form of this error involves calling nlohmann::json::reset(), to
-clear an object that's already been filled in. This has the potential to clear
+clear an object that's already been filled in. This has the potential to clear
correct data that was already filled in from other sources.
-
diff --git a/DBUS_USAGE.md b/DBUS_USAGE.md
index 354a79b..75a36c7 100644
--- a/DBUS_USAGE.md
+++ b/DBUS_USAGE.md
@@ -10,15 +10,15 @@
- If the DBus interface definition has an "unknown" or "unspecified" value,
detecting these will omit the property from the Redfish tree, in line with the
Redfish specification.
-- All DBus interfaces on all object paths are optional. An object missing an
+- All DBus interfaces on all object paths are optional. An object missing an
interface is never an error, and shall simply omit the relevant properties
and/or actions from that Redfish Resource.
-- bmcweb will code to the DBus interface itself. This means that daemons are
+- bmcweb will code to the DBus interface itself. This means that daemons are
expected to handle functionally bad, but DBus-correct input in their own
- process, and return appropriate return codes. This is done to reduce the
+ process, and return appropriate return codes. This is done to reduce the
duplication in input processing between the various user-facing daemons.
- There are interfaces for which there is an expectation that there will only
- ever be one producer in the project (ex bmc networking, user management). In
+ ever be one producer in the project (ex bmc networking, user management). In
these cases, it is desirable to call the daemon by well known name directly.
Bmcweb APIs should call the mapper in cases where it's reasonably expected
that multiple implementations exist (ex, CPU management, Sensors).
diff --git a/DEVELOPING.md b/DEVELOPING.md
index 5df3ce0..d475d53 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -1,185 +1,203 @@
# OpenBMC Webserver Development
1. ### Performance targets
- 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:
- - Binaries and static files should take up < 1MB of filesystem size
- - Memory usage should remain below 10MB at all times
- - Application startup time should be less than 1 second on target hardware
- (AST2500)
+ 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:
+
+ - Binaries and static files should take up < 1MB of filesystem size
+ - Memory usage should remain below 10MB at all times
+ - Application startup time should be less than 1 second on target hardware
+ (AST2500)
2. ### Asynchronous programming
+
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.
+ 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.
3. ### Secure coding guidelines
+
Secure coding practices should be followed in all places in the webserver
- In general, this means:
- - All buffer boundaries must be checked before indexing or using values
- - All pointers and iterators must be checked for null before dereferencing
- - All input from outside the application is considered untrusted, and should
- be escaped, authorized and filtered accordingly. This includes files in
- the filesystem.
- - All error statuses are checked and accounted for in control flow.
- - Where applicable, noexcept methods should be preferred to methods that use
- exceptions
- - Explicitly bounded types should be preferred over implicitly bounded types
- (like std::array<int, size> as opposed to int[size])
- - no use of [Banned
- functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions
- "Banned function list")
+ In general, this means:
+
+ - All buffer boundaries must be checked before indexing or using values
+ - All pointers and iterators must be checked for null before dereferencing
+ - All input from outside the application is considered untrusted, and should
+ be escaped, authorized and filtered accordingly. This includes files in the
+ filesystem.
+ - All error statuses are checked and accounted for in control flow.
+ - Where applicable, noexcept methods should be preferred to methods that use
+ exceptions
+ - Explicitly bounded types should be preferred over implicitly bounded types
+ (like std::array<int, size> as opposed to int[size])
+ - no use of
+ [Banned functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions "Banned function list")
4. ### Error handling
- 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
- - 200 OK - Request was properly handled
- - 201 Created - Resource was created
- - 401 Unauthorized - Request didn't posses the necessary authentication
- - 403 Forbidden - Request was authenticated, but did not have the necessary
- permissions to accomplish the requested task
- - 404 Not found - The url was not found
- - 500 Internal error - Something has broken within the OpenBMC web server,
- and should be filed as a bug
- Where possible, 307 and 308 redirects should be avoided, as they introduce
- the possibility for subtle security bugs.
+ 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
+
+ - 200 OK - Request was properly handled
+ - 201 Created - Resource was created
+ - 401 Unauthorized - Request didn't posses the necessary authentication
+ - 403 Forbidden - Request was authenticated, but did not have the necessary
+ permissions to accomplish the requested task
+ - 404 Not found - The url was not found
+ - 500 Internal error - Something has broken within the OpenBMC web server,
+ and should be filed as a bug
+
+ Where possible, 307 and 308 redirects should be avoided, as they introduce
+ the possibility for subtle security bugs.
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:
- - Minimizing the number of files read from disk at startup. Unless a
- feature is explicitly intended to be runtime configurable, its logic
- should be "baked in" to the application at compile time. For cases where
- the implementation is configurable at runtime, the default values should
- be included in application code to minimize the use of nonvolatile
- storage.
- - Avoid excessive memory usage and mallocs at startup.
+ 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:
+
+ - Minimizing the number of files read from disk at startup. Unless a feature
+ is explicitly intended to be runtime configurable, its logic should be
+ "baked in" to the application at compile time. For cases where the
+ implementation is configurable at runtime, the default values should be
+ included in application code to minimize the use of nonvolatile storage.
+ - Avoid excessive memory usage and mallocs at startup.
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
- CMakeLists.txt file.
- - Exceptions are currently enabled for webserver builds, but their use is
- discouraged. Long term, the intent is to disable exceptions, so any use
- of them for explicit control flow will likely be rejected in code review.
- Any use of exceptions should be cases where the program can be reasonably
- expected to crash if the exception occurs, as this will be the future
- behavior once exceptions are disabled.
- - Run time type information is disabled
- - Link time optimization is enabled
+
+ - 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
+ CMakeLists.txt file.
+ - Exceptions are currently enabled for webserver builds, but their use is
+ discouraged. Long term, the intent is to disable exceptions, so any use of
+ them for explicit control flow will likely be rejected in code review. Any
+ use of exceptions should be cases where the program can be reasonably
+ expected to crash if the exception occurs, as this will be the future
+ behavior once exceptions are disabled.
+ - Run time type information is disabled
+ - Link time optimization is enabled
7. ### Authentication
- The webserver shall provide the following authentication mechanisms.
- - Basic authentication
- - Cookie authentication
- - Token authentication
- 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 webserver shall provide the following authentication mechanisms.
+
+ - Basic authentication
+ - Cookie authentication
+ - Token authentication
+
+ 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.
8. ### Web security
+
The OpenBMC webserver shall follow the latest OWASP recommendations for
authentication, session management, and security.
9. ### Performance
+
The performance priorities for the OpenBMC webserver are (in order):
- 1. Code is readable and clear
- 2. Code follows secure guidelines
- 3. Code is performant, and does not unnecessarily abstract concepts at the
- expense of performance
- 4. Code does not employ constructs which require continuous system
- resources, unless required to meet performance targets. (example:
- caching sensor values which are expected to change regularly)
+
+ 1. Code is readable and clear
+ 2. Code follows secure guidelines
+ 3. Code is performant, and does not unnecessarily abstract concepts at the
+ expense of performance
+ 4. Code does not employ constructs which require continuous system resources,
+ unless required to meet performance targets. (example: caching sensor
+ values which are expected to change regularly)
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.
+
+ 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.
11. ### phosphor webui
- The webserver should be capable of hosting phosphor-webui, and implementing
- the required flows to host the application. In general, all access methods
- should be available to the webui.
+
+ The webserver should be capable of hosting phosphor-webui, and implementing
+ the required flows to host the application. In general, all access methods
+ should be available to the webui.
12. ### Redfish
- bmcweb's Redfish implementation, including Redfish OEM Resources, shall
- conform to the Redfish specification. Please keep bmcweb's [Redfish support
- document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) updated.
- OEM schemas should conform and be developed in line with the rules in
- [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md).
+
+ bmcweb's Redfish implementation, including Redfish OEM Resources, shall
+ conform to the Redfish specification. Please keep bmcweb's
+ [Redfish support document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md)
+ updated. OEM schemas should conform and be developed in line with the rules
+ in
+ [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md).
13. ### Common errors
- 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](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md).
+
+ 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](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md).
14. ### Commit messages
- Project commit message formatting should be obeyed
- [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages)
+ Project commit message formatting should be obeyed
+ [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages)
- 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.
+Commit messages should answer the following questions:
- - 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.
+- 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.
- - 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.
+- 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.
- Commit messages should be line wrapped 50/72.
+- 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.
15. ### Compatibility
- "Don't make your users mad" Greg K-H
- [source](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf)
+ "Don't make your users mad" Greg K-H
+ [source](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf)
- The kernel has very similar rules around compatibility that we should aspire
- to follow in the footsteps of.
+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:
- - New items added to a collection
- - Changes in UID for hypermedia resources (In line with Redfish spec)
- - New properties added to a resource
- - New versions of a given schema
+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.
+- New items added to a collection
+- Changes in UID for hypermedia resources (In line with Redfish spec)
+- New properties added to a resource
+- New versions of a given schema
- 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 judgement
- calls will be made, with options to allow providing the old behavior.
+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 judgement calls will be made, with
+options to allow providing the old behavior.
## clang-tidy
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](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-unit-test-docker.sh)
-implements clang-tidy checks and is the recommended way to run these checks
\ No newline at end of file
+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](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-unit-test-docker.sh)
+implements clang-tidy checks and is the recommended way to run these checks
diff --git a/HEADERS.md b/HEADERS.md
index f43cdfd..75f142e 100644
--- a/HEADERS.md
+++ b/HEADERS.md
@@ -1,21 +1,21 @@
-## Why does bmcweb use so many headers? My build times are slow!##
+## Why does bmcweb use so many headers? My build times are slow!##
TL; DR, History
-bmcweb at one point was a crow-based project. Evidence of this can still be
-seen in the http/.hpp files that still contain references to the crow
-namespaces. Crow makes heavy use of headers and template meta programming, and
-doesn't ship any cpp or implementation files, choosing to put everything in
-include once headers. As bmcweb evolved, it needed more capabilities, so the
-core was ported to Boost Beast, and what remains has very little similarity to
-crow anymore. Boost::beast at the time we ported took the same opinion,
-relying on header files and almost no implementation compile units. A large
-amount of the compile time is taken up in boost::beast template instantiations,
-specifically for boost::beast::http::message (ie Request and Response).
+bmcweb at one point was a crow-based project. Evidence of this can still be seen
+in the http/.hpp files that still contain references to the crow namespaces.
+Crow makes heavy use of headers and template meta programming, and doesn't ship
+any cpp or implementation files, choosing to put everything in include once
+headers. As bmcweb evolved, it needed more capabilities, so the core was ported
+to Boost Beast, and what remains has very little similarity to crow anymore.
+Boost::beast at the time we ported took the same opinion, relying on header
+files and almost no implementation compile units. A large amount of the compile
+time is taken up in boost::beast template instantiations, specifically for
+boost::beast::http::message (ie Request and Response).
The initial solution that gets proposed is to just move everything as it exists
-to separate compile units, making no other changes. This has been proposed and
-implemented 3-4 times in the project, the latest of which is below. The intent
+to separate compile units, making no other changes. This has been proposed and
+implemented 3-4 times in the project, the latest of which is below. The intent
of this document is largely to save effort for the next person, so they can at
least start from the existing prior attempts.
@@ -31,20 +31,20 @@
- Moving the Request and Response containers to opaque structures, so a majority
of code only needs to #include the interface, not any of the template code.
- https://gerrit.openbmc.org/c/openbmc/bmcweb/+/37445
- Doing this exposed a number of mediocre practices in the route handlers,
- where routes made copies of requests/responses, relied on APIs that should've
- been internal, and other practices that make this migration less
- straightforward, but is still being pursued by maintainers over time.
+ https://gerrit.openbmc.org/c/openbmc/bmcweb/+/37445 Doing this exposed a
+ number of mediocre practices in the route handlers, where routes made copies
+ of requests/responses, relied on APIs that should've been internal, and other
+ practices that make this migration less straightforward, but is still being
+ pursued by maintainers over time.
- Moving the internals of Request/Response/Connection to rely on something like
[http::proto](https://github.com/CPPAlliance/http_proto) which, written by the
same author as boost::beast, claims to have significant reduction in compile
time templates, and might not require abstracting the Request/Response
objects.
- Reduce the bmcweb binary size to the point where link time optimization is not
- required for most usages. About half of the bmcweb build time is spent doing
+ required for most usages. About half of the bmcweb build time is spent doing
link time optimization, which, as of this time is required to keep bmcweb code
- small enough to deploy on an actual BMCs (See DEVELOPING.md for details).
- One could theoretically determine the source of where LTO decreases the binary
+ small enough to deploy on an actual BMCs (See DEVELOPING.md for details). One
+ could theoretically determine the source of where LTO decreases the binary
size the most, and ensure that those were all in the same compile unit, such
that they got optimized without requiring LTO.
diff --git a/OEM_SCHEMAS.md b/OEM_SCHEMAS.md
index 275b6c2..c30e508 100644
--- a/OEM_SCHEMAS.md
+++ b/OEM_SCHEMAS.md
@@ -1,21 +1,22 @@
## Redfish OEM Resources
The Redfish specification allows for OEM resources and properties to be
-implemented by OEMs. As a general rule, OpenBMC discourages the use of OEM
-namespaces in APIs. In line with this, bmcweb does not expose an API for adding
+implemented by OEMs. As a general rule, OpenBMC discourages the use of OEM
+namespaces in APIs. In line with this, bmcweb does not expose an API for adding
OEM properties in a backward API compatible way for resources that have not been
merged to master.
### Why?
+
OEM properties in an open source project pose many problems when compared to
their closed source brethren in terms of reliability, code reuse, compatibility,
and maintenance.
1. As a general rule, OpenBMCs external Redfish API aims to be as compatible
- between systems as possible. Adding machine-specific resources, properties,
+ between systems as possible. Adding machine-specific resources, properties,
and types largely defeats some of that goal, as clients must implement
machine-specific APIs, some of which are likely to overlap, which increases
- the amount of code overall. OpenBMC also has very little visibility into
+ the amount of code overall. OpenBMC also has very little visibility into
clients that might interface with Redfish, and therefore needs to take care
when adding new, non-standard APIs.
@@ -28,32 +29,32 @@
3. If a given workflow eventually becomes standardized, OpenBMC OEM endpoints
now have to break an API boundary to be able to move to the standard
- implementation. Given the amount of effort it takes to break an API, it is
+ implementation. Given the amount of effort it takes to break an API, it is
much simpler to wait for the standard to be completed before merging the OEM
code to master.
-4. DMTF has many more Redfish experts than OpenBMC. While the bmcweb
- maintainers do their best to stay current on the evolving Redfish ecosystem,
- we have significantly limited scope, knowledge, and influence over the
- standard when compared to the experts within DMTF. Getting a DMTF opinion
- almost always leads to positive API design changes up front, which increases
- the usefulness of the code we write within the industry.
+4. DMTF has many more Redfish experts than OpenBMC. While the bmcweb maintainers
+ do their best to stay current on the evolving Redfish ecosystem, we have
+ significantly limited scope, knowledge, and influence over the standard when
+ compared to the experts within DMTF. Getting a DMTF opinion almost always
+ leads to positive API design changes up front, which increases the usefulness
+ of the code we write within the industry.
### How?
If you've read the above, and still think an OEM property is warranted, please
take the following steps.
-1. Present the new feature and use case to DMTF either through the [Redfish
- forum](https://www.redfishforum.com), or at a DMTF meeting. If possible,
- message the new feature through the normal openbmc communications channels to
- ensure OpenBMC is properly represented in the meeting/forum.
+1. Present the new feature and use case to DMTF either through the
+ [Redfish forum](https://www.redfishforum.com), or at a DMTF meeting. If
+ possible, message the new feature through the normal openbmc communications
+ channels to ensure OpenBMC is properly represented in the meeting/forum.
2. If DMTF is interested in the proposal, proceed using their documented process
- for change requests, and get your schema changes standardized; While OpenBMC
+ for change requests, and get your schema changes standardized; While OpenBMC
does not merge new schemas that have not been ratified by DMTF, feel free to
- push them to gerrit. If the features are major enough to warrant it, feel
+ push them to gerrit. If the features are major enough to warrant it, feel
free to discuss with maintainers about hosting a branch within gerrit while
- your DMTF proposal is in progress. If the DMTF feedback is documented as
+ your DMTF proposal is in progress. If the DMTF feedback is documented as
something to the effect of "this use case is unique to OpenBMC", proceed to
write an OpenBMC design document about the new feature you intend to
implement as OEM, under the OpenBMC (generic to all platforms) OEM namespace.
@@ -64,9 +65,9 @@
Regardless of the OEM namespace being used, implementations should plan to
implement all appropriate CSDL and OpenAPI schemas for their given OEM
resources, should pass the redfish service validator, and should follow redfish
-API design practices. We require this same level of quality as non OEM to
-ensure that OEM is truly required by the contributor to satisfy their use case.
-If OEM were held to a lesser level of quality requirements, bwcweb would consist
+API design practices. We require this same level of quality as non OEM to ensure
+that OEM is truly required by the contributor to satisfy their use case. If OEM
+were held to a lesser level of quality requirements, bwcweb would consist
entirely of OEM code.
bmcweb maintainers retain the final approval on OEM schemas.
diff --git a/README.md b/README.md
index c423d64..01b0c1a 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,59 @@
-# OpenBMC webserver #
+# OpenBMC webserver
This component attempts to be a "do everything" embedded webserver for OpenBMC.
+## Features
-## Features ##
The webserver implements a few distinct interfaces:
-+ DBus event websocket. Allows registering on changes to specific dbus paths,
+
+- DBus event websocket. Allows registering on changes to specific dbus paths,
properties, and will send an event from the websocket if those filters match.
-+ OpenBMC DBus REST api. Allows direct, low interference, high fidelity access
+- OpenBMC DBus REST api. Allows direct, low interference, high fidelity access
to dbus and the objects it represents.
-+ Serial: A serial websocket for interacting with the host serial console
+- Serial: A serial websocket for interacting with the host serial console
through websockets.
-+ Redfish: A protocol compliant, (Redfish.md)[DBus to Redfish translator].
-+ KVM: A websocket based implementation of the RFB (VNC) frame buffer protocol
+- Redfish: A protocol compliant, (Redfish.md)[DBus to Redfish translator].
+- KVM: A websocket based implementation of the RFB (VNC) frame buffer protocol
intended to mate to webui-vue to provide a complete KVM implementation.
-## Protocols ##
-bmcweb at a protocol level supports http and https. TLS is supported through
+## Protocols
+
+bmcweb at a protocol level supports http and https. TLS is supported through
OpenSSL.
-## AuthX ##
-### Authentication ###
+## AuthX
+
+### Authentication
+
Bmcweb supports multiple authentication protocols:
-+ Basic authentication per RFC7617
-+ Cookie based authentication for authenticating against webui-vue
-+ Mutual TLS authentication based on OpenSSL
-+ Session authentication through webui-vue
-+ XToken based authentication conformant to Redfish DSP0266
+
+- Basic authentication per RFC7617
+- Cookie based authentication for authenticating against webui-vue
+- Mutual TLS authentication based on OpenSSL
+- Session authentication through webui-vue
+- XToken based authentication conformant to Redfish DSP0266
Each of these types of authentication is able to be enabled or disabled both via
runtime policy changes (through the relevant Redfish APIs) or via configure time
-options. All authentication mechanisms supporting username/password are routed
+options. All authentication mechanisms supporting username/password are routed
to libpam, to allow for customization in authentication implementations.
-### Authorization ###
+### Authorization
+
All authorization in bmcweb is determined at routing time, and per route, and
conform to the Redfish PrivilegeRegistry.
-*Note: Non-Redfish functions are mapped to the closest equivalent Redfish
+\*Note: Non-Redfish functions are mapped to the closest equivalent Redfish
privilege level.
## Configuration
bmcweb is configured per the
-[meson build files](https://mesonbuild.com/Build-options.html). Available
+[meson build files](https://mesonbuild.com/Build-options.html). Available
options are documented in meson_options.txt
## Compile bmcweb with default options:
+
```ascii
meson builddir
ninja -C builddir
@@ -57,24 +64,29 @@
mentioned in `bmcweb/subprojects`.
## Debug logging
+
bmcweb by default is compiled with runtime logging disabled, as a performance
-consideration. To enable it in a standalone build, add the
+consideration. To enable it in a standalone build, add the
+
```ascii
-Dlogging='enabled'
```
-option to your configure flags. If building within Yocto, add the following to your local.conf.
+
+option to your configure flags. If building within Yocto, add the following to
+your local.conf.
+
```bash
EXTRA_OEMESON:pn-bmcweb:append = "-Dbmcweb-logging='enabled'"
```
## Use of persistent data
+
bmcweb relies on some on-system data for storage of persistent data that is
-internal to the process. Details on the exact data stored and when it is
+internal to the process. Details on the exact data stored and when it is
read/written can seen from the persistent_data namespace.
## TLS certificate generation
-When SSL support is enabled and a usable certificate is not found, bmcweb will
-generate a self-signed a certificate before launching the server. Please see
-the bmcweb source code for details on the parameters this certificate is built
-with.
+When SSL support is enabled and a usable certificate is not found, bmcweb will
+generate a self-signed a certificate before launching the server. Please see the
+bmcweb source code for details on the parameters this certificate is built with.
diff --git a/Redfish.md b/Redfish.md
index 3d36a57..d302f78 100644
--- a/Redfish.md
+++ b/Redfish.md
@@ -1,20 +1,21 @@
-# Redfish #
+# Redfish
-bmcweb provides an implementation of the [Redfish][1] API. This document
-details the Redfish schemas supported by bmcweb. This document also discusses
-some of the details of that implementation and different implementations
-available for certain areas.
+bmcweb provides an implementation of the [Redfish][1] API. This document details
+the Redfish schemas supported by bmcweb. This document also discusses some of
+the details of that implementation and different implementations available for
+certain areas.
## Redfish Schema
-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
+The following redfish schemas and fields are targeted for OpenBMC. This is a
living document, and these schemas are subject to change.
-The latest Redfish schemas can be found [here](https://redfish.dmtf.org/schemas/)
+The latest Redfish schemas can be found
+[here](https://redfish.dmtf.org/schemas/)
If using a previously unused schema, you will need to add it to the included
schema list in scripts/update_schemas.py and run update_schemas.py.
@@ -26,9 +27,10 @@
- Id
- Name
-
#### /redfish/v1/
+
##### ServiceRoot
+
- AccountService
- CertificateService
- Chassis
@@ -46,7 +48,9 @@
- UpdateService
#### /redfish/v1/AccountService/
+
##### AccountService
+
- AccountLockoutDuration
- AccountLockoutThreshold
- Accounts
@@ -63,13 +67,17 @@
- ServiceEnabled
#### /redfish/v1/AccountService/Accounts/
+
##### ManagerAccountCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/AccountService/Accounts/{ManagerAccountId}/
+
##### ManagerAccount
+
- AccountTypes
- Description
- Enabled
@@ -82,99 +90,122 @@
- UserName
#### /redfish/v1/AccountService/LDAP/Certificates/
+
##### CertificateCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/AccountService/Roles/
+
##### RoleCollection
+
- Description
- Members
- By default will contain 3 roles, "Administrator", "Operator", and "ReadOnly"
- Members@odata.count
#### /redfish/v1/AccountService/Roles/{RoleId}/
+
##### Role
+
- AssignedPrivileges
- - For the default roles, the following privileges will be assigned by
- default
- - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf,
- ConfigureComponents
- - Operator: Login, ConfigureComponents, ConfigureSelf
- - ReadOnly: Login, ConfigureSelf
+ - For the default roles, the following privileges will be assigned by default
+ - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf,
+ ConfigureComponents
+ - Operator: Login, ConfigureComponents, ConfigureSelf
+ - ReadOnly: Login, ConfigureSelf
- 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.
+ - 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.
- OemPrivileges
- RoleId
#### /redfish/v1/CertificateService/
+
##### CertificateService
+
- Actions
- CertificateLocations
- Description
#### /redfish/v1/CertificateService/CertificateLocations/
+
##### CertificateLocations
+
- Description
- Links/Certificates
- Links/Certificates@odata.count
#### /redfish/v1/Chassis/
+
##### ChassisCollection
+
- Members
- Members@odata.count
#### /redfish/v1/Chassis/{ChassisId}/
+
##### Chassis
+
- Actions
- ChassisType
- Links/ComputerSystems
- Links/ManagedBy
- PCIeDevices
- Power
- - Shall be included if component contains voltage/current sensing
- components, otherwise will be omitted.
+ - Shall be included if component contains voltage/current sensing components,
+ otherwise will be omitted.
- PowerState
- Sensors
- Status
- Thermal
- - Shall be included if component contains temperature sensors, otherwise
- shall be omitted.
+ - Shall be included if component contains temperature sensors, otherwise shall
+ be omitted.
#### /redfish/v1/Chassis/{ChassisId}/Drive/
+
#### Drive
-- Members
-(This is dependent on a entity manager association from
-Chassis to Drives, The name of the association is "chassis<->drive")
+
+- Members (This is dependent on a entity manager association from Chassis to
+ Drives, The name of the association is "chassis<->drive")
#### /redfish/v1/Chassis/{ChassisId}/Drive/{DriveId}/
+
#### Drive
+
- Drives
- Drives@odata.count
-- Status
-(this is dependant on a entity manager association from Chassis to Drives)
+- Status (this is dependant on a entity manager association from Chassis to
+ Drives)
#### /redfish/v1/Chassis/{ChassisId}/EnvironmentMetrics/
+
##### EnvironmentMetrics
#### /redfish/v1/Chassis/{ChassisId}/Power/
+
##### Power
+
- PowerControl
- PowerSupplies
- Redundancy
- Voltages
#### /redfish/v1/Chassis/{ChassisId}/Sensors/
+
##### SensorCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Chassis/{ChassisId}/Sensors/{Id}/
+
##### Sensor
+
- Reading
- ReadingRangeMax
- ReadingRangeMin
@@ -184,13 +215,17 @@
- Thresholds
#### /redfish/v1/Chassis/{ChassisId}/Thermal/
+
##### Thermal
+
- Fans
- Redundancy
- Temperatures
#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Temperatures/{SensorName}/
+
##### Temperature
+
- MemberId
- Status
- ReadingCelsius
@@ -199,11 +234,13 @@
- LowerThresholdNonCritical
- LowerThresholdCritical
- MinReadingRange
-- MaxReadingRange
-*threshold fields only present if defined for sensor, otherwise absent*
+- MaxReadingRange _threshold fields only present if defined for sensor,
+ otherwise absent_
#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Fans/{FanName}/
+
##### Fan
+
- MemberId
- Status
- Reading
@@ -214,11 +251,13 @@
- LowerThresholdCritical
- MinReadingRange
- MaxReadingRange
-- Redundancy
-*threshold fields only present if defined for sensor, otherwise absent*
+- Redundancy _threshold fields only present if defined for sensor, otherwise
+ absent_
#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Redundancy/{RedundancyName}/
+
##### Redundancy
+
- MemberId
- RedundancySet
- Mode
@@ -229,14 +268,19 @@
#### /redfish/v1/Chassis/{ChassisId}/ThermalSubsystem
##### ThermalSubsystem
+
- Status
#### /redfish/v1/Chassis/{ChassisId}/Power/
+
##### Power
+
PowerControl Voltages PowerSupplies Redundancy
#### /redfish/v1/Chassis/{ChassisId}/Power#/PowerControl/{ControlName}/
+
##### PowerControl
+
- MemberId
- PowerConsumedWatts
- PowerMetrics/IntervalInMin
@@ -247,7 +291,9 @@
- Should list systems and related chassis
#### /redfish/v1/Chassis/{ChassisId}/Power#/Voltages/{VoltageName}/
+
##### Voltage
+
- MemberId
- Status
- ReadingVolts
@@ -261,7 +307,9 @@
- RelatedItem
#### /redfish/v1/Chassis/{ChassisId}/Power#/PowerSupplies/{PSUName}/
+
##### PowerSupply
+
- MemberId
- Status
- LininputVoltage
@@ -274,7 +322,9 @@
- Redundancy
#### /redfish/v1/Chassis/{ChassisId}/Power#/Redundancy/{RedundancyName}/
+
##### Redundancy
+
- MemberId
- RedundancySet
- Mode
@@ -283,7 +333,9 @@
- MaxNumSupported
#### /redfish/v1/EventService/
+
##### EventService
+
- Actions
- DeliveryRetryAttempts
- Defaults to 3
@@ -297,12 +349,16 @@
- Subscriptions
#### /redfish/v1/EventService/Subscriptions/
+
##### EventDestinationCollection
+
- Members
- Members@odata.count
#### /redfish/v1/EventService/Subscriptions/{EventName}/
+
##### EventDestination
+
- Id
- Destination
- EventTypes
@@ -311,13 +367,17 @@
- Protocol
#### /redfish/v1/JsonSchemas/
+
##### JsonSchemaFileCollection
+
- Description
- Members@odata.count
- Members
#### /redfish/v1/JsonSchemas/{Id}/
+
##### JsonSchemaFile
+
- Schema
- Description
- Languages
@@ -326,12 +386,16 @@
- Location@odata.count
#### /redfish/v1/Managers/
+
##### ManagerCollection
+
- Members
- Members@odata.count
#### /redfish/v1/Managers/bmc/
+
##### Manager
+
- Actions
- DateTime
- DateTimeLocalOffset
@@ -364,13 +428,17 @@
- UUID
#### /redfish/v1/Managers/bmc/EthernetInterfaces/
+
##### EthernetInterfaceCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/
+
##### EthernetInterface
+
- DHCPv4
- DHCPv6
- Description
@@ -392,7 +460,9 @@
- VLANs
#### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/VLANs/
+
##### VLanNetworkInterfaceCollection
+
- Members
- Members@odata.count
@@ -404,8 +474,8 @@
Within bmcweb, the LogService object resides under the System resource. It
tracks all events for the system.
-The LogService supports multiple log entry types. bmcweb has support for
-the `Event` type. This is the new Redfish-defined type.
+The LogService supports multiple log entry types. bmcweb has support for the
+`Event` type. This is the new Redfish-defined type.
bmcweb supports two different implementations of the
`LogService/EventLog/Entries` URI.
@@ -420,17 +490,21 @@
bmcweb to look to [phosphor-logging][4] for any D-Bus log entries. These will
then be translated to Redfish EventLog Entries.
-These two implementations do not work together, so choosing one will disable
-the other.
+These two implementations do not work together, so choosing one will disable the
+other.
#### /redfish/v1/Managers/bmc/LogServices/
+
##### LogServiceCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Managers/bmc/LogServices/RedfishLog/
+
##### LogService
+
- Entries
- OverWritePolicy
- Actions
@@ -439,13 +513,17 @@
- MaxNumberOfRecords
#### /redfish/v1/Managers/bmc/LogServices/RedfishLog/Entries/{LogEntryId}/
+
##### LogEntry
+
- Message
- Created
- EntryType
#### /redfish/v1/Managers/bmc/NetworkProtocol/
+
##### ManagerNetworkProtocol
+
- Description
- FQDN
- HTTP
@@ -457,13 +535,17 @@
- Status
#### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/
+
##### CertificateCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/{CertificateId}/
+
##### Certificate
+
- CertificateString
- Description
- Issuer
@@ -473,20 +555,25 @@
- ValidNotBefore
#### /redfish/v1/Managers/bmc/Truststore/Certificates/
+
##### CertificateCollection
+
- Description
- error
-
#### /redfish/v1/Registries/
+
##### MessageRegistryFileCollection
+
- Description
- Members
- Should support Base, CommonMessages, and EventingMessages
- Members@odata.count
#### /redfish/v1/Registries/{MessageRegistryFileId}/
+
##### MessageRegistryFile
+
- Description
- Languages
- Languages@odata.count
@@ -495,33 +582,43 @@
- Registry
#### /redfish/v1/SessionService/
+
##### SessionService
+
- Description
- ServiceEnabled
- SessionTimeout
- Sessions
#### /redfish/v1/SessionService/Sessions/
+
##### SessionCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/SessionService/Sessions/{SessionId}/
+
##### Session
+
- ClientOriginIPAddress
- Description
- Oem
- UserName
#### /redfish/v1/Systems/
+
##### ComputerSystemCollection
+
- Members
- Should support one system
- Members@odata.count
#### /redfish/v1/Systems/system/Bios/
+
##### Bios
+
- Actions
- Description
- Links/ActiveSoftwareImage
@@ -529,7 +626,9 @@
- Links/SoftwareImages@odata.count
#### /redfish/v1/Systems/system/
+
##### ComputerSystem
+
- Actions
- AssetTag
- Bios
@@ -566,20 +665,26 @@
- SystemType
#### /redfish/v1/Systems/system/EthernetInterfaces/
+
##### EthernetInterfaceCollection
+
- Members
- Members@odata.count
- Description
#### /redfish/v1/Systems/system/LogServices/
+
##### LogServiceCollection
+
- Description
- Members
- Should default to one member, named SEL
- Members@odata.count
#### /redfish/v1/Systems/system/LogServices/EventLog/
+
##### LogService
+
- Actions
- DateTime
- DateTimeLocalOffset
@@ -588,13 +693,17 @@
- OverWritePolicy
#### /redfish/v1/Systems/system/LogServices/EventLog/Entries/
+
##### LogEntryCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Systems/system/LogServices/EventLog/Entries/{LogEntryId}/
+
##### LogEntry
+
- AdditionalDataURI
- Created
- EntryType
@@ -604,14 +713,18 @@
- Severity
#### /redfish/v1/Systems/system/LogServices/SEL/Entries/
+
##### LogEntryCollection
+
- Members
- Members@odata.count
- Description
- @odata.nextLink
#### /redfish/v1/Systems/system/LogServices/SEL/Entries/{LogEntryId}/
+
##### LogEntry
+
- MessageArgs
- Severity
- SensorType
@@ -622,12 +735,16 @@
- EntryType
#### /redfish/v1/Systems/system/Memory/
+
##### MemoryCollection
+
- Members
- Members@odata.count
#### /redfish/v1/Systems/system/Memory/{MemoryId}/
+
##### Memory
+
- AllowedSpeedsMHz
- BaseModuleType
- BusWidthBits
@@ -645,24 +762,32 @@
- Status
#### /redfish/v1/Systems/system/Memory/{MemoryId}/MemoryMetrics/
+
##### MemoryMetrics
+
- Description
- HealthData
#### /redfish/v1/Systems/system/PCIeDevices/
+
##### PCIeDeviceCollection
+
- Description
- Members
- Members@odata.count
#### /redfish/v1/Systems/system/Processors/
+
##### ProcessorCollection
+
- Members
- Should Support CPU1 and CPU2 for dual socket systems
- Members@odata.count
#### /redfish/v1/Systems/system/Processors/{ProcessorId}/
+
##### Processor
+
- InstructionSet
- Manufacturer
- MaxSpeedMHz
@@ -679,24 +804,32 @@
- Version
#### /redfish/v1/Systems/system/Storage/
+
##### StorageCollection
+
- Members
- Members@odata.count
#### /redfish/v1/Systems/system/Storage/{StorageId}/
+
##### Storage
+
- Drives
- Drives@odata.count
- Status
#### /redfish/v1/Systems/system/Storage/{StorageId}/Drive/{DriveId}/
+
##### Storage
+
- CapacityBytes
- Links
- Status
#### /redfish/v1/TaskService/
+
##### TaskService
+
- CompletedTaskOverWritePolicy
- DateTime
- LifeCycleEventOnTaskStateChange
@@ -705,12 +838,16 @@
- Tasks
#### /redfish/v1/TaskService/Tasks/
+
##### TaskCollection
+
- Members
- Members@odata.count
#### /redfish/v1/TelemetryService/
+
##### TelemetryService
+
- MaxReports
- MetricReportDefinitions
- MetricReports
@@ -719,22 +856,30 @@
- Triggers
#### /redfish/v1/TelemetryService/MetricReportDefinitions/
+
##### MetricReportDefinitionCollection
+
- Members
- Members@odata.count
#### /redfish/v1/TelemetryService/MetricReports/
+
##### MetricReportCollection
+
- Members
- Members@odata.count
#### /redfish/v1/TelemetryService/Triggers/
+
##### TriggersCollection
+
- Members
- Members@odata.count
#### /redfish/v1/UpdateService/
+
##### UpdateService
+
- Actions
- Description
- FirmwareInventory
@@ -744,13 +889,17 @@
- ServiceEnabled
#### /redfish/v1/UpdateService/FirmwareInventory/
+
##### SoftwareInventoryCollection
+
- Members
- Should Support BMC, ME, CPLD and BIOS
- Members@odata.count
#### /redfish/v1/UpdateService/FirmwareInventory/{SoftwareInventoryId}/
+
##### SoftwareInventory
+
- Description
- RelatedItem@odata.count
- RelatedItem
@@ -760,5 +909,6 @@
[1]: https://www.dmtf.org/standards/redfish
[2]: https://redfish.dmtf.org/schemas/v1/LogService.json
-[3]: https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md
+[3]:
+ https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md
[4]: https://github.com/openbmc/phosphor-logging
diff --git a/TESTING.md b/TESTING.md
index 5a489f0..f335392 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -6,50 +6,61 @@
in commit messages.
## General Methodology
-There are a variety of ways to develop and test bmcweb software changes.
-Here are the steps for using the SDK and QEMU.
-- Follow all [development environment setup](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
-directions in the development environment setup document. This will get
-QEMU started up and you in the SDK environment.
-- Follow all of the [gerrit setup](https://github.com/openbmc/docs/blob/master/development/gerrit-setup.md)
-directions in the gerrit setup document.
+There are a variety of ways to develop and test bmcweb software changes. Here
+are the steps for using the SDK and QEMU.
+
+- Follow all
+ [development environment setup](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+ directions in the development environment setup document. This will get QEMU
+ started up and you in the SDK environment.
+- Follow all of the
+ [gerrit setup](https://github.com/openbmc/docs/blob/master/development/gerrit-setup.md)
+ directions in the gerrit setup document.
- Clone bmcweb from gerrit
+
```
git clone ssh://openbmc.gerrit/openbmc/bmcweb/
```
-- Follow directions in [README.md](https://github.com/openbmc/bmcweb#configuration) to compile
+- Follow directions in
+ [README.md](https://github.com/openbmc/bmcweb#configuration) to compile
- Reduce binary size by stripping it when ready for testing
+
```
arm-openbmc-linux-gnueabi-strip bmcweb
```
+
**Note:** Stripping is not required and having the debug symbols could be
- useful depending on your testing. Leaving them will drastically increase
- your transfer time to the BMC.
+ useful depending on your testing. Leaving them will drastically increase your
+ transfer time to the BMC.
- Copy your bmcweb you want to test to /tmp/ in QEMU
+
```
scp -P 2222 bmcweb root@127.0.0.1:/tmp/
```
- **Special Notes:**
- The address and port shown here (127.0.0.1 and 2222) reaches the QEMU session
- you set up in your development environment as described above.
+
+ **Special Notes:** The address and port shown here (127.0.0.1 and 2222)
+ reaches the QEMU session you set up in your development environment as
+ described above.
- Stop bmcweb service within your QEMU session
+
```
systemctl stop bmcweb
```
+
**Note:** bmcweb supports being started directly in parallel with the bmcweb
running as a service. The standalone bmcweb will be available on port 18080.
- An advantage of this is you can compare between the two easily for testing.
- In QEMU you would need to open up port 18080 when starting QEMU. Your curl
+ An advantage of this is you can compare between the two easily for testing. In
+ QEMU you would need to open up port 18080 when starting QEMU. Your curl
commands would need to use 18080 to communicate.
-- If running within a system that has read-only /usr/ filesystem, issue
-the following commands one time per QEMU boot to make the filesystem
-writeable
+- If running within a system that has read-only /usr/ filesystem, issue the
+ following commands one time per QEMU boot to make the filesystem writeable
+
```
mkdir -p /var/persist/usr
mkdir -p /var/persist/work/usr
@@ -57,32 +68,37 @@
```
- Remove the existing bmcweb from the filesystem in QEMU
+
```
rm /usr/bin/bmcweb
```
- Link to your new bmcweb in /tmp/
+
```
ln -sf /tmp/bmcweb /usr/bin/bmcweb
```
-- Test your changes. bmcweb will be started automatically upon your
-first REST or Redfish command
+- Test your changes. bmcweb will be started automatically upon your first REST
+ or Redfish command
+
```
curl -c cjar -b cjar -k -X POST https://127.0.0.1:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
curl -c cjar -b cjar -k -X GET https://127.0.0.1:2443/xyz/openbmc_project/state/bmc0
```
-- Stop the bmcweb service and scp new file over to /tmp/ each time you
-want to retest a change.
+- Stop the bmcweb service and scp new file over to /tmp/ each time you want to
+ retest a change.
See the [REST](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md)
- and [Redfish](https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md) cheatsheets for valid commands.
-
+ and
+ [Redfish](https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md)
+ cheatsheets for valid commands.
## Types of Changes to Run
-A committer should run tests that exercise all paths changed in the patchset.
-If making changes to the http core, that are expected to effect all types of
+
+A committer should run tests that exercise all paths changed in the patchset. If
+making changes to the http core, that are expected to effect all types of
routes, testing one route of each class (websocket, HTTP get, HTTP post) is
required.
@@ -90,7 +106,8 @@
### Basic Redfish Robot Test on QEMU
-Run the [upstream Robot QEMU test](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-qemu-robot-test.sh).
+Run the
+[upstream Robot QEMU test](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-qemu-robot-test.sh).
This test is performed automatically when bumping SRCREV. Ensuring this test
passing makes your CL less likely to be rolled back while bumping SRCREV of
bmcweb.
@@ -106,7 +123,8 @@
### Redfish Validator
-Commiters are required to run the [Redfish Validator](https://github.com/DMTF/Redfish-Service-Validator.git)
+Commiters are required to run the
+[Redfish Validator](https://github.com/DMTF/Redfish-Service-Validator.git)
anytime they make a change to the GET behavior of the redfish tree. The test
must run on real hardware since the resource tree will be more complete.
diff --git a/scripts/check_base_registry.py b/scripts/check_base_registry.py
index 1db533a..663c6e0 100755
--- a/scripts/check_base_registry.py
+++ b/scripts/check_base_registry.py
@@ -4,10 +4,9 @@
import json
import re
-
parser = argparse.ArgumentParser()
-parser.add_argument('-b', '--base', default=None, required=True)
-parser.add_argument('-f', '--file', default=None, required=True)
+parser.add_argument("-b", "--base", default=None, required=True)
+parser.add_argument("-f", "--file", default=None, required=True)
args = parser.parse_args()
with open(args.file) as error_file:
@@ -15,9 +14,14 @@
with open(args.base) as base_file:
base_json = json.load(base_file)
- for message_name, message_data in base_json['Messages'].items():
- message_id = base_json['RegistryPrefix'] + '.' + \
- base_json['RegistryVersion'] + '.' + message_name
+ for message_name, message_data in base_json["Messages"].items():
+ message_id = (
+ base_json["RegistryPrefix"]
+ + "."
+ + base_json["RegistryVersion"]
+ + "."
+ + message_name
+ )
message_found = False
index = 0
for i, error in enumerate(error_data):
@@ -29,33 +33,38 @@
print("{} not found".format(message_id))
continue
- error_info = error_data[index:index + 15]
+ error_info = error_data[index : index + 15]
error_str = " ".join(error_info)
error_str = re.sub(
- 'std::to_string\\(arg(\\d+)\\)',
- 'arg\\1',
- error_str)
- error_str = re.sub('"\n\\s*"', '', error_str, re.MULTILINE)
+ "std::to_string\\(arg(\\d+)\\)", "arg\\1", error_str
+ )
+ error_str = re.sub('"\n\\s*"', "", error_str, re.MULTILINE)
error_str = re.sub(
'"\\s*\\+\\s*arg(\\d+)\\s*\\+\n?\\s*"',
- '%\\1',
+ "%\\1",
error_str,
- re.MULTILINE)
- if message_data['Message'] not in error_str:
+ re.MULTILINE,
+ )
+ if message_data["Message"] not in error_str:
print(
"{}: error in Message: {}".format(
- message_id,
- message_data['Message']))
+ message_id, message_data["Message"]
+ )
+ )
print(error_str)
- if message_data['MessageSeverity'] not in error_str:
- print("{}: error in MessageSeverity: {}".format(
- message_id, message_data['MessageSeverity']))
+ if message_data["MessageSeverity"] not in error_str:
+ print(
+ "{}: error in MessageSeverity: {}".format(
+ message_id, message_data["MessageSeverity"]
+ )
+ )
print(error_str)
- if message_data['Resolution'] not in error_str:
+ if message_data["Resolution"] not in error_str:
print(
"{}: error in Resolution: {}".format(
- message_id,
- message_data['Resolution']))
+ message_id, message_data["Resolution"]
+ )
+ )
print(error_str)
diff --git a/scripts/parse_registries.py b/scripts/parse_registries.py
index bfe87ef..369bebf 100755
--- a/scripts/parse_registries.py
+++ b/scripts/parse_registries.py
@@ -1,14 +1,14 @@
#!/usr/bin/env python3
+import argparse
import json
import os
import requests
-import argparse
-PRAGMA_ONCE = '''#pragma once
-'''
+PRAGMA_ONCE = """#pragma once
+"""
-WARNING = '''/****************************************************************
+WARNING = """/****************************************************************
* READ THIS WARNING FIRST
* This is an auto-generated header which contains definitions
* for Redfish DMTF defined messages.
@@ -17,9 +17,12 @@
* this file are owned by DMTF. Any modifications to these files
* should be first pushed to the relevant registry in the DMTF
* github organization.
- ***************************************************************/'''
+ ***************************************************************/"""
-REGISTRY_HEADER = PRAGMA_ONCE + WARNING + '''
+REGISTRY_HEADER = (
+ PRAGMA_ONCE
+ + WARNING
+ + """
#include "registries.hpp"
#include <array>
@@ -28,25 +31,20 @@
namespace redfish::registries::{}
{{
-'''
+"""
+)
SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__))
include_path = os.path.realpath(
- os.path.join(
- SCRIPT_DIR,
- "..",
- "redfish-core",
- "include",
- "registries"))
+ os.path.join(SCRIPT_DIR, "..", "redfish-core", "include", "registries")
+)
-proxies = {
- 'https': os.environ.get("https_proxy", None)
-}
+proxies = {"https": os.environ.get("https_proxy", None)}
def make_getter(dmtf_name, header_name, type_name):
- url = 'https://redfish.dmtf.org/registries/{}'.format(dmtf_name)
+ url = "https://redfish.dmtf.org/registries/{}".format(dmtf_name)
dmtf = requests.get(url, proxies=proxies)
dmtf.raise_for_status()
json_file = json.loads(dmtf.text)
@@ -62,72 +60,68 @@
except BaseException:
print("{} not found".format(file))
- with open(file, 'w') as registry:
+ with open(file, "w") as registry:
registry.write(REGISTRY_HEADER.format(namespace))
# Parse the Registry header info
registry.write(
"const Header header = {{\n"
- " \"{json_dict[@Redfish.Copyright]}\",\n"
- " \"{json_dict[@odata.type]}\",\n"
- " \"{json_dict[Id]}\",\n"
- " \"{json_dict[Name]}\",\n"
- " \"{json_dict[Language]}\",\n"
- " \"{json_dict[Description]}\",\n"
- " \"{json_dict[RegistryPrefix]}\",\n"
- " \"{json_dict[RegistryVersion]}\",\n"
- " \"{json_dict[OwningEntity]}\",\n"
+ ' "{json_dict[@Redfish.Copyright]}",\n'
+ ' "{json_dict[@odata.type]}",\n'
+ ' "{json_dict[Id]}",\n'
+ ' "{json_dict[Name]}",\n'
+ ' "{json_dict[Language]}",\n'
+ ' "{json_dict[Description]}",\n'
+ ' "{json_dict[RegistryPrefix]}",\n'
+ ' "{json_dict[RegistryVersion]}",\n'
+ ' "{json_dict[OwningEntity]}",\n'
"}};\n"
"constexpr const char* url =\n"
- " \"{url}\";\n"
+ ' "{url}";\n'
"\n"
"constexpr std::array registry =\n"
"{{\n".format(
json_dict=json_dict,
url=url,
- ))
+ )
+ )
messages_sorted = sorted(json_dict["Messages"].items())
for messageId, message in messages_sorted:
registry.write(
" MessageEntry{{\n"
- " \"{messageId}\",\n"
+ ' "{messageId}",\n'
" {{\n"
- " \"{message[Description]}\",\n"
- " \"{message[Message]}\",\n"
- " \"{message[MessageSeverity]}\",\n"
+ ' "{message[Description]}",\n'
+ ' "{message[Message]}",\n'
+ ' "{message[MessageSeverity]}",\n'
" {message[NumberOfArgs]},\n"
" {{".format(
- messageId=messageId,
- message=message
- ))
+ messageId=messageId, message=message
+ )
+ )
paramTypes = message.get("ParamTypes")
if paramTypes:
for paramType in paramTypes:
registry.write(
- "\n"
- " \"{}\",".format(paramType)
+ '\n "{}",'.format(paramType)
)
registry.write("\n },\n")
else:
registry.write("},\n")
registry.write(
- " \"{message[Resolution]}\",\n"
- " }}}},\n".format(message=message))
+ ' "{message[Resolution]}",\n'
+ " }}}},\n".format(message=message)
+ )
- registry.write(
- "\n};\n"
- "\n"
- "enum class Index\n"
- "{\n"
- )
+ registry.write("\n};\n\nenum class Index\n{\n")
for index, (messageId, message) in enumerate(messages_sorted):
messageId = messageId[0].lower() + messageId[1:]
- registry.write(
- " {} = {},\n".format(messageId, index))
+ registry.write(" {} = {},\n".format(messageId, index))
registry.write(
- "}};\n"
- "}} // namespace redfish::registries::{}\n"
- .format(namespace))
+ "}};\n}} // namespace redfish::registries::{}\n".format(
+ namespace
+ )
+ )
def get_privilege_string_from_list(privilege_list):
@@ -138,9 +132,9 @@
for privilege in privileges:
if privilege == "NoAuth":
continue
- privilege_string += "\""
+ privilege_string += '"'
privilege_string += privilege
- privilege_string += "\",\n"
+ privilege_string += '",\n'
if privilege != "NoAuth":
privilege_string = privilege_string[:-2]
privilege_string += "}"
@@ -158,7 +152,10 @@
return "Or".join(names)
-PRIVILEGE_HEADER = PRAGMA_ONCE + WARNING + '''
+PRIVILEGE_HEADER = (
+ PRAGMA_ONCE
+ + WARNING
+ + """
#include "privileges.hpp"
#include <array>
@@ -167,29 +164,34 @@
namespace redfish::privileges
{
-'''
+"""
+)
def make_privilege_registry():
- path, json_file, type_name, url = \
- make_getter('Redfish_1.3.0_PrivilegeRegistry.json',
- 'privilege_registry.hpp', 'privilege')
- with open(path, 'w') as registry:
+ path, json_file, type_name, url = make_getter(
+ "Redfish_1.3.0_PrivilegeRegistry.json",
+ "privilege_registry.hpp",
+ "privilege",
+ )
+ with open(path, "w") as registry:
registry.write(PRIVILEGE_HEADER)
privilege_dict = {}
for mapping in json_file["Mappings"]:
# first pass, identify all the unique privilege sets
for operation, privilege_list in mapping["OperationMap"].items():
- privilege_dict[get_privilege_string_from_list(
- privilege_list)] = (privilege_list, )
+ privilege_dict[
+ get_privilege_string_from_list(privilege_list)
+ ] = (privilege_list,)
for index, key in enumerate(privilege_dict):
- (privilege_list, ) = privilege_dict[key]
+ (privilege_list,) = privilege_dict[key]
name = get_variable_name_for_privilege_set(privilege_list)
registry.write(
"const std::array<Privileges, {length}> "
- "privilegeSet{name} = {key};\n"
- .format(length=len(privilege_list), name=name, key=key)
+ "privilegeSet{name} = {key};\n".format(
+ length=len(privilege_list), name=name, key=key
+ )
)
privilege_dict[key] = (privilege_list, name)
@@ -198,26 +200,29 @@
registry.write("// {}\n".format(entity))
for operation, privilege_list in mapping["OperationMap"].items():
privilege_string = get_privilege_string_from_list(
- privilege_list)
+ privilege_list
+ )
operation = operation.lower()
registry.write(
"const static auto& {}{} = privilegeSet{};\n".format(
- operation,
- entity,
- privilege_dict[privilege_string][1]))
+ operation, entity, privilege_dict[privilege_string][1]
+ )
+ )
registry.write("\n")
registry.write(
- "} // namespace redfish::privileges\n"
- "// clang-format on\n")
+ "} // namespace redfish::privileges\n// clang-format on\n"
+ )
def main():
parser = argparse.ArgumentParser()
parser.add_argument(
- '--registries', type=str,
+ "--registries",
+ type=str,
default="base,task_event,resource_event,privilege",
- help="Comma delimited list of registries to update")
+ help="Comma delimited list of registries to update",
+ )
args = parser.parse_args()
@@ -225,17 +230,27 @@
files = []
if "base" in registries:
- files.append(make_getter('Base.1.13.0.json',
- 'base_message_registry.hpp',
- 'base'))
+ files.append(
+ make_getter(
+ "Base.1.13.0.json", "base_message_registry.hpp", "base"
+ )
+ )
if "task_event" in registries:
- files.append(make_getter('TaskEvent.1.0.3.json',
- 'task_event_message_registry.hpp',
- 'task_event'))
+ files.append(
+ make_getter(
+ "TaskEvent.1.0.3.json",
+ "task_event_message_registry.hpp",
+ "task_event",
+ )
+ )
if "resource_event" in registries:
- files.append(make_getter('ResourceEvent.1.0.3.json',
- 'resource_event_message_registry.hpp',
- 'resource_event'))
+ files.append(
+ make_getter(
+ "ResourceEvent.1.0.3.json",
+ "resource_event_message_registry.hpp",
+ "resource_event",
+ )
+ )
update_registries(files)
diff --git a/scripts/update_schemas.py b/scripts/update_schemas.py
index da9c346..459d045 100755
--- a/scripts/update_schemas.py
+++ b/scripts/update_schemas.py
@@ -1,14 +1,13 @@
#!/usr/bin/env python3
-import requests
-import zipfile
-from io import BytesIO
-from packaging.version import parse
-
import os
-from collections import OrderedDict, defaultdict
import shutil
-
import xml.etree.ElementTree as ET
+import zipfile
+from collections import OrderedDict, defaultdict
+from io import BytesIO
+
+import requests
+from packaging.version import parse
VERSION = "DSP8010_2022.2"
@@ -42,7 +41,7 @@
"ComputerSystemCollection",
"Drive",
"DriveCollection",
- 'EnvironmentMetrics',
+ "EnvironmentMetrics",
"EthernetInterface",
"EthernetInterfaceCollection",
"Event",
@@ -254,7 +253,6 @@
csdl_filenames.sort(key=version_sort_key)
with open(metadata_index_path, "w") as metadata_index:
-
metadata_index.write('<?xml version="1.0" encoding="UTF-8"?>\n')
metadata_index.write(
"<edmx:Edmx xmlns:edmx="
@@ -270,7 +268,6 @@
continue
with open(os.path.join(schema_path, filename), "wb") as schema_out:
-
metadata_index.write(
' <edmx:Reference Uri="/redfish/v1/schema/'
+ filename
@@ -289,16 +286,14 @@
namespace = data_child.attrib["Namespace"]
if namespace.startswith("RedfishExtensions"):
metadata_index.write(
- " "
- '<edmx:Include Namespace="'
+ ' <edmx:Include Namespace="'
+ namespace
+ '" Alias="Redfish"/>\n'
)
else:
metadata_index.write(
- " "
- '<edmx:Include Namespace="'
+ ' <edmx:Include Namespace="'
+ namespace
+ '"/>\n'
)
@@ -392,6 +387,6 @@
for schema_file in json_schema_files:
hpp_file.write(' "{}",\n'.format(schema_file))
- hpp_file.write(" };\n" "}\n")
+ hpp_file.write(" };\n}\n")
zip_ref.close()
diff --git a/scripts/websocket_test.py b/scripts/websocket_test.py
index 85b2c0d..21c7f16 100755
--- a/scripts/websocket_test.py
+++ b/scripts/websocket_test.py
@@ -3,20 +3,23 @@
# Example of streaming sensor values from openbmc using the /subscribe api
# requires websockets package to be installed
+import argparse
import asyncio
-import ssl
-import websockets
import base64
import json
-import argparse
+import ssl
+
+import websockets
parser = argparse.ArgumentParser()
parser.add_argument("--host", help="Host to connect to", required=True)
parser.add_argument(
- "--username", help="Username to connect with", default="root")
+ "--username", help="Username to connect with", default="root"
+)
parser.add_argument("--password", help="Password to use", default="0penBmc")
-parser.add_argument('--ssl', default=True,
- action=argparse.BooleanOptionalAction)
+parser.add_argument(
+ "--ssl", default=True, action=argparse.BooleanOptionalAction
+)
args = parser.parse_args()
@@ -29,27 +32,30 @@
"altitude": "Meters",
"current": "Amps",
"energy": "Joules",
- "cfm": "CFM"
+ "cfm": "CFM",
}
async def hello():
- protocol = 'ws'
+ protocol = "ws"
if args.ssl:
- protocol += 's'
- uri = '{}://{}/subscribe'.format(protocol, args.host)
+ protocol += "s"
+ uri = "{}://{}/subscribe".format(protocol, args.host)
ssl_context = ssl.SSLContext()
- authbytes = "{}:{}".format(args.username, args.password).encode('ascii')
- auth = "Basic {}".format(base64.b64encode(authbytes).decode('ascii'))
+ authbytes = "{}:{}".format(args.username, args.password).encode("ascii")
+ auth = "Basic {}".format(base64.b64encode(authbytes).decode("ascii"))
headers = {"Authorization": auth}
- async with \
- websockets.connect(uri, ssl=ssl_context, extra_headers=headers) \
- if args.ssl else websockets.connect(uri, extra_headers=headers) \
- as websocket:
- request = json.dumps({
- "paths": ["/xyz/openbmc_project/sensors"],
- "interfaces": ["xyz.openbmc_project.Sensor.Value"]
- })
+ async with websockets.connect(
+ uri, ssl=ssl_context, extra_headers=headers
+ ) if args.ssl else websockets.connect(
+ uri, extra_headers=headers
+ ) as websocket:
+ request = json.dumps(
+ {
+ "paths": ["/xyz/openbmc_project/sensors"],
+ "interfaces": ["xyz.openbmc_project.Sensor.Value"],
+ }
+ )
await websocket.send(request)
while True: