| <!--* |
| # Document freshness: For more information, see go/fresh-source. |
| freshness: { owner: 'tlbmc-dev' reviewed: '2026-06-04' } |
| *--> |
| |
| # Redfish API Presentation Module |
| |
| The Redfish API Presentation Module in tlBMC is responsible for exposing |
| tlBMC-owned resources (Chassis, Sensors, Cables, UpdateService, TaskService) via |
| a standard Redfish REST API. It receives HTTP requests, routes them to correct |
| handlers, handles query parsing (like `$expand`), and enforces |
| authentication/authorization and rate limiting. |
| |
| The core implementation resides in the |
| `third_party/milotic/external/cc/tlbmc/redfish/` directory. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Overview and Integration (gBMCWeb Proxying) |
| |
| tlBMC does not run as a standalone, public-facing web server for the entire |
| Redfish tree. Instead, it co-exists with a primary web daemon (like `gbmcweb`). |
| |
| - **Path Ownership**: During startup, `RedfishApp` calculates the list of |
| routes it manages by calling `GetOwnedUrls()` and `GetOwnedSubtrees()`. |
| - **Dynamic Proxying**: `gbmcweb` queries these functions to dynamically |
| determine which HTTP request paths to proxy directly to tlBMC over a local |
| IPC or socket connection. |
| - **Asynchronous Execution**: Incoming proxied requests are adapted from |
| `crow::Request` into internal `RedfishRequest` formats and processed |
| asynchronously on a dedicated thread pool. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Central Configuration |
| |
| The Redfish presentation layer is configured via `TlbmcConfig` inside |
| `tlbmc_config_bundle.textproto` (defined in |
| [`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto)). |
| |
| ### 1. Redfish Rate Limiter Module (`RedfishRateLimiterModule`) |
| |
| Exposes request rate limiting on Redfish paths using a token bucket algorithm. |
| |
| | Field | Type | Default | Description | |
| | :------------------ | :---------------------- | :------ | :----------------- | |
| | `enabled` | `bool` | `false` | Registers the rate | |
| : : : : limiter service : |
| : : : : routes. : |
| | `active` | `bool` | `false` | Actively drops | |
| : : : : requests when : |
| : : : : limits are : |
| : : : : crossed. : |
| | `leak_rate_per_sec` | `double` | `100.0` | Sustained requests | |
| : : : : processed per : |
| : : : : second. : |
| | `bucket_capacity` | `double` | `200.0` | Maximum burst of | |
| : : : : requests allowed. : |
| | `bypass_uri` | `repeated string` | - | Routes exempt from | |
| : : : : rate limiting. : |
| | `red` | `RedfishRateLimiterRed` | - | Random Early | |
| : : : : Detection (RED) : |
| : : : : drop rules. : |
| |
| #### RedfishRateLimiterRed (Random Early Discard) Options |
| |
| - `enabled` (`bool`, default: `false`): Enables random dropping. |
| - `min_threshold` (`double`, default: `50.0`): Bucket level fullness (in %) |
| where RED starts randomly dropping requests. |
| - `max_threshold` (`double`, default: `150.0`): Bucket level where all |
| requests are dropped with `max_drop_prob`. |
| - `max_drop_prob` (`double`, default: `0.1`): Max drop probability. |
| |
| ### 2. Trust Bundle Installation Module (`TrustBundleInstallModule`) |
| |
| Field | Type | Default | Description |
| :-------- | :----- | :------ | :---------- |
| `enabled` | `bool` | `false` | If `true`, tlBMC claims ownership of `/redfish/v1/CertificateService` and `/redfish/v1/CertificateService/CertificateLocations` to manage client certificates and trust bundles. It also restricts the recovery authorization policy to only allow certificate actions. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Core Routing and Trie Matching |
| |
| - **`RedfishApp` (`redfish/app.cc`)**: The main entry point that wraps the |
| request worker pool, adapters, and configuration hooks. |
| - **`Router` (`redfish/routing.cc`)**: Uses a Trie data structure to map |
| incoming request URIs and HTTP methods to their handlers. Custom routing |
| rules are registered using the `ECRXX_ROUTE` macros. |
| - **Preprocess & Postprocess**: |
| - **`RedfishPreprocess`**: Enforces authorization and maps peer client |
| certificates (mTLS) to specific roles and privileges. |
| - **`RedfishPostprocess`**: Implements standard query parameters, such as |
| resolving `$expand` queries. |
| |
| ## Protobuf Configuration Schemas |
| |
| The Redfish presentation layer reads from the tlBMC Store. The tlBMC store holds |
| a representation of all resources parsed and managed by tlBMC and the |
| presentation layer maps this to standard redfish output consistent with DMTF |
| schemas. The following are proto definitions that tlBMC uses to internally model |
| resources: |
| |
| - **`StableId`** (defined in |
| [`stable_id.proto`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/data/stable_id.proto)): |
| Defines structures to map hardware physical paths (like I2C/PCIe paths) to |
| stable Redfish IDs. |
| - **`Resource`** (defined in |
| [`resource.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/resource.proto)): |
| Defines types representing physical and logical components (Chassis, Fan, |
| PowerSupply, etc.). |
| - **`Sensor`** (defined in |
| [`sensor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sensor.proto)): |
| Schema representing sensor telemetry properties, readings, and states |
| exposed in Redfish Sensor collections. |
| - **`SoftwareMetrics`** (defined in |
| [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto)): |
| Schema defining software metrics (network ports, stall info). |
| - **`PowerFaultLogEntry`** (defined in |
| [`power_fault_log_entry.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/power_fault_log_entry.proto)): |
| Defines the log entries exposed by the power fault log service. |
| - **`FruTable`** (defined in |
| [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto)): |
| Inventory data parsed to populate Redfish chassis properties. |
| - **`TopologyConfig`** (defined in |
| [`topology_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/topology_config.proto)): |
| Defines chassis and cable relationships mapped to Redfish URLs. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Examples |
| |
| ### Rate Limiter and Trust Bundle Activation (`tlbmc_config_bundle.textproto`) |
| |
| Shows how to configure rate limiting with Random Early Detection, set up a |
| bypass URI, and activate the CertificateService. |
| |
| ```protobuf |
| general_config { |
| redfish_rate_limiter_module { |
| enabled: true |
| active: true |
| leak_rate_per_sec: 50.0 |
| bucket_capacity: 100.0 |
| bypass_uri: "/redfish/v1/SessionService/Sessions" |
| bypass_uri: "/redfish/v1/CertificateService" |
| red { |
| enabled: true |
| min_threshold: 40.0 |
| max_threshold: 120.0 |
| max_drop_prob: 0.15 |
| } |
| } |
| trust_bundle_install_module { |
| enabled: true |
| } |
| } |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Code References |
| |
| ### Config & Presentation Protos |
| |
| - [`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto) |
| - [`stable_id.proto`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/data/stable_id.proto) |
| - [`resource.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/resource.proto) |
| - [`sensor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sensor.proto) |
| - [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto) |
| - [`power_fault_log_entry.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/power_fault_log_entry.proto) |
| - [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto) |
| - [`topology_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/topology_config.proto) |
| |
| ### Core Code |
| |
| - [`app.h`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/app.h) |
| - [`app.cc`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/app.cc) |
| - [`routing.h`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/routing.h) |
| - [`routing.cc`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/routing.cc) |
| - [`routes/`](http://google3/third_party/milotic/external/cc/tlbmc/redfish/routes/) |
| (Directory containing route handlers like `sensor.cc`, `chassis.cc`, |
| `update_service.cc`) |
