# Configuration Reference

Both the controller and the agent read the same YAML file, and each ignores the
sections that do not apply to it. The default path is
`/etc/fabric-manager/config.yaml`, overridable with `--config`.

For Kubernetes deployments the chart renders this file into a ConfigMap, so
prefer the [chart values](configuration.md); this page describes the underlying
file, which is what you edit for bare-metal and Docker runs.

Only `controller.listen_address` is required. Every other key has a default, and
the whole `otel`, `telemetry`, and `discovery` sections can be omitted.

## `controller`

| Key | Default | Description |
|-----|---------|-------------|
| `listen_address` | **required** | `host:port` the controller's gRPC server binds to. Agents dial this |
| `heartbeat_interval_sec` | `10` | How often each agent sends a heartbeat. Must be positive |
| `heartbeat_timeout_sec` | `30` | Mark a host offline after this long without a heartbeat. Must be positive and **strictly greater than** `heartbeat_interval_sec` |
| `daemon_reconnect_timeout_sec` | `60` | Grace period for an agent to reconnect before its topology is dropped |
| `factory_system_descriptor_search_path` | unset | Path searched for Factory System Descriptor textprotos. Required for anything FSD-related: `QueryFactorySystemDescriptor`, `topo_source: FSD`, `validate_topo`, and placement validation |
| `physical_grouping_descriptor_path` | unset | Path to a Physical Grouping Descriptor, which tells the mapper about hardware-specific tray layouts (e.g. BH galaxy rev C) |
| `supported_topology_shapes` | empty | Native topology shapes discoverable from FSD host instance paths; see below |
| `http_listen_address` | unset | `host:port` for the [web UI and JSON API](web-ui.md). Empty disables the HTTP server |
| `web_ui_path` | unset | Directory of static UI assets served at `/`. Empty serves the JSON API only |
| `keepalive` | see below | gRPC keepalive for the controller ↔ agent connection |

### `controller.keepalive`

Applied to both the controller's gRPC server and each agent's client channel;
agents read this section from their own copy of the config.

| Key | Default | Description |
|-----|---------|-------------|
| `time_sec` | `20` | Interval between keepalive HTTP/2 pings. Must be positive |
| `timeout_sec` | `10` | How long to wait for a ping ack before treating the connection as dead. Must be positive |
| `permit_without_calls` | `true` | Ping even with no active RPCs on the connection |
| `max_connection_idle_sec` | `0` | Server-only: close a connection idle this long. `0` disables. Must not be negative |

This matters because agents send *unary* heartbeats over a single reused channel,
so the connection is idle between calls. Without keepalive, a peer that vanishes
without a TCP FIN/RST leaves a half-open connection that the transport poller
can spin on.

Leave `max_connection_idle_sec` at `0`, or comfortably above
`heartbeat_interval_sec`, so healthy but briefly idle connections are not torn
down.

## `otel`

OpenTelemetry logs, traces, and metrics. Currently exported to stdout in
OStream/OTLP-style format; pipe it to a Collector or scrape via `kubectl logs`.

| Key | Default | Description |
|-----|---------|-------------|
| `enabled` | `false` | Install the Logger, Tracer, and Meter providers |
| `service_name` | `tt-fabric-manager-controller` | Reported service name. Must be non-empty when enabled |
| `deployment_environment` | unset | Reported deployment environment, e.g. `production` |
| `metric_export_interval_sec` | `10` | Metric export interval. Must be positive when enabled |

Standard environment variables take precedence over these values:
`OTEL_SERVICE_NAME` overrides `service_name`, and `OTEL_SDK_DISABLED=true`
(or `TRUE`/`1`) forces OTEL off regardless of the YAML.

## `telemetry`

Agent-side integration with the per-host [tt-telemetry](https://docs.tenstorrent.com/tt-telemetry/)
collector. When enabled, the agent opens a streaming subscription to the
collector and rediscovers its topology when link state changes, so the controller
tracks fabric health without waiting for re-registration.

| Key | Default | Description |
|-----|---------|-------------|
| `enabled` | `false` | Connect to a local collector |
| `address` | `127.0.0.1:50051` | TCP endpoint of the collector's gRPC listener. The preferred transport |
| `socket_path` | unset | Collector UNIX socket, dialled as `unix://<path>`. Used only when `address` is empty |
| `metric_queries` | `tt_ethernet_link_up`, `tt_ethernet_cable_present` | Substring matches against metric paths; one subscription per entry |
| `rediscovery_min_interval_sec` | `5` | Minimum spacing between telemetry-triggered rediscoveries. Bursts of link events are coalesced into at most one rediscovery per interval |

When both `address` and `socket_path` are set, TCP wins. When `enabled` is true,
at least one of them must be set or startup fails. The collector must be started
with a matching `--grpc-port`/`--grpc-bind`.

The default queries are the boolean link-health metrics specifically so the agent
gets one update per link state transition instead of subscribing to high-rate
counters.

## `discovery`

Retry policy for the agent's initial device discovery, which can transiently find
nothing if UMD runs while devices are still coming up.

| Key | Default | Description |
|-----|---------|-------------|
| `retry_max_attempts` | `3` | Re-discoveries attempted after an empty startup scan. `0` disables retries; must not be negative |
| `retry_interval_sec` | `20` | Seconds between retries. Must be positive when retries are enabled |

Retries stop as soon as a discovery finds devices.