markdownlint: fix all warnings
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: I1402cbd84c916792ca2fc0ad0f34db661cbdfa72
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index a1e190d..532af8e 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -12,7 +12,7 @@
QEMU, please add
What specific OpenBMC versions (SHA1) did you use? (note, SHA1 should be
-resolvable to https://github.com/openbmc/openbmc)
+resolvable to <https://github.com/openbmc/openbmc>)
**To Reproduce** Steps to reproduce the behavior:
diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md
index b168329..e3c7a81 100644
--- a/.github/ISSUE_TEMPLATE/custom.md
+++ b/.github/ISSUE_TEMPLATE/custom.md
@@ -9,4 +9,4 @@
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
+<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 86f8716..60e1e07 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -8,4 +8,4 @@
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
+<https://lists.ozlabs.org/listinfo/openbmc>
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 0000000..15c9e81
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1,3 @@
+default: true
+MD024:
+ siblings_only: true
diff --git a/CLIENTS.md b/CLIENTS.md
index 6e7091e..4978bb6 100644
--- a/CLIENTS.md
+++ b/CLIENTS.md
@@ -1,3 +1,5 @@
+# Client overview
+
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
non-exhaustive list of tests and clients that bmcweb is expected to be
@@ -31,13 +33,13 @@
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
+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
+<https://github.com/drwetter/testssl.sh>
Status: Unknown
@@ -55,7 +57,7 @@
Status: Compatible
Redfish-Event-Listener: An example client for testing and implementing
-EventService handlers. https://github.com/DMTF/Redfish-Event-Listener
+EventService handlers. <https://github.com/DMTF/Redfish-Event-Listener>
Status: Compatible. No CI integration.
@@ -65,6 +67,6 @@
Status: Unknown.
redfishtool: A generic command line tool for reading and writing operations to
-the Redfish server. https://github.com/DMTF/Redfishtool
+the Redfish server. <https://github.com/DMTF/Redfishtool>
Status: Compatible. No automated testing.
diff --git a/COMMON_ERRORS.md b/COMMON_ERRORS.md
index 317cef8..6cb7340 100644
--- a/COMMON_ERRORS.md
+++ b/COMMON_ERRORS.md
@@ -9,9 +9,9 @@
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
+## 1. Directly dereferencing a pointer without checking for validity first
-```C++
+```cpp
int myBadMethod(const nlohmann::json& j){
const int* myPtr = j.get_if<int>();
return *myPtr;
@@ -20,21 +20,21 @@
This pointer is not guaranteed to be filled, and could be a null dereference.
-### 2. String views aren't null terminated
+## 2. String views aren't null terminated
-```C++
+```cpp
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
+## 3. Not handling input errors
-```C++
+```cpp
int getIntFromString(const std::string& s){
return std::atoi(s.c_str());
}
@@ -42,12 +42,12 @@
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
-code.
+string, ideally with something like `from_chars`, and return the appropriate
+error code.
-### 4. Walking off the end of a string
+## 4. Walking off the end of a string
-```C++
+```cpp
std::string getFilenameFromPath(const std::string& path){
size_t index = path.find("/");
if (index != std::string::npos){
@@ -58,9 +58,9 @@
}
```
-### 5. Using methods that throw (or not handling bad inputs)
+## 5. Using methods that throw (or not handling bad inputs)
-```C++
+```cpp
int myBadMethod(nlohmann::json& j){
return j.get<int>();
}
@@ -90,7 +90,7 @@
- std::stol
- std::stoll
-#### Special note: JSON
+### Special note: JSON
`nlohmann::json::parse` by default
[throws](https://json.nlohmann.me/api/basic_json/parse/) on failure, but also
@@ -103,7 +103,7 @@
to `replace`. Although `ignore` preserves content 1:1, `replace` is preferred
from a security point of view.
-#### Special note: Boost
+### 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
@@ -116,7 +116,7 @@
- boost::asio::ip::tcp::acceptor::listen();
- boost::asio::ip::address::make_address();
-### 6. Blocking functions
+## 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
@@ -138,7 +138,7 @@
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
+## 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
@@ -146,7 +146,7 @@
must be always left in a valid state, and checked for other uses before
occupying.
-```C++
+```cpp
std::optional<std::string> currentOperation;
void firstCallbackInFlow(){
currentOperation = "Foo";
@@ -159,9 +159,9 @@
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
+## 8. Wildcard reference captures in lambdas
-```
+```cpp
std::string x; auto mylambda = [&](){
x = "foo";
}
@@ -173,11 +173,12 @@
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
-[&x]()... Which makes clear that x is captured, and its lifetime needs tracked.
+`[&x]()...` Which makes clear that x is captured, and its lifetime needs
+tracked.
-### 9. URLs should end in "/"
+## 9. URLs should end in "/"
-```C++
+```cpp
BMCWEB("/foo/bar");
```
@@ -188,9 +189,9 @@
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
+## 10. URLs constructed in aggregate
-```C++
+```cpp
std::string routeStart = "/redfish/v1";
BMCWEB_ROUTE(routestart + "/SessionService/")
@@ -203,9 +204,9 @@
the route handlers no longer greppable, and complicates bmcweb patchsets as a
whole.
-### 11. Not responding to 404
+## 11. Not responding to 404
-```C++
+```cpp
BMCWEB_ROUTE("/myendpoint/<str>",
[](Request& req, Response& res, const std::string& id){
crow::connections::systemBus->async_method_call(
@@ -228,16 +229,16 @@
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.
+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++
+```cpp
BMCWEB_ROUTE("/myendpoint/<str>",
[](Request& req, Response& res, const std::string& id){
crow::connections::systemBus->async_method_call(
@@ -265,9 +266,9 @@
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
+## 12. Imprecise matching
-```C++
+```cpp
void isInventoryPath(const std::string& path){
if (path.find("inventory")){
return true;
@@ -281,7 +282,7 @@
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.
@@ -300,9 +301,9 @@
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
+## 13. Complete replacement of the response object
-```
+```cpp
void getMembers(crow::Response& res){
res.jsonValue = {{"Value", 2}};
}
@@ -314,7 +315,7 @@
output of the response is dependent on the _order_ of the asynchronous actions
completing, which cannot be guaranteed, and has many time caused bugs.
-```
+```cpp
void getMembers(crow::Response& res){
res.jsonValue["Value"] = 2;
}
diff --git a/DBUS_USAGE.md b/DBUS_USAGE.md
index 75a36c7..577bf9f 100644
--- a/DBUS_USAGE.md
+++ b/DBUS_USAGE.md
@@ -1,3 +1,5 @@
+# dbus usage
+
The following are guidelines for bmcweb's use of DBus to construct Redfish
schemas:
diff --git a/DEVELOPING.md b/DEVELOPING.md
index d475d53..77cfece 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -1,150 +1,151 @@
# OpenBMC Webserver Development
-1. ### Performance targets
+## Guidelines
- 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:
+### Performance targets
- - 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:
-2. ### Asynchronous programming
+- 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)
- Care should be taken to ensure that all code is written to be asynchronous in
- nature, to avoid blocking methods from stopping the processing of other
- tasks. At this time the webserver uses boost::asio for it async framework.
- Threads should be avoided if possible, and instead use async tasks within
- boost::asio.
+### Asynchronous programming
-3. ### Secure coding guidelines
+Care should be taken to ensure that all code is written to be asynchronous in
+nature, to avoid blocking methods from stopping the processing of other tasks.
+At this time the webserver uses boost::asio for it async framework. Threads
+should be avoided if possible, and instead use async tasks within boost::asio.
- Secure coding practices should be followed in all places in the webserver
+### Secure coding guidelines
- In general, this means:
+Secure coding practices should be followed in all places in the webserver
- - 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:
-4. ### Error handling
+- 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")
- 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
+### Error handling
- - 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
+Error handling should be constructed in such a way that all possible errors
+return valid HTTP responses. The following HTTP codes will be used commonly
- Where possible, 307 and 308 redirects should be avoided, as they introduce
- the possibility for subtle security bugs.
+- 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
-5. ### Startup times
+Where possible, 307 and 308 redirects should be avoided, as they introduce the
+possibility for subtle security bugs.
- Given that the most common target of OpenBMC is an ARM11 processor, care
- needs to be taken to ensure startup times are low. In general this means:
+### Startup times
- - Minimizing the number of files read from disk at startup. Unless a feature
- is explicitly intended to be runtime configurable, its logic should be
- "baked in" to the application at compile time. For cases where the
- implementation is configurable at runtime, the default values should be
- included in application code to minimize the use of nonvolatile storage.
- - Avoid excessive memory usage and mallocs at startup.
+Given that the most common target of OpenBMC is an ARM11 processor, care needs
+to be taken to ensure startup times are low. In general this means:
-6. ### Compiler features
+- 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.
- - 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
+### Compiler features
-7. ### Authentication
+- 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
- The webserver shall provide the following authentication mechanisms.
+### Authentication
- - Basic authentication
- - Cookie authentication
- - Token authentication
+The webserver shall provide the following authentication mechanisms.
- There shall be connection between the authentication mechanism used and
- resources that are available over it. The webserver shall employ an
- authentication scheme that is in line with the rest of OpenBMC, and allows
- users and privileges to be provisioned from other interfaces.
+- Basic authentication
+- Cookie authentication
+- Token authentication
-8. ### Web security
+There shall be connection between the authentication mechanism used and
+resources that are available over it. The webserver shall employ an
+authentication scheme that is in line with the rest of OpenBMC, and allows users
+and privileges to be provisioned from other interfaces.
- The OpenBMC webserver shall follow the latest OWASP recommendations for
- authentication, session management, and security.
+### Web security
-9. ### Performance
+The OpenBMC webserver shall follow the latest OWASP recommendations for
+authentication, session management, and security.
- The performance priorities for the OpenBMC webserver are (in order):
+### Performance
- 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)
+The performance priorities for the OpenBMC webserver are (in order):
-10. ### Abstraction/interfacing
+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)
- 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.
+### Abstraction/interfacing
-11. ### phosphor webui
+In general, the OpenBMC webserver is built using the data driven design.
+Abstraction and Interface guarantees should be used when multiple
+implementations exist, but for implementations where only a single
+implementation exists, prefer to make the code correct and clean rather than
+implement a concrete interface.
- The webserver should be capable of hosting phosphor-webui, and implementing
- the required flows to host the application. In general, all access methods
- should be available to the webui.
+### phosphor webui
-12. ### Redfish
+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.
- 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).
+### Redfish
-13. ### Common errors
+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).
- 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).
+### Common errors
-14. ### Commit messages
- Project commit message formatting should be obeyed
- [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages)
+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).
+
+### 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:
@@ -162,9 +163,10 @@
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)
+### Compatibility
+
+> Don't make your users mad -
+> [Greg K-H](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.
diff --git a/HEADERS.md b/HEADERS.md
index 75f142e..1a9c849 100644
--- a/HEADERS.md
+++ b/HEADERS.md
@@ -1,6 +1,8 @@
-## Why does bmcweb use so many headers? My build times are slow!##
+# bmcweb headers
-TL; DR, History
+**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.
@@ -19,7 +21,7 @@
of this document is largely to save effort for the next person, so they can at
least start from the existing prior attempts.
-https://gerrit.openbmc.org/c/openbmc/bmcweb/+/49039
+<https://gerrit.openbmc.org/c/openbmc/bmcweb/+/49039>
Moving to cpp files without handling any architecture has the net result of
making total compilation slower, not faster, as the slowest-to-compile parts end
@@ -31,7 +33,7 @@
- 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
+ <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
diff --git a/OEM_SCHEMAS.md b/OEM_SCHEMAS.md
index c30e508..0758097 100644
--- a/OEM_SCHEMAS.md
+++ b/OEM_SCHEMAS.md
@@ -1,4 +1,4 @@
-## Redfish OEM Resources
+# 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
@@ -6,7 +6,7 @@
OEM properties in a backward API compatible way for resources that have not been
merged to master.
-### Why?
+## 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,
@@ -40,7 +40,7 @@
leads to positive API design changes up front, which increases the usefulness
of the code we write within the industry.
-### How?
+## How?
If you've read the above, and still think an OEM property is warranted, please
take the following steps.
diff --git a/README.md b/README.md
index 01b0c1a..8abaa61 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
to dbus and the objects it represents.
- Serial: A serial websocket for interacting with the host serial console
through websockets.
-- Redfish: A protocol compliant, (Redfish.md)[DBus to Redfish translator].
+- Redfish: A protocol compliant, [DBus to Redfish translator](Redfish.md).
- KVM: A websocket based implementation of the RFB (VNC) frame buffer protocol
intended to mate to webui-vue to provide a complete KVM implementation.
@@ -50,9 +50,9 @@
bmcweb is configured per the
[meson build files](https://mesonbuild.com/Build-options.html). Available
-options are documented in meson_options.txt
+options are documented in `meson_options.txt`
-## Compile bmcweb with default options:
+## Compile bmcweb with default options
```ascii
meson builddir
@@ -83,7 +83,7 @@
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
-read/written can seen from the persistent_data namespace.
+read/written can seen from the `persistent_data` namespace.
## TLS certificate generation
diff --git a/Redfish.md b/Redfish.md
index d302f78..cc714eb 100644
--- a/Redfish.md
+++ b/Redfish.md
@@ -18,7 +18,7 @@
[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.
+schema list in `scripts/update_schemas.py` and run `update_schemas.py`.
Fields common to all schemas
@@ -27,9 +27,9 @@
- Id
- Name
-#### /redfish/v1/
+### /redfish/v1/
-##### ServiceRoot
+#### ServiceRoot
- AccountService
- CertificateService
@@ -47,9 +47,9 @@
- UUID
- UpdateService
-#### /redfish/v1/AccountService/
+### /redfish/v1/AccountService/
-##### AccountService
+#### AccountService
- AccountLockoutDuration
- AccountLockoutThreshold
@@ -66,17 +66,17 @@
- Roles
- ServiceEnabled
-#### /redfish/v1/AccountService/Accounts/
+### /redfish/v1/AccountService/Accounts/
-##### ManagerAccountCollection
+#### ManagerAccountCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/AccountService/Accounts/{ManagerAccountId}/
+### /redfish/v1/AccountService/Accounts/{ManagerAccountId}/
-##### ManagerAccount
+#### ManagerAccount
- AccountTypes
- Description
@@ -89,26 +89,26 @@
- RoleId
- UserName
-#### /redfish/v1/AccountService/LDAP/Certificates/
+### /redfish/v1/AccountService/LDAP/Certificates/
-##### CertificateCollection
+#### CertificateCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/AccountService/Roles/
+### /redfish/v1/AccountService/Roles/
-##### RoleCollection
+#### RoleCollection
- Description
- Members
- By default will contain 3 roles, "Administrator", "Operator", and "ReadOnly"
- Members@odata.count
-#### /redfish/v1/AccountService/Roles/{RoleId}/
+### /redfish/v1/AccountService/Roles/{RoleId}/
-##### Role
+#### Role
- AssignedPrivileges
- For the default roles, the following privileges will be assigned by default
@@ -123,32 +123,32 @@
- OemPrivileges
- RoleId
-#### /redfish/v1/CertificateService/
+### /redfish/v1/CertificateService/
-##### CertificateService
+#### CertificateService
- Actions
- CertificateLocations
- Description
-#### /redfish/v1/CertificateService/CertificateLocations/
+### /redfish/v1/CertificateService/CertificateLocations/
-##### CertificateLocations
+#### CertificateLocations
- Description
- Links/Certificates
- Links/Certificates@odata.count
-#### /redfish/v1/Chassis/
+### /redfish/v1/Chassis/
-##### ChassisCollection
+#### ChassisCollection
- Members
- Members@odata.count
-#### /redfish/v1/Chassis/{ChassisId}/
+### /redfish/v1/Chassis/{ChassisId}/
-##### Chassis
+#### Chassis
- Actions
- ChassisType
@@ -165,14 +165,14 @@
- Shall be included if component contains temperature sensors, otherwise shall
be omitted.
-#### /redfish/v1/Chassis/{ChassisId}/Drive/
+### /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")
+ Drives, The name of the association is `chassis<->drive`)
-#### /redfish/v1/Chassis/{ChassisId}/Drive/{DriveId}/
+### /redfish/v1/Chassis/{ChassisId}/Drive/{DriveId}/
#### Drive
@@ -181,30 +181,30 @@
- Status (this is dependant on a entity manager association from Chassis to
Drives)
-#### /redfish/v1/Chassis/{ChassisId}/EnvironmentMetrics/
+### /redfish/v1/Chassis/{ChassisId}/EnvironmentMetrics/
-##### EnvironmentMetrics
+#### EnvironmentMetrics
-#### /redfish/v1/Chassis/{ChassisId}/Power/
+### /redfish/v1/Chassis/{ChassisId}/Power/
-##### Power
+#### Power
- PowerControl
- PowerSupplies
- Redundancy
- Voltages
-#### /redfish/v1/Chassis/{ChassisId}/Sensors/
+### /redfish/v1/Chassis/{ChassisId}/Sensors/
-##### SensorCollection
+#### SensorCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Chassis/{ChassisId}/Sensors/{Id}/
+### /redfish/v1/Chassis/{ChassisId}/Sensors/{Id}/
-##### Sensor
+#### Sensor
- Reading
- ReadingRangeMax
@@ -214,17 +214,17 @@
- Status
- Thresholds
-#### /redfish/v1/Chassis/{ChassisId}/Thermal/
+### /redfish/v1/Chassis/{ChassisId}/Thermal/
-##### Thermal
+#### Thermal
- Fans
- Redundancy
- Temperatures
-#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Temperatures/{SensorName}/
+### /redfish/v1/Chassis/{ChassisId}/Thermal#/Temperatures/{SensorName}/
-##### Temperature
+#### Temperature
- MemberId
- Status
@@ -237,9 +237,9 @@
- MaxReadingRange _threshold fields only present if defined for sensor,
otherwise absent_
-#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Fans/{FanName}/
+### /redfish/v1/Chassis/{ChassisId}/Thermal#/Fans/{FanName}/
-##### Fan
+#### Fan
- MemberId
- Status
@@ -254,9 +254,9 @@
- Redundancy _threshold fields only present if defined for sensor, otherwise
absent_
-#### /redfish/v1/Chassis/{ChassisId}/Thermal#/Redundancy/{RedundancyName}/
+### /redfish/v1/Chassis/{ChassisId}/Thermal#/Redundancy/{RedundancyName}/
-##### Redundancy
+#### Redundancy
- MemberId
- RedundancySet
@@ -265,21 +265,15 @@
- MinNumNeeded
- MaxNumSupported
-#### /redfish/v1/Chassis/{ChassisId}/ThermalSubsystem
+### /redfish/v1/Chassis/{ChassisId}/ThermalSubsystem
-##### ThermalSubsystem
+#### ThermalSubsystem
- Status
-#### /redfish/v1/Chassis/{ChassisId}/Power/
+### /redfish/v1/Chassis/{ChassisId}/Power#/PowerControl/{ControlName}/
-##### Power
-
-PowerControl Voltages PowerSupplies Redundancy
-
-#### /redfish/v1/Chassis/{ChassisId}/Power#/PowerControl/{ControlName}/
-
-##### PowerControl
+#### PowerControl
- MemberId
- PowerConsumedWatts
@@ -290,9 +284,9 @@
- RelatedItem
- Should list systems and related chassis
-#### /redfish/v1/Chassis/{ChassisId}/Power#/Voltages/{VoltageName}/
+### /redfish/v1/Chassis/{ChassisId}/Power#/Voltages/{VoltageName}/
-##### Voltage
+#### Voltage
- MemberId
- Status
@@ -306,9 +300,9 @@
- PhysicalContext
- RelatedItem
-#### /redfish/v1/Chassis/{ChassisId}/Power#/PowerSupplies/{PSUName}/
+### /redfish/v1/Chassis/{ChassisId}/Power#/PowerSupplies/{PSUName}/
-##### PowerSupply
+#### PowerSupply
- MemberId
- Status
@@ -321,9 +315,9 @@
- RelatedItem
- Redundancy
-#### /redfish/v1/Chassis/{ChassisId}/Power#/Redundancy/{RedundancyName}/
+### /redfish/v1/Chassis/{ChassisId}/Power#/Redundancy/{RedundancyName}/
-##### Redundancy
+#### Redundancy
- MemberId
- RedundancySet
@@ -332,9 +326,9 @@
- MinNumNeeded
- MaxNumSupported
-#### /redfish/v1/EventService/
+### /redfish/v1/EventService/
-##### EventService
+#### EventService
- Actions
- DeliveryRetryAttempts
@@ -348,16 +342,16 @@
- Status
- Subscriptions
-#### /redfish/v1/EventService/Subscriptions/
+### /redfish/v1/EventService/Subscriptions/
-##### EventDestinationCollection
+#### EventDestinationCollection
- Members
- Members@odata.count
-#### /redfish/v1/EventService/Subscriptions/{EventName}/
+### /redfish/v1/EventService/Subscriptions/{EventName}/
-##### EventDestination
+#### EventDestination
- Id
- Destination
@@ -366,17 +360,17 @@
- OriginResources
- Protocol
-#### /redfish/v1/JsonSchemas/
+### /redfish/v1/JsonSchemas/
-##### JsonSchemaFileCollection
+#### JsonSchemaFileCollection
- Description
- Members@odata.count
- Members
-#### /redfish/v1/JsonSchemas/{Id}/
+### /redfish/v1/JsonSchemas/{Id}/
-##### JsonSchemaFile
+#### JsonSchemaFile
- Schema
- Description
@@ -385,16 +379,16 @@
- Location
- Location@odata.count
-#### /redfish/v1/Managers/
+### /redfish/v1/Managers/
-##### ManagerCollection
+#### ManagerCollection
- Members
- Members@odata.count
-#### /redfish/v1/Managers/bmc/
+### /redfish/v1/Managers/bmc/
-##### Manager
+#### Manager
- Actions
- DateTime
@@ -427,17 +421,17 @@
- Status
- UUID
-#### /redfish/v1/Managers/bmc/EthernetInterfaces/
+### /redfish/v1/Managers/bmc/EthernetInterfaces/
-##### EthernetInterfaceCollection
+#### EthernetInterfaceCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/
+### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/
-##### EthernetInterface
+#### EthernetInterface
- DHCPv4
- DHCPv6
@@ -459,14 +453,14 @@
- Status
- VLANs
-#### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/VLANs/
+### /redfish/v1/Managers/bmc/EthernetInterfaces/{EthernetInterfaceId}/VLANs/
-##### VLanNetworkInterfaceCollection
+#### VLanNetworkInterfaceCollection
- Members
- Members@odata.count
-#### /redfish/v1/Managers/bmc/LogServices/
+### /redfish/v1/Managers/bmc/LogServices/
The [LogService][2] resource provides properties for monitoring and configuring
events for the service or resource to which it is associated.
@@ -493,17 +487,15 @@
These two implementations do not work together, so choosing one will disable the
other.
-#### /redfish/v1/Managers/bmc/LogServices/
-
-##### LogServiceCollection
+#### LogServiceCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Managers/bmc/LogServices/RedfishLog/
+### /redfish/v1/Managers/bmc/LogServices/RedfishLog/
-##### LogService
+#### LogService
- Entries
- OverWritePolicy
@@ -512,17 +504,17 @@
- DateTime
- MaxNumberOfRecords
-#### /redfish/v1/Managers/bmc/LogServices/RedfishLog/Entries/{LogEntryId}/
+### /redfish/v1/Managers/bmc/LogServices/RedfishLog/Entries/{LogEntryId}/
-##### LogEntry
+#### LogEntry
- Message
- Created
- EntryType
-#### /redfish/v1/Managers/bmc/NetworkProtocol/
+### /redfish/v1/Managers/bmc/NetworkProtocol/
-##### ManagerNetworkProtocol
+#### ManagerNetworkProtocol
- Description
- FQDN
@@ -534,17 +526,17 @@
- SSH
- Status
-#### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/
+### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/
-##### CertificateCollection
+#### CertificateCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/{CertificateId}/
+### /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/{CertificateId}/
-##### Certificate
+#### Certificate
- CertificateString
- Description
@@ -554,25 +546,25 @@
- ValidNotAfter
- ValidNotBefore
-#### /redfish/v1/Managers/bmc/Truststore/Certificates/
+### /redfish/v1/Managers/bmc/Truststore/Certificates/
-##### CertificateCollection
+#### CertificateCollection
- Description
- error
-#### /redfish/v1/Registries/
+### /redfish/v1/Registries/
-##### MessageRegistryFileCollection
+#### MessageRegistryFileCollection
- Description
- Members
- Should support Base, CommonMessages, and EventingMessages
- Members@odata.count
-#### /redfish/v1/Registries/{MessageRegistryFileId}/
+### /redfish/v1/Registries/{MessageRegistryFileId}/
-##### MessageRegistryFile
+#### MessageRegistryFile
- Description
- Languages
@@ -581,43 +573,43 @@
- Location@odata.count
- Registry
-#### /redfish/v1/SessionService/
+### /redfish/v1/SessionService/
-##### SessionService
+#### SessionService
- Description
- ServiceEnabled
- SessionTimeout
- Sessions
-#### /redfish/v1/SessionService/Sessions/
+### /redfish/v1/SessionService/Sessions/
-##### SessionCollection
+#### SessionCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/SessionService/Sessions/{SessionId}/
+### /redfish/v1/SessionService/Sessions/{SessionId}/
-##### Session
+#### Session
- ClientOriginIPAddress
- Description
- Oem
- UserName
-#### /redfish/v1/Systems/
+### /redfish/v1/Systems/
-##### ComputerSystemCollection
+#### ComputerSystemCollection
- Members
- Should support one system
- Members@odata.count
-#### /redfish/v1/Systems/system/Bios/
+### /redfish/v1/Systems/system/Bios/
-##### Bios
+#### Bios
- Actions
- Description
@@ -625,9 +617,9 @@
- Links/SoftwareImages
- Links/SoftwareImages@odata.count
-#### /redfish/v1/Systems/system/
+### /redfish/v1/Systems/system/
-##### ComputerSystem
+#### ComputerSystem
- Actions
- AssetTag
@@ -664,26 +656,26 @@
- SubModel
- SystemType
-#### /redfish/v1/Systems/system/EthernetInterfaces/
+### /redfish/v1/Systems/system/EthernetInterfaces/
-##### EthernetInterfaceCollection
+#### EthernetInterfaceCollection
- Members
- Members@odata.count
- Description
-#### /redfish/v1/Systems/system/LogServices/
+### /redfish/v1/Systems/system/LogServices/
-##### LogServiceCollection
+#### LogServiceCollection
- Description
- Members
- Should default to one member, named SEL
- Members@odata.count
-#### /redfish/v1/Systems/system/LogServices/EventLog/
+### /redfish/v1/Systems/system/LogServices/EventLog/
-##### LogService
+#### LogService
- Actions
- DateTime
@@ -692,17 +684,17 @@
- Entries
- OverWritePolicy
-#### /redfish/v1/Systems/system/LogServices/EventLog/Entries/
+### /redfish/v1/Systems/system/LogServices/EventLog/Entries/
-##### LogEntryCollection
+#### LogEntryCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Systems/system/LogServices/EventLog/Entries/{LogEntryId}/
+### /redfish/v1/Systems/system/LogServices/EventLog/Entries/{LogEntryId}/
-##### LogEntry
+#### LogEntry
- AdditionalDataURI
- Created
@@ -712,18 +704,18 @@
- Resolved
- Severity
-#### /redfish/v1/Systems/system/LogServices/SEL/Entries/
+### /redfish/v1/Systems/system/LogServices/SEL/Entries/
-##### LogEntryCollection
+#### LogEntryCollection
- Members
- Members@odata.count
- Description
- @odata.nextLink
-#### /redfish/v1/Systems/system/LogServices/SEL/Entries/{LogEntryId}/
+### /redfish/v1/Systems/system/LogServices/SEL/Entries/{LogEntryId}/
-##### LogEntry
+#### LogEntry
- MessageArgs
- Severity
@@ -734,16 +726,16 @@
- EntryCode
- EntryType
-#### /redfish/v1/Systems/system/Memory/
+### /redfish/v1/Systems/system/Memory/
-##### MemoryCollection
+#### MemoryCollection
- Members
- Members@odata.count
-#### /redfish/v1/Systems/system/Memory/{MemoryId}/
+### /redfish/v1/Systems/system/Memory/{MemoryId}/
-##### Memory
+#### Memory
- AllowedSpeedsMHz
- BaseModuleType
@@ -761,32 +753,32 @@
- SparePartNumber
- Status
-#### /redfish/v1/Systems/system/Memory/{MemoryId}/MemoryMetrics/
+### /redfish/v1/Systems/system/Memory/{MemoryId}/MemoryMetrics/
-##### MemoryMetrics
+#### MemoryMetrics
- Description
- HealthData
-#### /redfish/v1/Systems/system/PCIeDevices/
+### /redfish/v1/Systems/system/PCIeDevices/
-##### PCIeDeviceCollection
+#### PCIeDeviceCollection
- Description
- Members
- Members@odata.count
-#### /redfish/v1/Systems/system/Processors/
+### /redfish/v1/Systems/system/Processors/
-##### ProcessorCollection
+#### ProcessorCollection
- Members
- Should Support CPU1 and CPU2 for dual socket systems
- Members@odata.count
-#### /redfish/v1/Systems/system/Processors/{ProcessorId}/
+### /redfish/v1/Systems/system/Processors/{ProcessorId}/
-##### Processor
+#### Processor
- InstructionSet
- Manufacturer
@@ -803,32 +795,32 @@
- TotalThreads
- Version
-#### /redfish/v1/Systems/system/Storage/
+### /redfish/v1/Systems/system/Storage/
-##### StorageCollection
+#### StorageCollection
- Members
- Members@odata.count
-#### /redfish/v1/Systems/system/Storage/{StorageId}/
+### /redfish/v1/Systems/system/Storage/{StorageId}/
-##### Storage
+#### Storage
- Drives
- Drives@odata.count
- Status
-#### /redfish/v1/Systems/system/Storage/{StorageId}/Drive/{DriveId}/
+### /redfish/v1/Systems/system/Storage/{StorageId}/Drive/{DriveId}/
-##### Storage
+#### Storage
- CapacityBytes
- Links
- Status
-#### /redfish/v1/TaskService/
+### /redfish/v1/TaskService/
-##### TaskService
+#### TaskService
- CompletedTaskOverWritePolicy
- DateTime
@@ -837,16 +829,16 @@
- Status
- Tasks
-#### /redfish/v1/TaskService/Tasks/
+### /redfish/v1/TaskService/Tasks/
-##### TaskCollection
+#### TaskCollection
- Members
- Members@odata.count
-#### /redfish/v1/TelemetryService/
+### /redfish/v1/TelemetryService/
-##### TelemetryService
+#### TelemetryService
- MaxReports
- MetricReportDefinitions
@@ -855,30 +847,30 @@
- Status
- Triggers
-#### /redfish/v1/TelemetryService/MetricReportDefinitions/
+### /redfish/v1/TelemetryService/MetricReportDefinitions/
-##### MetricReportDefinitionCollection
+#### MetricReportDefinitionCollection
- Members
- Members@odata.count
-#### /redfish/v1/TelemetryService/MetricReports/
+### /redfish/v1/TelemetryService/MetricReports/
-##### MetricReportCollection
+#### MetricReportCollection
- Members
- Members@odata.count
-#### /redfish/v1/TelemetryService/Triggers/
+### /redfish/v1/TelemetryService/Triggers/
-##### TriggersCollection
+#### TriggersCollection
- Members
- Members@odata.count
-#### /redfish/v1/UpdateService/
+### /redfish/v1/UpdateService/
-##### UpdateService
+#### UpdateService
- Actions
- Description
@@ -888,17 +880,17 @@
- MaxImageSizeBytes
- ServiceEnabled
-#### /redfish/v1/UpdateService/FirmwareInventory/
+### /redfish/v1/UpdateService/FirmwareInventory/
-##### SoftwareInventoryCollection
+#### SoftwareInventoryCollection
- Members
- Should Support BMC, ME, CPLD and BIOS
- Members@odata.count
-#### /redfish/v1/UpdateService/FirmwareInventory/{SoftwareInventoryId}/
+### /redfish/v1/UpdateService/FirmwareInventory/{SoftwareInventoryId}/
-##### SoftwareInventory
+#### SoftwareInventory
- Description
- RelatedItem@odata.count
diff --git a/TESTING.md b/TESTING.md
index f335392..e1112e7 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -19,7 +19,7 @@
directions in the gerrit setup document.
- Clone bmcweb from gerrit
- ```
+ ```sh
git clone ssh://openbmc.gerrit/openbmc/bmcweb/
```
@@ -28,7 +28,7 @@
- Reduce binary size by stripping it when ready for testing
- ```
+ ```sh
arm-openbmc-linux-gnueabi-strip bmcweb
```
@@ -38,7 +38,7 @@
- Copy your bmcweb you want to test to /tmp/ in QEMU
- ```
+ ```sh
scp -P 2222 bmcweb root@127.0.0.1:/tmp/
```
@@ -48,7 +48,7 @@
- Stop bmcweb service within your QEMU session
- ```
+ ```sh
systemctl stop bmcweb
```
@@ -61,7 +61,7 @@
- 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
- ```
+ ```sh
mkdir -p /var/persist/usr
mkdir -p /var/persist/work/usr
mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr
@@ -69,20 +69,20 @@
- Remove the existing bmcweb from the filesystem in QEMU
- ```
+ ```sh
rm /usr/bin/bmcweb
```
- Link to your new bmcweb in /tmp/
- ```
+ ```sh
ln -sf /tmp/bmcweb /usr/bin/bmcweb
```
- Test your changes. bmcweb will be started automatically upon your first REST
or Redfish command
- ```
+ ```sh
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
```