1*dfa3fdc3SPatrick Williams# OpenBMC webserver 2038c52e0SEd Tanous 3d2b83cfeSEd TanousThis component attempts to be a "do everything" embedded webserver for OpenBMC. 4038c52e0SEd Tanous 5*dfa3fdc3SPatrick Williams## Features 6038c52e0SEd Tanous 7d2b83cfeSEd TanousThe webserver implements a few distinct interfaces: 8*dfa3fdc3SPatrick Williams 9*dfa3fdc3SPatrick 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. 11*dfa3fdc3SPatrick Williams- OpenBMC DBus REST api. Allows direct, low interference, high fidelity access 12d2b83cfeSEd Tanous to dbus and the objects it represents. 13*dfa3fdc3SPatrick Williams- Serial: A serial websocket for interacting with the host serial console 14d2b83cfeSEd Tanous through websockets. 15*dfa3fdc3SPatrick Williams- Redfish: A protocol compliant, (Redfish.md)[DBus to Redfish translator]. 16*dfa3fdc3SPatrick 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 19*dfa3fdc3SPatrick Williams## Protocols 20*dfa3fdc3SPatrick Williams 21d2b83cfeSEd Tanousbmcweb at a protocol level supports http and https. TLS is supported through 22d2b83cfeSEd TanousOpenSSL. 23d2b83cfeSEd Tanous 24*dfa3fdc3SPatrick Williams## AuthX 25*dfa3fdc3SPatrick Williams 26*dfa3fdc3SPatrick Williams### Authentication 27*dfa3fdc3SPatrick Williams 28d2b83cfeSEd TanousBmcweb supports multiple authentication protocols: 29*dfa3fdc3SPatrick Williams 30*dfa3fdc3SPatrick Williams- Basic authentication per RFC7617 31*dfa3fdc3SPatrick Williams- Cookie based authentication for authenticating against webui-vue 32*dfa3fdc3SPatrick Williams- Mutual TLS authentication based on OpenSSL 33*dfa3fdc3SPatrick Williams- Session authentication through webui-vue 34*dfa3fdc3SPatrick 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 41*dfa3fdc3SPatrick Williams### Authorization 42*dfa3fdc3SPatrick Williams 43d2b83cfeSEd TanousAll authorization in bmcweb is determined at routing time, and per route, and 44d2b83cfeSEd Tanousconform to the Redfish PrivilegeRegistry. 45d2b83cfeSEd Tanous 46*dfa3fdc3SPatrick 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 53d2b83cfeSEd Tanousoptions are documented in meson_options.txt 54976596bcSJoseph Reynolds 55d2b83cfeSEd Tanous## Compile bmcweb with default options: 56*dfa3fdc3SPatrick Williams 57af6298daSManojkiran Eda```ascii 58af6298daSManojkiran Edameson 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## Debug logging 67*dfa3fdc3SPatrick Williams 68d2b83cfeSEd Tanousbmcweb by default is compiled with runtime logging disabled, as a performance 69d2b83cfeSEd Tanousconsideration. To enable it in a standalone build, add the 70*dfa3fdc3SPatrick Williams 71af6298daSManojkiran Eda```ascii 72d2b83cfeSEd Tanous-Dlogging='enabled' 73af6298daSManojkiran Eda``` 74*dfa3fdc3SPatrick Williams 75*dfa3fdc3SPatrick Williamsoption to your configure flags. If building within Yocto, add the following to 76*dfa3fdc3SPatrick Williamsyour local.conf. 77*dfa3fdc3SPatrick Williams 78d2b83cfeSEd Tanous```bash 79d2b83cfeSEd TanousEXTRA_OEMESON:pn-bmcweb:append = "-Dbmcweb-logging='enabled'" 8092696982SChris Cain``` 81976596bcSJoseph Reynolds 82d2b83cfeSEd Tanous## Use of persistent data 83*dfa3fdc3SPatrick Williams 84d2b83cfeSEd Tanousbmcweb relies on some on-system data for storage of persistent data that is 85d2b83cfeSEd Tanousinternal to the process. Details on the exact data stored and when it is 86d2b83cfeSEd Tanousread/written can seen from the persistent_data namespace. 87d2b83cfeSEd Tanous 88d2b83cfeSEd Tanous## TLS certificate generation 89038c52e0SEd Tanous 90*dfa3fdc3SPatrick WilliamsWhen SSL support is enabled and a usable certificate is not found, bmcweb will 91*dfa3fdc3SPatrick Williamsgenerate a self-signed a certificate before launching the server. Please see the 92*dfa3fdc3SPatrick Williamsbmcweb source code for details on the parameters this certificate is built with. 93