1dfa3fdc3SPatrick Williams# OpenBMC webserver 2038c52e0SEd Tanous 3d2b83cfeSEd TanousThis component attempts to be a "do everything" embedded webserver for OpenBMC. 4038c52e0SEd Tanous 5dfa3fdc3SPatrick Williams## Features 6038c52e0SEd Tanous 7d2b83cfeSEd TanousThe webserver implements a few distinct interfaces: 8dfa3fdc3SPatrick Williams 9dfa3fdc3SPatrick Williams- DBus event websocket. Allows registering on changes to specific dbus paths, 10d2b83cfeSEd Tanous properties, and will send an event from the websocket if those filters match. 11dfa3fdc3SPatrick Williams- OpenBMC DBus REST api. Allows direct, low interference, high fidelity access 12d2b83cfeSEd Tanous to dbus and the objects it represents. 13dfa3fdc3SPatrick Williams- Serial: A serial websocket for interacting with the host serial console 14d2b83cfeSEd Tanous through websockets. 15f4f2643aSPatrick Williams- Redfish: A protocol compliant, [DBus to Redfish translator](Redfish.md). 16dfa3fdc3SPatrick Williams- KVM: A websocket based implementation of the RFB (VNC) frame buffer protocol 17d2b83cfeSEd Tanous intended to mate to webui-vue to provide a complete KVM implementation. 18d2b83cfeSEd Tanous 19dfa3fdc3SPatrick Williams## Protocols 20dfa3fdc3SPatrick Williams 21d2b83cfeSEd Tanousbmcweb at a protocol level supports http and https. TLS is supported through 22d2b83cfeSEd TanousOpenSSL. 23d2b83cfeSEd Tanous 24dfa3fdc3SPatrick Williams## AuthX 25dfa3fdc3SPatrick Williams 26dfa3fdc3SPatrick Williams### Authentication 27dfa3fdc3SPatrick Williams 28d2b83cfeSEd TanousBmcweb supports multiple authentication protocols: 29dfa3fdc3SPatrick Williams 30dfa3fdc3SPatrick Williams- Basic authentication per RFC7617 31dfa3fdc3SPatrick Williams- Cookie based authentication for authenticating against webui-vue 32dfa3fdc3SPatrick Williams- Mutual TLS authentication based on OpenSSL 33dfa3fdc3SPatrick Williams- Session authentication through webui-vue 34dfa3fdc3SPatrick Williams- XToken based authentication conformant to Redfish DSP0266 35d2b83cfeSEd Tanous 36d2b83cfeSEd TanousEach of these types of authentication is able to be enabled or disabled both via 37d2b83cfeSEd Tanousruntime policy changes (through the relevant Redfish APIs) or via configure time 38d2b83cfeSEd Tanousoptions. All authentication mechanisms supporting username/password are routed 39d2b83cfeSEd Tanousto libpam, to allow for customization in authentication implementations. 40d2b83cfeSEd Tanous 41dfa3fdc3SPatrick Williams### Authorization 42dfa3fdc3SPatrick Williams 43d2b83cfeSEd TanousAll authorization in bmcweb is determined at routing time, and per route, and 44d2b83cfeSEd Tanousconform to the Redfish PrivilegeRegistry. 45d2b83cfeSEd Tanous 46dfa3fdc3SPatrick Williams\*Note: Non-Redfish functions are mapped to the closest equivalent Redfish 47d2b83cfeSEd Tanousprivilege level. 48038c52e0SEd Tanous 49976596bcSJoseph Reynolds## Configuration 50976596bcSJoseph Reynolds 51d2b83cfeSEd Tanousbmcweb is configured per the 52d2b83cfeSEd Tanous[meson build files](https://mesonbuild.com/Build-options.html). Available 53f4f2643aSPatrick Williamsoptions are documented in `meson_options.txt` 54976596bcSJoseph Reynolds 55f4f2643aSPatrick Williams## Compile bmcweb with default options 56dfa3fdc3SPatrick Williams 57af6298daSManojkiran Eda```ascii 58*adfc6dd8SGunnar Millsmeson setup builddir 59af6298daSManojkiran Edaninja -C builddir 60af6298daSManojkiran Eda``` 61d2b83cfeSEd Tanous 62af6298daSManojkiran EdaIf any of the dependencies are not found on the host system during 63d2b83cfeSEd Tanousconfiguration, meson will automatically download them via its wrap dependencies 64af6298daSManojkiran Edamentioned in `bmcweb/subprojects`. 65af6298daSManojkiran Eda 66d2b83cfeSEd Tanous## Use of persistent data 67dfa3fdc3SPatrick Williams 68d2b83cfeSEd Tanousbmcweb relies on some on-system data for storage of persistent data that is 69d2b83cfeSEd Tanousinternal to the process. Details on the exact data stored and when it is 70f4f2643aSPatrick Williamsread/written can seen from the `persistent_data` namespace. 71d2b83cfeSEd Tanous 72d2b83cfeSEd Tanous## TLS certificate generation 73038c52e0SEd Tanous 74dfa3fdc3SPatrick WilliamsWhen SSL support is enabled and a usable certificate is not found, bmcweb will 75dfa3fdc3SPatrick Williamsgenerate a self-signed a certificate before launching the server. Please see the 76dfa3fdc3SPatrick Williamsbmcweb source code for details on the parameters this certificate is built with. 77a88562deSCarson Labrado 78a88562deSCarson Labrado## Redfish Aggregation 79a88562deSCarson Labrado 80a88562deSCarson Labradobmcweb is capable of aggregating resources from satellite BMCs. Refer to 81a88562deSCarson Labrado[AGGREGATION.md](https://github.com/openbmc/bmcweb/blob/master/AGGREGATION.md) 82a88562deSCarson Labradofor more information on how to enable and use this feature. 83