Configuration and State Flow
This lesson traces intent end to end — operator → config interface → CONFIG_DB → managers → APPL_DB → SWSS orchagents → SAI → syncd → ASIC_DB → ASIC — and then shows the equally important path that does NOT start at CONFIG_DB: protocol-learned routes. Understanding both flows is what lets you localize a stall to a single hop.
Prerequisites: Lessons 1.3 and 1.4 complete. · Comfort with the SONiC databases and containers.
Learning objectives
- →Trace an operator configuration from CLI all the way to the ASIC, naming every hop.
- →Explain the role of feature managers, orchagents, SAI, and syncd in that flow.
- →Describe the protocol-learned path (BGP route → fpmsyncd → APPL_DB → …) that bypasses CONFIG_DB.
- →Use the flow to localize where a change stalled instead of guessing.
Almost every SONiC incident reduces to 'intent existed but did not reach hardware.' If you know the exact chain, you can bisect it and find the broken hop in minutes.
Assuming everything starts in CONFIG_DB will mislead you the moment you debug a BGP-learned route — those enter through a different door and never touch CONFIG_DB.
What your CCNP already gives you
- • The mental split between configured intent and programmed forwarding (RIB vs FIB).
- • The idea that control-plane protocols install routes that then must reach the data plane.
- • Change-control instincts: verify a change actually took effect, not just that the CLI accepted it.
What is new in SONiC
- • The intent-to-hardware path is explicit and inspectable at every hop.
- • There is a distinct configured path (via CONFIG_DB) and a protocol-learned path (via fpmsyncd/APPL_DB).
- • Localizing a fault means naming the exact hop where state stopped propagating.
| In the analogy | In SONiC |
|---|---|
| Customer placing an order at the front desk | Operator at the CLI |
| The order logged in the intake ledger | CONFIG_DB |
| Planners converting the order into a build plan | Feature managers |
| The build plan on the production board | APPL_DB |
| The coordinator turning the plan into machine setups | SWSS orchagents |
| The standard machine-control language | SAI |
| The operator driving the machinery | syncd |
| The machine setup sheet → the running machine | ASIC_DB → ASIC |
Where the analogy stops working
The single assembly-line image implies one entrance, but SONiC has more than one on-ramp. Protocol-learned state (a BGP route) enters partway down the line — the routing daemon writes it toward APPL_DB via fpmsyncd, never passing through CONFIG_DB or the front desk. Counters and observed state also flow the *other* direction, upward from hardware. The line is real, but it is not single-entry and not one-way.
Intent is a message that travels
The core idea of this module lands here: in SONiC, configuration is not applied in place. A config command writes desired state and returns; the actual programming happens asynchronously as that state propagates through managers, orchagents, SAI, and syncd. 'The CLI accepted it' means the message was posted — not that it arrived.
The configured path, hop by hop
- Operator/automation issues a
configcommand (or writes CONFIG_DB via gNMI/GCU). - CONFIG_DB stores the desired state and publishes a change notification.
- A feature manager subscribed to CONFIG_DB validates and translates the intent into APPL_DB entries.
- An orchagent in swss consumes APPL_DB and makes SAI calls.
- Those SAI calls materialize as objects in ASIC_DB (hardware-facing intent).
- syncd consumes ASIC_DB and drives the vendor SDK to program the ASIC.
- Forwarding changes; STATE_DB/COUNTERS_DB later reflect the observed result.
A BGP-learned route never touches CONFIG_DB. FRR's bgpd computes it, zebra installs it, and fpmsyncd (Forwarding Plane Manager sync) writes it into APPL_DB's route table — from there it follows the same orchagent → SAI → syncd → ASIC path. If you go hunting for a learned route in CONFIG_DB, you will wrongly conclude 'it's not configured.' It was never supposed to be there.
Configured path vs protocol-learned path
| Aspect | Configured (e.g., interface IP, static route) | Protocol-learned (e.g., BGP route) |
|---|---|---|
| Entry point | CONFIG_DB (via CLI/gNMI). | APPL_DB route table (via fpmsyncd). |
| Producer | Feature manager translating CONFIG_DB. | FRR bgpd/zebra → fpmsyncd. |
| Passes through CONFIG_DB? | Yes. | No. |
| Shared downstream path | orchagent → SAI → ASIC_DB → syncd → ASIC. | orchagent → SAI → ASIC_DB → syncd → ASIC. |
| Where you look if it's missing | CONFIG_DB, then the manager, then APPL_DB. | vtysh/FRR, then fpmsyncd, then APPL_DB. |
Using the flow to localize a stall
Because the path is explicit, troubleshooting becomes a bisection. Confirm the intent exists at the top (CONFIG_DB for configured items, FRR for learned ones). Then check the next hop (APPL_DB), then ASIC_DB, then observed state. The first hop where the state is absent localizes the fault: CONFIG_DB→APPL_DB gap = a manager problem; APPL_DB→ASIC_DB gap = an orchagent/SAI problem; ASIC_DB present but no forwarding = syncd/SDK/hardware or a resource limit.
Do not model the system as strictly top-down. Counters and operational status originate at the hardware/agents and populate COUNTERS_DB/STATE_DB upward. When you read show interfaces counters, you are reading observed state that traveled up — not the intent that traveled down.
Common misconceptions
Myth: Every piece of forwarding state begins in CONFIG_DB.
Reality: Protocol-learned routes enter via fpmsyncd into APPL_DB and never pass through CONFIG_DB.
Myth: A successful config command means the ASIC is programmed.
Reality: The command posts intent and returns; programming is asynchronous across managers, orchagents, SAI, and syncd. Verify at ASIC_DB/observed state.
Myth: State only flows downward from intent to hardware.
Reality: Observed state and counters flow upward from hardware/agents into STATE_DB/COUNTERS_DB.
- Bisect the path: confirm intent at the top, then APPL_DB, then ASIC_DB, then observed — the first empty hop is the fault.
- For routing issues, decide first whether the route is configured (CONFIG_DB) or learned (FRR→fpmsyncd→APPL_DB); you look in different places.
- Never accept CLI acceptance as proof of programming; walk at least to ASIC_DB plus an observed check.
Key takeaways
- ✓Configuration is a message that travels CONFIG_DB → managers → APPL_DB → orchagents → SAI → ASIC_DB → syncd → ASIC.
- ✓Protocol-learned routes bypass CONFIG_DB, entering APPL_DB via fpmsyncd.
- ✓Observed state (STATE_DB/counters) flows upward from hardware, not down from intent.
- ✓Localizing a fault means naming the first hop where state stopped propagating.
Tested against: SONiC 202305 / 202311 lineage · Upstream (community) unless noted · SONiC-VS (virtual) baseline · last reviewed 2026-07. Exact commands and behavior can vary by SONiC release, image, hardware platform, and enterprise distribution.
Knowledge check
Choose the single best next place to look.
You added an interface IP. The CLI accepted it and it is present in CONFIG_DB, but the directly-connected neighbor is unreachable. Which layer do you inspect FIRST to confirm the intent actually propagated toward hardware?
Single best answer.
A BGP-learned prefix shows correctly in vtysh (FRR) but traffic to it is black-holed. You check CONFIG_DB and the route is not there. What is the correct interpretation?
Related lessons