fboss2-dev Config Sessions

fboss2-dev is fboss2 plus commands that edit the switch's persistent configuration. Edits are staged in a per-user session, reviewed as a diff, and applied in one commit that is recorded in a local Git repository under /etc/coop, so every change has history and can be rolled back. This page explains the session model, every config and delete area, how commits are applied, and how config differs from the runtime set commands.

The Session Model

Staging has no side effects. A config command edits a copy of the configuration in your session directory, ~/.fboss2/. The switch is untouched until you commit.
One commit applies everything. config session commit applies all staged changes. It is not transactional: services are updated one at a time, and if applying fails the CLI attempts a best-effort rollback.
Several services per session. A session can hold changes to the agent config (agent.conf) and the BGP daemon config (bgpcpp.conf).
Rebase replays your uncommitted changes on top of the current startup config, like git rebase, when someone else committed in the meantime.
Rollback restores any earlier revision, because every commit is a Git commit.

Session Files

File	Contents
`~/.fboss2/agent.conf`	Your staged agent config
`~/.fboss2/bgp_config.json`	Your staged BGP config
`~/.fboss2/cli_metadata.json`	Session metadata, including the action level each service needs

Because the session lives in $HOME, two operators on the same switch have independent sessions; use rebase when the startup config moved under you.

A Complete Workflow

# Stage changes
fboss2-dev config interface eth1/1/1 description "Peer link to device XYZ"
fboss2-dev config interface eth1/1/1 eth1/2/1 mtu 1500

# Review
fboss2-dev config session diff

# Apply
fboss2-dev config session commit

# Or: replay onto a newer startup config, or throw everything away
fboss2-dev config session rebase
fboss2-dev config session clear

Staging echoes what was recorded:

Successfully configured interface(s) eth1/1/1: description="Peer link to device XYZ"
Successfully configured interface(s) eth1/1/1, eth1/2/1: mtu=1500

config session diff prints a unified diff between the live config and your session (it can also compare the session with a revision, or two revisions):

--- current live config
+++ session config
@@ -174,7 +174,7 @@
-        "mtu": 9000,
+        "mtu": 1500,

config session commit reports the new revision and what it did per service:

Config session committed successfully as 21c94ca and config reloaded for fboss_sw_agent.

Config Storage

/etc/coop/
├── .git/                # Local Git repository, no remote
├── agent.conf           # Agent startup config (usually a symlink to cli/agent.conf)
├── cli/
│   ├── agent.conf       # Last agent config committed by the CLI
│   └── cli_metadata.json
├── bgpcpp.conf          # BGP daemon startup config (symlink)
└── bgpcpp/
    └── bgpcpp.conf      # Last BGP config committed by the CLI

Each commit is a Git commit with a message such as Config commit by <user>. config history shows them:

 Commit    Author  Commit Time          Message
---------------------------------------------------------------------
 21c94ca8  netops  2026-07-30 19:23:24  Config commit by netops
 d0ab8413  netops  2026-07-30 19:23:15  Config commit by netops
 e3446ba1  netops  2026-07-30 19:22:34  Initial commit

You can also use plain git log in /etc/coop.

Rolling Back

fboss2-dev config rollback 21c94ca8   # to a specific revision
fboss2-dev config rollback            # to the previous revision

Output is similar to Successfully rolled back. New commit: 790bf861. Config reloaded. A rollback never rewrites history: it creates a new commit whose content matches the target (message Rollback to <rev> by <user>), which can itself be rolled back.

How a Commit Is Applied

As you stage changes, the CLI records per service the least disruptive action that will apply them. At commit time it performs exactly that: some agent changes are applied hitlessly by delta processing in about 1 to 2 seconds, others require an agent restart; a BGP change may restart the BGP daemon while leaving the agent alone; a session that touches only the agent leaves BGP alone.

fboss2-dev config applied-info shows information about the applied config, and fboss2-dev config reload makes the agent re-read its startup config.

Config Areas

Command	What it configures
`config acl rule`, `config acl table`, `config acl table-group`	ACL rules, tables within a table group, and table groups with their stage
`config applied-info`	Show config applied information
`config arp`	ARP/NDP timer settings
`config copp queue`, `config copp traffic-policy`, `config copp reason`	CPU queue shaping, CPU-plane actions on named ACL rules, packet-rx reason to CPU queue mapping
`config data-plane traffic-policy`	Data-plane actions on named ACL rules
`config dhcp relay-source-override`, `config dhcp reply-source-override`	DHCP relay source overrides
`config history`	Committed revisions
`config interface <ports> <attr> <value> ...`	Port and interface attributes (see below), plus `pfc-config`, `ipv6 ndp`, `sflow`, and `switchport access vlan` sub-areas
`config l2 learning-mode`	L2 learning mode
`config mac aging-time`	MAC aging time in seconds
`config load-balancing ecmp`, `config load-balancing lag`	Hash fields, algorithm, and seed for ECMP and LAG
`config protocol bgp global`, `neighbor`, `peer-group`, `policy ...`	BGP (see below)
`config protocol static ip route`, `config protocol static ipv6 route`	Static routes
`config ptp transparent-clock`	Enable or disable PTP transparent clock mode
`config qos buffer-pool`, `default-policy`, `policy ... map`, `priority-group-policy`, `queue-config ... queue-id`	QoS: buffer pools, the default data-plane QoS policy, QoS maps (tc-to-queue, pfc-pri-to-queue, tc-to-pg, pfc-pri-to-pg), PG policies, queue configs
`config reload`	Reload the agent configuration
`config rollback [rev]`	Roll back
`config session clear`, `commit`, `diff`, `rebase`	Manage the session
`config srv6 my-sid ... entry`	SRv6 MySID entries under a locator prefix
`config switch admin-distance`, `hostname`, `icmpv4-unavailable-src-addr`	Switch-level settings
`config traffic-counter`	Create or update a named traffic counter (`PACKETS`, `BYTES`)
`config tunnel ip-in-ip encap`, `decap`	IP-in-IP tunnels
`config vlan <id> port ...`, `config vlan <id> static-mac add\|delete`	VLAN port tagging mode (tagged, untagged, priority-tagged), static MAC entries
`config vlan default`	Global default VLAN for untagged traffic

Interface Attributes

config interface takes one or more port names followed by attribute/value pairs. The accepted attributes are description, name, mtu, ip-address, ipv6-address, profile, loopback-mode, flow-control-rx, flow-control-tx, lldp-expected-*, type, shutdown, no-shutdown, lookup-class, and queue-config. shutdown and no-shutdown take no value. A profile must be a PortProfileID name from switch_config.thrift, for example PROFILE_400G_8_PAM4_RS544X2N_OPTICAL; anything else is rejected with Invalid profile value '<x>': not a valid PortProfileID.

fboss2-dev config interface eth1/1/1 shutdown
fboss2-dev config interface eth1/1/1 eth1/1/5 mtu 9000 description "uplink"

delete Commands

Most areas have a delete counterpart that removes the object or resets it to its default: delete arp, delete interface ... ipv6 ndp, delete interface ... sflow, delete qos default-policy|queue-config|policy ... map, delete protocol bgp neighbor|peer-group|policy ..., delete protocol static ip|ipv6 route, delete acl rule|table, delete copp queue|traffic-policy ... match|action|reason, delete data-plane traffic-policy ... match|action, delete dhcp relay-source-override|reply-source-override, delete load-balancing ecmp|lag, delete srv6 my-sid ... entry, delete tunnel ip-in-ip encap|decap, delete traffic-counter, delete vlan, and delete switch admin-distance|icmpv4-unavailable-src-addr.

Behavior to expect:

delete is meant to be idempotent: deleting something that does not exist is not an error.
Not every leaf can be deleted individually. Sometimes you must delete the parent object and configure it again.
Some deletes refuse while the object is in use: delete traffic-counter refuses while a traffic-policy match action references the counter, and delete vlan refuses while the VLAN is the default VLAN or a port's ingress VLAN.

BGP Configuration

BGP support is under active development, and some pieces are still being upstreamed. BGP changes go through the same session but are committed to /etc/coop/bgpcpp/bgpcpp.conf.

config protocol bgp global [<attr> <value> ...]: router-id, local-asn, hold-time, confed-asn, cluster-id, network6, switch-limit settings.
config protocol bgp neighbor <ip> [<attr> <value> ...]: remote-asn, local-asn, peer-group, description, bind-addr address, next-hop settings, passive, address-family toggles, rr-client, confed-peer, type, ingress and egress policies, add-path, link-bandwidth, graceful-restart and timer settings, and max-route limits. A bare neighbor <ip> creates the neighbor.
config protocol bgp peer-group <name> ...: the same attributes on a peer group.
config protocol bgp policy as-path-list|community-list|prefix-list|routing-policy <name> ...: policy objects. For an as-path-list, regex <regex> appends one pattern (join AS numbers with _, for example ^65000_65001$).

fboss2-dev config protocol bgp global local-asn 65000
fboss2-dev config protocol bgp neighbor 2001:db8::99 remote-asn 65510
fboss2-dev config session diff
fboss2-dev config session commit

Config vs set

	`fboss2 set ...`	`fboss2-dev config ...`
What changes	Running `SwitchState` only, via Thrift	`agent.conf` (or `bgpcpp.conf`) through a session
Persisted	No	Yes, as a Git commit
Audit trail	None: not in `session diff`, not in `config history`	Full history and rollback
When it takes effect	Immediately	At `session commit`

When both touch the same setting, config wins. For example, fboss2 set port <ports> state disable and fboss2-dev config interface <ports> shutdown both drive port admin state, but any later commit or reload, even for an unrelated change, re-applies the config and reverts the set. A warm or cold restart does the same. Conversely, a staged config edit is invisible to fboss2 show ... until committed; session diff is the only way to see pending changes.

Trying It Without a Switch

All of this works in the fboss-sim container, whose setup initializes /etc/coop as a Git repo with an initial commit. See Quick Start.