How openbmc/docs works
1. What this repository is
- This is the OpenBMC documentation repository, not the firmware implementation itself.
- Its job is to define the architecture, design decisions, usage patterns, and development process for the OpenBMC ecosystem.
- The actual runtime components live in separate component repositories and Yocto layers; this repo explains how they fit together.
2. Top-level structure as an architecture map
- architecture/ contains the most stable system-level architecture docs.
- designs/ contains feature and subsystem design proposals, often more detailed and narrower than the architecture docs.
- development/, testing/, release/, and process/ describe the engineering workflow around the platform.
- security/, style/, and tof/ are governance and policy boundaries rather than product features.
- userguide/ and cheatsheets provide operator-facing usage guidance.
3. Core system architecture themes
- The docs center on OpenBMC as a BMC firmware stack for out-of-band server management.
- Major architecture areas documented here include:
- management interfaces such as Redfish, REST, and IPMI,
- sensors and inventory,
- code/firmware update,
- event and error logging,
- user and authorization management,
- power, LED, and host control,
- and platform integration through D-Bus, systemd, and object mapping.
4. The interface boundary to the outside world
- OpenBMC’s main external consumers are operators, automation tools, and the managed host platform.
- The repository documents multiple access protocols:
- Redfish as the modern API surface,
- REST as a general HTTP API,
- IPMI as the legacy management interface,
- plus protocol-specific areas like PLDM, MCTP, and USB/network-based update paths.
- These docs establish where each protocol fits, and which features are exposed through which interface.
5. Data and control flow around hardware management
- A key architectural pattern is that hardware state is discovered and normalized inside BMC services, then surfaced through management interfaces.
- The docs for sensors, object mapper, entity/inventory management, and physical topology imply a flow from hardware signals and platform description into a centralized representation, then outward to Redfish/IPMI.
- This is the backbone for inventory, health, telemetry, and platform status reporting.
6. Firmware and code update subsystem
- architecture/code-update/ and several designs/code-update* docs describe one of the most important workflows in the system: updating the BMC itself and, in some cases, host firmware.
- The architecture boundary here includes:
- image layout and flash storage,
- update transport mechanisms,
- staging/activation behavior,
- and host-vs-BMC update separation.
- Related designs cover update paths over Redfish, blobs, USB, and platform-specific storage layouts.
7. Logging, events, and diagnostics
- Several docs cover event logging, SEL/error handling, dump management, and telemetry.
- This indicates a pipeline where platform faults and operational events are captured locally, normalized, and then exposed to external consumers.
- There is also explicit attention to Redfish eventing/logging, showing that observability is part of the management-plane architecture, not an afterthought.
8. Security, identity, and authorization
- security/ and design docs on user management, TLS, authorization, certificate handling, and attestation define the trust boundary for the management plane.
- The architecture distinguishes between:
- local BMC authentication and user lifecycle,
- transport security for API access,
- and broader platform trust features such as certificates, revocation, and attestation.
- This is important for diagramming because security is layered across the API surfaces rather than isolated in one component.
9. Platform integration and service composition
- OpenBMC is documented as a service-oriented Linux userspace built on top of system services and D-Bus-style integration.
- The architecture/openbmc-systemd.md, architecture/object-mapper.md, and related docs suggest that system services are coordinated through standard Linux mechanisms rather than a monolithic application.
- The repo also references Yocto and Linux kernel development, which frames the platform as a firmware distribution assembled from multiple layers.
10. Host/BMC interaction model
- Many design docs focus on interactions between the BMC and the managed host: power recovery, boot progress, postcodes, virtual media, console access, NMI, and reset behavior.
- This shows a two-plane architecture:
- the BMC management plane running independently,
- and the host control/monitoring plane that the BMC influences or observes.
- These flows are central to understanding OpenBMC’s purpose in a system diagram.
11. Hardware-specific and vendor-specific extensions
- The designs/oem/ area and multiple platform-oriented docs show that OpenBMC is intentionally extensible per board or vendor.
- This repository therefore documents the common architecture plus places where OEM-specific behavior plugs in without redefining the core stack.
- That makes the repo useful as the shared contract between upstream architecture and downstream platform adaptations.
12. Engineering workflow and project governance
- development/, testing/, process/, release/, and maintainer/membership docs describe how the project is built, reviewed, tested, and released.
- The collaboration model includes mailing lists, Gerrit-based development, and documented contribution rules.
- These are not runtime subsystems, but they define the organizational boundary around how the architecture evolves.
13. How to read this repo for an architecture diagram
- Treat the repo as a documentation hub for a layered firmware platform:
- hardware and platform description at the bottom,
- Linux/system services and D-Bus coordination in the middle,
- management protocols and security at the boundary,
- and operator/automation consumers at the top.
- The most important diagram anchors are: inventory/sensors, logging/events, code update, host control, and external management APIs.
Main entry points: interface-overview.md Architecture · README.md Docs home · development/README.md Development · physical-topology.md Topology
Components 29
Repository
Top-level entry and overview for the documentation repo.
- Docs home · Repository overview and navigation starting point.
README.md
Architecture
Stable system-level architecture and platform boundaries.
- Architecture · High-level OpenBMC architecture and interface boundaries.
architecture/interface-overview.md - Systemd · How OpenBMC services are composed and coordinated on Linux.
architecture/openbmc-systemd.md - Object mapper · Central D-Bus object discovery and lookup boundary.
architecture/object-mapper.md - Sensors · Hardware state, sensor normalization, and reporting architecture.
architecture/sensor-architecture.md - Code update · BMC and host firmware update architecture and activation flow.
architecture/code-update/code-update.md - User mgmt · BMC user accounts, roles, and authorization boundaries.
architecture/user-management.md - IPMI · Legacy management interface architecture and scope.
architecture/ipmi-architecture.md - Redfish logging · Logging and event exposure through the Redfish boundary.
architecture/redfish-logging-in-bmcweb.md - LEDs · System LED policy and control architecture.
architecture/LED-architecture.md
Designs
Feature, subsystem, and OEM design proposals.
- Topology · Physical topology and platform description used by downstream services.
designs/physical-topology.md - Inventory · Entity manager and hardware inventory discovery patterns.
designs/entity-manager.md - Events · Event logging, SEL handling, and diagnostic flow.
designs/event-logging.md - Dumps · Crash and diagnostic dump collection and exposure.
designs/dump-manager.md - Boot flow · Boot progress, readiness, and host-visible startup state.
designs/boot-progress.md - Power · Power recovery and reset behavior between BMC and host.
designs/power-recovery.md - Virtual media · Remote media and host access through the BMC.
designs/virtual-media.md - PLDM · PLDM stack and related protocol integration.
designs/pldm-stack.md - EventService · Redfish event delivery and subscription model.
designs/redfish-eventservice.md - TLS auth · Transport security and authenticated access for management APIs.
designs/redfish-tls-user-authentication.md
Workflow
Development, testing, release, and contribution process.
- Development · Contributor setup, coding, and development workflow.
development/README.md - Testing · Local and CI test practices for the platform.
testing/local-ci-build.md - Release metrics · Release tracking and operational metrics over time.
release/metrics/2022-12 - Maintainership · Subproject ownership and governance process.
process/subproject-maintainership.md
Governance
Policy, style, and membership documents.
- Style · Language and formatting conventions for the project.
cpp-style-and-conventions.md - Membership · Project membership, voting, and community rules.
tof/membership-and-voting.md
Security
Security-specific guidance and response process.
- Security · Security response and vulnerability reporting policy.
SECURITY.md - TLS config · TLS configuration guidance for secure transport.
security/TLS-configuration.md - Network sec · Network-facing security considerations for the management plane.
security/network-security-considerations.md
Connections 29
- Docs home → Architecture: documents · Repository home points into the architecture map.
- Docs home → Topology: covers · The repo also contains detailed subsystem design docs.
- Docs home → Development: explains · Contributor workflow and development practices.
- Docs home → Security: sets · Security reporting and response boundary.
- Architecture → Systemd: runs on · OpenBMC is framed as coordinated Linux services.
- Architecture → Object mapper: coordinates · D-Bus object discovery is a central integration point.
- Architecture → Sensors: surfaces · Hardware state and telemetry are normalized for consumers.
- Architecture → Code update: updates · Firmware update is a core management workflow.
- Architecture → User mgmt: secures · User and authorization management bounds API access.
- Architecture → IPMI: exposes · Legacy management access is documented as a boundary.
- Architecture → Redfish logging: exposes · Redfish is the modern management interface surface.
- Architecture → LEDs: controls · LED behavior is part of platform management.
- Topology → Inventory: feeds · Topology and platform description support inventory discovery.
- Topology → Power: informs · Platform topology shapes host power and recovery flows.
- Inventory → Object mapper: publishes · Inventory is represented through the object mapping layer.
- Events → Redfish logging: surfaces · Events and logs are exposed through management APIs.
- Dumps → Events: extends · Diagnostics complement the event and logging pipeline.
- Boot flow → Power: depends on · Boot and readiness state are tied to host power control.
- Virtual media → Architecture: fronts · Remote media is one of the external management capabilities.
- PLDM → Architecture: integrates · PLDM is part of the protocol landscape around OpenBMC.
- EventService → Redfish logging: extends · Redfish eventing is part of the API-facing observability path.
- TLS auth → Security: implements · Transport authentication is a concrete security control.
- Development → Testing: pairs with · Development flows into local and CI validation.
- Development → Maintainership: governed by · Contribution and review are shaped by maintainership.
- Release metrics → Testing: requires · Release tracking depends on validated builds and test results.
- Style → Development: guides · Style rules shape implementation work.
- Membership → Maintainership: supports · Membership rules underpin subproject governance.
- TLS config → Network sec: complements · Transport security and network guidance are paired controls.
- Security → TLS auth: covers · Policy documents the security requirements for management access.