SONiC Redfish implementation providing bmcweb and sonic-dbus-bridge as Debian packages.
- Overview
- Quick Start
- Build System
- Patch Management
- Cleanup Targets
- Dependency Management
- Components
- Configuration
- OEM Extension
- Testing
- Redfish API Endpoints
- License
This repository contains:
- bmcweb: OpenBMC web server source code with SONiC-specific patches
- sonic-dbus-bridge: Bridge between SONiC Redis and D-Bus for bmcweb integration
Both components are built as Debian packages (.deb) for easy integration with SONiC.
- Docker installed on your system
- Git
- sudo access (for cleaning root-owned build artifacts)
# Build all components AND run unit + integration tests (Docker-based)
make
# Or explicitly
make all
# Build the .deb packages only, without running any tests
make buildBuild artifacts will be available in target/debs/trixie/ (<arch> is the
build host architecture, e.g. arm64 or amd64):
bmcweb_1.0.0_<arch>.debbmcweb-dbg_1.0.0_<arch>.debsonic-dbus-bridge_1.0.0_<arch>.debsonic-dbus-bridge-dbgsym_1.0.0_<arch>.deb
Plus the matching .changes, .buildinfo and .dsc files.
# Show all available targets
make help
# Build both components, no tests
make build
# Build individual components (automatically runs clean + dependencies)
make build-bmcweb # Runs: clean -> setup-bmcweb -> copy-oem-extension -> apply-patches -> build
make build-bridge # Runs: clean -> build
# Run the test suites (see section 10)
make test # Redfish API integration tests (requires a prior build)
make unit-test # C++ gtest unit tests
# Clean build artifacts (removes build dirs and target/, resets bmcweb source)
make clean
# Complete reset (clean + delete bmcweb/ + remove Docker images)
make reset
# Remove a test container left behind by `make test NODELETE=1`
make clean-debug# Use custom number of parallel jobs (default: nproc)
make SONIC_CONFIG_MAKE_JOBS=8
# Use custom output directory (default: target/debs/trixie)
make SONIC_REDFISH_TARGET=output/debs
# Build with specific bmcweb commit (default: 6926d430)
make BMCWEB_HEAD_COMMIT=abc123
# Build with custom bmcweb repository URL
make BMCWEB_REPO_URL=https://github.com/custom/bmcweb.git
# Pin a different stdexec revision (default: fee4d651...)
make STDEXEC_REVISION=<sha>
# Keep the integration-test container alive for debugging
make test NODELETE=1CONFIGURED_ARCH (default: amd64) is used only by the
sonic-buildimage integration targets described in section 3.
The build system is designed for Debian Trixie and uses:
- Docker-based builds: All compilation happens inside a
debian:trixiecontainer for consistency - Debian packaging: Uses
dpkg-buildpackageto create.debpackages - Meson subprojects: sdbusplus is pre-built in the Docker image; other dependencies are managed via
.wrapfiles - Automatic dependencies: Build targets automatically trigger required cleanup and setup steps
- Patch management: Uses a
patches/seriesfile to define patch order
make all
1. Build Docker image (sonic-redfish-builder:latest)
- Base: debian:trixie
- Installs: build-essential, meson, debhelper, C++23 toolchain, sdbusplus
2. Setup bmcweb source
- Auto-clone from GitHub if not present
- Checkout to specified commit (default: 6926d430)
3. Copy OEM extension into the bmcweb source tree
- oem-extension/sonic/ and oem-extension/schema/ (see section 9)
4. Apply patches
- Apply patches from patches/series to bmcweb source
5. Build sonic-dbus-bridge
- Uses pre-installed sdbusplus from Docker image
- dpkg-buildpackage creates .deb packages
6. Build bmcweb
- Meson downloads dependencies via .wrap files
- dpkg-buildpackage creates .deb packages
7. Collect artifacts to target/debs/trixie/
- bmcweb_1.0.0_<arch>.deb
- bmcweb-dbg_1.0.0_<arch>.deb
- sonic-dbus-bridge_1.0.0_<arch>.deb
- sonic-dbus-bridge-dbgsym_1.0.0_<arch>.deb
- Plus .changes, .buildinfo, .dsc files
8. Run unit tests (make unit-test), then integration tests (make test)
- Any test failure fails the whole `make all` invocation
The build system automatically handles dependencies:
build-bmcweb: Automatically runsclean->setup-bmcweb->copy-oem-extension->apply-patches-> buildbuild-bridge: Automatically runsclean-> build
This ensures a clean, reproducible build every time.
Patches are located in the patches/ directory:
patches/series- Defines patch order (lines starting with#are comments)patches/*.patch- Individual patch files
Current patches:
0001-Integrating-bmcweb-with-SONiC-s-build-system.patch- Adds Debian packaging0002-add-bmc-MAC-address-based-product-to-Redfish-service-root.patch- Sets the service rootProducttoSONiCBMC-<base MAC>(MAC read from the bridge over D-Bus; falls back toSONiCBMCwhen unavailable)0003-pin-sdbusplus-to-known-good-revision.patch- Pins the sdbusplus wrap0004-Integrate-SONiC-OEM-extension.patch- Wires in the OEM extension (section 9)
To add a new patch:
- Make changes in bmcweb source directory.
- Generate patch:
cd bmcweb && git format-patch -1 HEAD. - Move patch to
patches/directory. - Add patch filename to
patches/series.
- Removes:
obj-*,debian/build state,.deb/.changes/.buildinfo/.dscstrays at the repo root, subproject checkouts, and thetarget/directory - Resets: bmcweb source to clean git state via
git reset --hard+git clean -ffdx(so patches can be reapplied) - Keeps: Docker images, the
bmcweb/directory itself - Needs
sudoto reclaim ownership of root-owned files left by Docker builds - Use when: You want to rebuild from scratch
- Does everything
cleandoes forsonic-dbus-bridgeandtarget/, plus: - Deletes: the entire
bmcweb/source directory (re-cloned on the next build) - Removes: the builder image (
sonic-redfish-builder:latest) and the test image (sonic-redfish-test:latest) - Use when: You want to start completely fresh
sdbusplus (OpenBMC D-Bus C++ bindings) is pre-built and installed in the Docker
image (build/Dockerfile.build). Both bmcweb and sonic-dbus-bridge find it via
pkg-config at build time. The pinned sdbusplus and stdexec commits are configured
as ARG directives in the Dockerfile.
Other dependencies are managed via Meson wrap files (.wrap):
bmcweb/subprojects/sdbusplus.wrap- D-Bus C++ bindings (fallback; prefers system package)- Plus other dependencies defined in bmcweb upstream (boost, nghttp2, nlohmann_json, openssl, cli11, tinyxml2, zstd, gtest)
sonic-dbus-bridge/subprojects/sdbusplus.wrap- D-Bus C++ bindings (fallback; prefers system package)
Meson automatically downloads and builds subproject dependencies during the build process.
The Debian packages can be installed in SONiC images.
- Source: https://github.com/openbmc/bmcweb
- Base commit: 6926d430 (configurable via
BMCWEB_HEAD_COMMIT) - License: Apache-2.0
- Purpose: Redfish API server providing standard Redfish REST API
- Build system: Meson + Debian packaging
- Output:
bmcweb_1.0.0_<arch>.deb,bmcweb-dbg_1.0.0_<arch>.deb - Auto-clone: Automatically cloned from GitHub if not present
- License: Apache-2.0
- Purpose: Bridge SONiC Redis database to D-Bus for bmcweb integration
- Features:
- Redis to D-Bus data synchronization
- Platform inventory management (including the base MAC address from CONFIG_DB)
- FRU EEPROM data export
- User management integration
- State management (host, chassis)
- Rack-manager commands, alerts and telemetry persisted to STATE_DB
- Build system: Meson + Debian packaging
- Output:
sonic-dbus-bridge_1.0.0_<arch>.deb,sonic-dbus-bridge-dbgsym_1.0.0_<arch>.deb - Configuration:
config/config.yamlfor Redis, D-Bus, and platform settings
The bridge is configured via sonic-dbus-bridge/config/config.yaml:
- Redis settings: Connection parameters for CONFIG_DB and STATE_DB
- Platform data: Path to platform.json and FRU EEPROM locations
- D-Bus settings: Service name and bus configuration
- Update behavior: Polling intervals and pub/sub settings
- Logging: Log levels and output configuration
D-Bus security policies are defined in sonic-dbus-bridge/dbus/:
xyz.openbmc_project.Inventory.Manager.conf- Inventory managementxyz.openbmc_project.ObjectMapper.conf- Object mapper servicexyz.openbmc_project.State.Host.conf- Host state managementxyz.openbmc_project.User.Manager.conf- User managementxyz.openbmc_project.bmcweb.conf- bmcweb servicecom.sonic.RackManager.conf- SONiC rack-manager OEM service (section 9)
These files are installed to /etc/dbus-1/system.d/ during package installation.
A SONiC-specific OEM extension is exposed under
Manager.Oem.SONiC.RackManager and provides two POST actions
(SubmitAlert, SubmitTelemetry) that a rack-manager device uses to
push structured alerts and periodic telemetry into the BMC. bmcweb
validates and forwards the JSON body verbatim over D-Bus to
sonic-dbus-bridge, which persists it as HSET rows in Redis STATE_DB.
The full contract - body envelopes, JSON schemas, per-action request / response / Redis state, and error responses - lives in:
- oem-extension/README.md - OEM contract, schema bindings, and worked POST examples.
Source layout:
oem-extension/sonic/- bmcweb-side route handlers (sonic_submit_alert.hpp,sonic_submit_telemetry.hpp,sonic_rack_manager.hpp,sonic_oem_redfish.hpp).oem-extension/schema/json-schema/- authoritativeSonicManager.v1_0_0.jsonschema (and its unversioned alias).
Two independent test suites live under tests/:
| Suite | Type | Runner |
|---|---|---|
tests/redfish-api/ |
pytest integration | make test |
tests/unit-tests/ |
C++ gtest unit tests | make unit-test |
The integration suite spins up the whole Redfish stack
(dbus-daemon -> redis -> sonic-dbus-bridge -> bmcweb) inside a Docker
container and hits the live HTTPS API on https://localhost:443. The
unit suite covers pure-logic C++ classes in sonic-dbus-bridge/ with
no Redis, no D-Bus, and no network.
Quick start:
make test # full integration suite (builds the test image first)
make unit-test # C++ unit tests in the builder imageSee tests/README.md for the JSON case schema,
fixtures, debugging recipes (NODELETE=1), and the guide for adding a
new test case.
Below are the currently supported Redfish API endpoints and their sample responses.
GET /redfish/v1/UpdateService/FirmwareInventory{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory",
"@odata.type": "#SoftwareInventoryCollection.SoftwareInventoryCollection",
"Members": [
{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/bios"
},
{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/bmc"
},
{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/switch"
}
],
"Members@odata.count": 3,
"Name": "Software Inventory Collection"
}GET /redfish/v1/UpdateService/FirmwareInventory/bios{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/bios",
"@odata.type": "#SoftwareInventory.v1_1_0.SoftwareInventory",
"Description": "Other image",
"Id": "bios",
"Name": "Software Inventory",
"Status": {
"Health": "OK",
"HealthRollup": "OK",
"State": "Enabled"
},
"Updateable": false,
"Version": "N/A"
}GET /redfish/v1/UpdateService/FirmwareInventory/bmc{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/bmc",
"@odata.type": "#SoftwareInventory.v1_1_0.SoftwareInventory",
"Description": "BMC image",
"Id": "bmc",
"Name": "Software Inventory",
"RelatedItem": [
{
"@odata.id": "/redfish/v1/Managers/bmc"
}
],
"RelatedItem@odata.count": 1,
"Status": {
"Health": "OK",
"HealthRollup": "OK",
"State": "Enabled"
},
"Updateable": false,
"Version": "sonic-redfish-build.0-ddbc425a4"
}GET /redfish/v1/UpdateService/FirmwareInventory/switch{
"@odata.id": "/redfish/v1/UpdateService/FirmwareInventory/switch",
"@odata.type": "#SoftwareInventory.v1_1_0.SoftwareInventory",
"Description": "Host image",
"Id": "switch",
"Name": "Software Inventory",
"RelatedItem": [
{
"@odata.id": "/redfish/v1/Systems/system/Bios"
}
],
"RelatedItem@odata.count": 1,
"Status": {
"Health": "OK",
"HealthRollup": "OK",
"State": "Enabled"
},
"Updateable": false,
"Version": "N/A"
}GET /redfish/v1/{
"@odata.id": "/redfish/v1",
"@odata.type": "#ServiceRoot.v1_15_0.ServiceRoot",
"AccountService": {
"@odata.id": "/redfish/v1/AccountService"
},
"Cables": {
"@odata.id": "/redfish/v1/Cables"
},
"CertificateService": {
"@odata.id": "/redfish/v1/CertificateService"
},
"Chassis": {
"@odata.id": "/redfish/v1/Chassis"
},
"EventService": {
"@odata.id": "/redfish/v1/EventService"
},
"Id": "RootService",
"JsonSchemas": {
"@odata.id": "/redfish/v1/JsonSchemas"
},
"Links": {
"ManagerProvidingService": {
"@odata.id": "/redfish/v1/Managers/bmc"
},
"Sessions": {
"@odata.id": "/redfish/v1/SessionService/Sessions"
}
},
"Managers": {
"@odata.id": "/redfish/v1/Managers"
},
"Name": "Root Service",
"Product": "SONiCBMC-aa:18:f1:e4:27:60",
"ProtocolFeaturesSupported": {
"DeepOperations": {
"DeepPATCH": false,
"DeepPOST": false
},
"ExcerptQuery": false,
"ExpandQuery": {
"ExpandAll": false,
"Levels": false,
"Links": false,
"NoLinks": false
},
"FilterQuery": false,
"OnlyMemberQuery": true,
"SelectQuery": true
},
"RedfishVersion": "1.17.0",
"Registries": {
"@odata.id": "/redfish/v1/Registries"
},
"SessionService": {
"@odata.id": "/redfish/v1/SessionService"
},
"Systems": {
"@odata.id": "/redfish/v1/Systems"
},
"Tasks": {
"@odata.id": "/redfish/v1/TaskService"
},
"TelemetryService": {
"@odata.id": "/redfish/v1/TelemetryService"
},
"UUID": "00000000-0000-0000-0000-000000000000",
"UpdateService": {
"@odata.id": "/redfish/v1/UpdateService"
}
}POST /redfish/v1/Systems/system/Actions/ComputerSystem.Reset
Content-Type: application/json
{"ResetType": "On"}This action publishes a RACK_MANAGER_COMMAND row to STATE_DB which
sonic-bmcctld (sonic-platform-daemons) consumes:
root@sonic:/home/admin# redis-cli -n 6 KEYS 'RACK_MANAGER_COMMAND|*'
1) "RACK_MANAGER_COMMAND|CMD_1775040896_000001"
root@sonic:/home/admin# redis-cli -n 6 HGETALL 'RACK_MANAGER_COMMAND|CMD_1775040896_000001'
1) "command"
2) "POWER_ON"
3) "status"
4) "PENDING"
5) "result"
6) ""
7) "last_change_timestamp"
8) "2026-05-08T12:34:56.157648Z"
POST /redfish/v1/Systems/system/Actions/ComputerSystem.Reset
Content-Type: application/json
{"ResetType": "GracefulShutdown"}Redis STATE_DB after the request:
root@sonic:/home/admin# redis-cli -n 6 HGETALL 'RACK_MANAGER_COMMAND|CMD_1775041067_000002'
1) "command"
2) "POWER_OFF"
3) "status"
4) "PENDING"
5) "result"
6) ""
7) "last_change_timestamp"
8) "2026-05-08T12:37:47.766120Z"
POST /redfish/v1/Systems/system/Actions/ComputerSystem.Reset
Content-Type: application/json
{"ResetType": "PowerCycle"}Redis STATE_DB after the request:
root@sonic:/home/admin# redis-cli -n 6 HGETALL 'RACK_MANAGER_COMMAND|CMD_1775041121_000003'
1) "command"
2) "POWER_CYCLE"
3) "status"
4) "PENDING"
5) "result"
6) ""
7) "last_change_timestamp"
8) "2026-05-08T12:38:41.924146Z"
sonic-bmcctld then transitions status to IN_PROGRESS and finally
DONE or FAILED, writing a human-readable string into result on
failure (e.g. CRITICAL_LEAK_PRESENT). Authoritative host power state
is published by the daemon to HOST_STATE|switch-host
(device_power_state, device_status, last_change_timestamp).
Apache-2.0