diff options
| -rw-r--r-- | .github/ISSUE_TEMPLATE/bug_report.md | 27 | ||||
| -rw-r--r-- | .github/ISSUE_TEMPLATE/custom.md | 9 | ||||
| -rw-r--r-- | .github/ISSUE_TEMPLATE/feature_request.md | 9 | ||||
| -rw-r--r-- | .prettierignore | 1 | ||||
| -rw-r--r-- | CLIENTS.md | 38 | ||||
| -rw-r--r-- | COMMON_ERRORS.md | 157 | ||||
| -rw-r--r-- | DBUS_USAGE.md | 8 | ||||
| -rw-r--r-- | DEVELOPING.md | 280 | ||||
| -rw-r--r-- | HEADERS.md | 42 | ||||
| -rw-r--r-- | OEM_SCHEMAS.md | 43 | ||||
| -rw-r--r-- | README.md | 66 | ||||
| -rw-r--r-- | Redfish.md | 226 | ||||
| -rw-r--r-- | TESTING.md | 76 | ||||
| -rwxr-xr-x | scripts/check_base_registry.py | 53 | ||||
| -rwxr-xr-x | scripts/parse_registries.py | 177 | ||||
| -rwxr-xr-x | scripts/update_schemas.py | 25 | ||||
| -rwxr-xr-x | scripts/websocket_test.py | 46 |
17 files changed, 755 insertions, 528 deletions
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 22c4a69fe8..a1e190d1ff 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 2ac057672c..b168329fb7 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 6c77cefdf3..86f8716eff 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 0000000000..c2a1ee5cff --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +static/redfish diff --git a/CLIENTS.md b/CLIENTS.md index 010be31c2d..6e7091e7f5 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 @@ Redfish-Service-Validator: A tool to verify through GET requests that bmcweb 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 - -Status: 95+% of assertions passing. No CI integration. +specification. git@github.com:DMTF/Redfish-Protocol-Validator.git +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 @@ git@github.com:fwupd/fwupd.git 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 - -Status: Compatible. No CI integration. +EventService handlers. https://github.com/DMTF/Redfish-Event-Listener +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 - -Status: Compatible. No automated testing. +the Redfish server. https://github.com/DMTF/Redfishtool +Status: Compatible. No automated testing. diff --git a/COMMON_ERRORS.md b/COMMON_ERRORS.md index 8bb1288291..317cef829c 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 @@ std::string getFilenameFromPath(const std::string& path){ ``` ### 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 @@ Commonly used methods that fall into this pattern: - 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 @@ Commonly used methods that fall into this pattern: #### 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 @@ asio methods, and prefer the one that returns an error code instead of throwing. - 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 @@ In the above case, the first callback needs a check to ensure that currentOperation is not already being used. ### 8. Wildcard reference captures in lambdas + ``` std::string x; auto mylambda = [&](){ x = "foo"; @@ -157,39 +169,42 @@ do_async_read(mylambda) ``` 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 +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. - +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 @@ BMCWEB_ROUTE("/myendpoint/<str>", "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 @@ BMCWEB_ROUTE("/myendpoint/<str>", 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 @@ void isInventoryPath(const std::string& path){ 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 @@ void getMembers(crow::Response& res){ ``` 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 @@ intermediate object construction and the move, and as a result, produces smaller 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 354a79bb79..75a36c7db3 100644 --- a/DBUS_USAGE.md +++ b/DBUS_USAGE.md @@ -10,15 +10,15 @@ schemas: - 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 5df3ce057f..d475d5364d 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. + 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: + 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. + - 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. + - 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: - 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. +- 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. +- 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. +- 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. +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) - - 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 - - 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. + "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. + +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 + +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 f43cdfdf94..75f142ed6b 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 @@ there have been proposed a few ideas might provide some relief; - 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 275b6c2423..c30e508d3e 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 @@ and maintenance. 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 @@ take the following steps. 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. @@ -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 @@ configuration, meson will automatically download them via its wrap dependencies 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 3d36a57089..d302f78150 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 @@ Fields common to all schemas - Id - Name - #### /redfish/v1/ + ##### ServiceRoot + - AccountService - CertificateService - Chassis @@ -46,7 +48,9 @@ Fields common to all schemas - UpdateService #### /redfish/v1/AccountService/ + ##### AccountService + - AccountLockoutDuration - AccountLockoutThreshold - Accounts @@ -63,13 +67,17 @@ Fields common to all schemas - ServiceEnabled #### /redfish/v1/AccountService/Accounts/ + ##### ManagerAccountCollection + - Description - Members - Members@odata.count #### /redfish/v1/AccountService/Accounts/{ManagerAccountId}/ + ##### ManagerAccount + - AccountTypes - Description - Enabled @@ -82,99 +90,122 @@ Fields common to all schemas - 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 @@ Chassis to Drives, The name of the association is "chassis<->drive") - 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 @@ Chassis to Drives, The name of the association is "chassis<->drive") - 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 @@ Chassis to Drives, The name of the association is "chassis<->drive") - 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 @@ Chassis to Drives, The name of the association is "chassis<->drive") #### /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 @@ PowerControl Voltages PowerSupplies Redundancy - Should list systems and related chassis #### /redfish/v1/Chassis/{ChassisId}/Power#/Voltages/{VoltageName}/ + ##### Voltage + - MemberId - Status - ReadingVolts @@ -261,7 +307,9 @@ PowerControl Voltages PowerSupplies Redundancy - RelatedItem #### /redfish/v1/Chassis/{ChassisId}/Power#/PowerSupplies/{PSUName}/ + ##### PowerSupply + - MemberId - Status - LininputVoltage @@ -274,7 +322,9 @@ PowerControl Voltages PowerSupplies Redundancy - Redundancy #### /redfish/v1/Chassis/{ChassisId}/Power#/Redundancy/{RedundancyName}/ + ##### Redundancy + - MemberId - RedundancySet - Mode @@ -283,7 +333,9 @@ PowerControl Voltages PowerSupplies Redundancy - MaxNumSupported #### /redfish/v1/EventService/ + ##### EventService + - Actions - DeliveryRetryAttempts - Defaults to 3 @@ -297,12 +349,16 @@ PowerControl Voltages PowerSupplies Redundancy - Subscriptions #### /redfish/v1/EventService/Subscriptions/ + ##### EventDestinationCollection + - Members - Members@odata.count #### /redfish/v1/EventService/Subscriptions/{EventName}/ + ##### EventDestination + - Id - Destination - EventTypes @@ -311,13 +367,17 @@ PowerControl Voltages PowerSupplies Redundancy - Protocol #### /redfish/v1/JsonSchemas/ + ##### JsonSchemaFileCollection + - Description - Members@odata.count - Members #### /redfish/v1/JsonSchemas/{Id}/ + ##### JsonSchemaFile + - Schema - Description - Languages @@ -326,12 +386,16 @@ PowerControl Voltages PowerSupplies Redundancy - Location@odata.count #### /redfish/v1/Managers/ + ##### ManagerCollection + - Members - Members@odata.count #### /redfish/v1/Managers/bmc/ + ##### Manager + - Actions - DateTime - DateTimeLocalOffset @@ -364,13 +428,17 @@ PowerControl Voltages PowerSupplies Redundancy - 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 @@ PowerControl Voltages PowerSupplies Redundancy - VLANs #### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/VLANs/ + ##### VLanNetworkInterfaceCollection + - Members - Members@odata.count @@ -404,8 +474,8 @@ events for the service or resource to which it is associated. 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 @@ with the `-DBMCWEB_ENABLE_REDFISH_DBUS_LOG_ENTRIES=ON` option. This will cause 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - Links/SoftwareImages@odata.count #### /redfish/v1/Systems/system/ + ##### ComputerSystem + - Actions - AssetTag - Bios @@ -566,20 +665,26 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - 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 @@ the other. - Tasks #### /redfish/v1/TaskService/Tasks/ + ##### TaskCollection + - Members - Members@odata.count #### /redfish/v1/TelemetryService/ + ##### TelemetryService + - MaxReports - MetricReportDefinitions - MetricReports @@ -719,22 +856,30 @@ the other. - 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 @@ the other. - 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 @@ the other. [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 5a489f02ff..f335392dde 100644 --- a/TESTING.md +++ b/TESTING.md @@ -6,50 +6,61 @@ should add types of testing they performed and their results as "Tested" footers 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 @@ writeable ``` - 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 @@ required. ### 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 @@ $ python scripts/websocket_test.py --host 1.2.3.4:443 --ssl ### 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 1db533a09d..663c6e0541 100755 --- a/scripts/check_base_registry.py +++ b/scripts/check_base_registry.py @@ -4,10 +4,9 @@ import argparse 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.file) as error_file: 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 @@ with open(args.file) as error_file: 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 bfe87ef773..369bebf582 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 @@ WARNING = '''/**************************************************************** * 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 @@ REGISTRY_HEADER = PRAGMA_ONCE + WARNING + ''' 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 @@ def update_registries(files): 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 @@ def get_privilege_string_from_list(privilege_list): 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 @@ def get_variable_name_for_privilege_set(privilege_list): return "Or".join(names) -PRIVILEGE_HEADER = PRAGMA_ONCE + WARNING + ''' +PRIVILEGE_HEADER = ( + PRAGMA_ONCE + + WARNING + + """ #include "privileges.hpp" #include <array> @@ -167,29 +164,34 @@ PRIVILEGE_HEADER = PRAGMA_ONCE + WARNING + ''' 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 @@ def make_privilege_registry(): 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 @@ def main(): 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 da9c3460f2..459d0457bd 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 @@ include_list = [ "ComputerSystemCollection", "Drive", "DriveCollection", - 'EnvironmentMetrics', + "EnvironmentMetrics", "EthernetInterface", "EthernetInterfaceCollection", "Event", @@ -254,7 +253,6 @@ json_schema_files = OrderedDict( 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 @@ with open(metadata_index_path, "w") as metadata_index: 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 @@ with open(metadata_index_path, "w") as metadata_index: 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 @@ with open(os.path.join(cpp_path, "schemas.hpp"), "w") as hpp_file: 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 85b2c0d8ef..21c7f160b1 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 @@ sensor_type_map = { "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: |