FBOSS

FBOSS (Facebook Open Switching System, now maintained by Meta) is the software stack Meta runs on its data center network switches. It is a set of Linux user-space daemons, libraries, and tools that run on the switch's x86 CPU: the agent programs the forwarding ASIC through the Switch Abstraction Interface (SAI), qsfp_service manages optics and external PHYs, a family of platform services handles sensors, fans, LEDs, FRUs, and firmware, FSDB distributes state and statistics, and the fboss2 CLI ties it all together for operators.

This site documents the open source repository at github.com/meta/fboss: how to build it, how its processes fit together, how to configure and run them on a switch or in a hardware-free simulator, how to use the CLI, and how to run the hardware test suites that vendors use to onboard new platforms.

Note: FBOSS is production software shaped by Meta's networks. The repository's own README says it is "primarily of interest to network software developers" rather than a turnkey network operating system. Expect to build from source, to bring your own ASIC vendor SDK for real hardware, and to read code. The README itself is old and describes only the original agent release; the code and the docs/ folder are much more current.

What FBOSS Is Made Of

Component	Binary	What it does
Agent	`wedge_agent-sai_impl` (mono), or `fboss_sw_agent` + `fboss_hw_agent-sai_impl` (split)	Owns the switch ASIC: ports, VLANs, routes, neighbors, ACLs, QoS, LLDP, ARP/NDP. See Architecture.
QSFP service	`qsfp_service`	Detects, configures, and monitors transceivers and external PHYs. See qsfp_service.
FSDB	`fsdb`	Publish/subscribe store for switch state and stats. See FSDB.
Platform services	`platform_manager`, `sensor_service`, `fan_service`, `data_corral_service`, `led_service`, ...	Device discovery, BSP kernel modules, sensors, thermal control, FRU presence, LEDs. See Platform Services.
CLIs	`fboss2`, `fboss2-dev`, `wedge_qsfp_util`, `weutil`, `fw_util`, ...	Inspect and change the switch. See fboss2 CLI and Diagnostic Tools.
Test binaries	`sai_test-`, `sai_agent_hw_test-`, `multi_switch_agent_hw_test`, `qsfp_hw_test`, link tests, benchmarks	Hardware qualification, driven by `run_test.py`. See Running Tests.

Key Features

Vendor-neutral ASIC programming through SAI. The agent's hardware layer is built on the OCP Switch Abstraction Interface. The build knows about Broadcom XGS and DNX, Cisco (Tajo), and Nvidia (Chenab) SAI SDKs, and falls back to a fake SAI implementation when no SDK is given. See Building FBOSS.
Split control and data plane. The agent can run as one process (mono) or as a software agent plus one hardware agent per ASIC talking over Thrift (multi_switch), the mode used in production. See Architecture.
Copy-on-write switch state. All configuration and operational state lives in an immutable SwitchState tree; hardware is programmed from state deltas, which also makes warm boot possible.
Config-driven platforms. Platform specifics live in JSON and CSV files under fboss/configs/platforms/<vendor>/<platform>/, not in code. See Platform Support.
Session-based CLI configuration with Git-backed history and rollback in fboss2-dev. See fboss2-dev Config Sessions.
A complete hardware test harness: agent, SAI, QSFP, link, platform, scale, invariant, and benchmark tests, with per-ASIC known-bad lists and T0/T1/T2 tiers. See Test Suites.
A hardware-free simulator (fboss-sim) that runs the real agent and CLI on fake SAI inside Docker. See Quick Start.

A Short Example

After building with fake SAI and starting the simulator container (both covered in the Quick Start), the CLI talks to a real agent:

sudo docker exec fboss_sim_runtime_root /opt/fboss/bin/fboss2 show interface
sudo docker exec fboss_sim_runtime_root /opt/fboss/bin/fboss2 show hw-agent

On a real switch with a vendor SDK build, the same fboss2 commands report live ASIC state, and run_test.py drives the hardware test suites:

cd /opt/fboss
./bin/run_test.py sai_agent --config ./share/hw_test_configs/$CONFIG --agent-run-mode multi_switch

How It Works in One Paragraph

At boot, platform_manager identifies the platform with dmidecode, loads the BSP kernel modules, and creates stable device paths. sensor_service, fan_service, and data_corral_service then start monitoring the chassis. The agent reads /etc/coop/agent.conf, builds a SwitchState from it, and pushes state deltas down to the hardware agent(s), which call SAI. qsfp_service brings up the optics on the same ports. Both publish into FSDB, and fboss2 queries everything over Thrift on well-known ports (agent 5909, FSDB 5908, qsfp_service 5910). The full picture is in Architecture.

When to Use FBOSS

Use it when you:

develop switch software and want a production-grade, SAI-based reference stack,
onboard a new switch platform, ASIC, or optic and need Meta's qualification tests (this is a large share of the repository's documentation),
want to study how a large operator structures switch control-plane software (copy-on-write state, warm boot, split agents).

Look elsewhere when you need a ready-made NOS with a routing suite: the open source repo contains no general-purpose routing daemon (routes are programmed over Thrift, and BGP support in the CLI is still being upstreamed), and running on real hardware requires an ASIC vendor SDK that is not in the repository.

Project Status

The repository is very active, with main as the default branch. It does not ship a changelog or tagged releases; builds pin dependency revisions through fboss/oss/stable_commits/latest_stable_hashes.tar.gz. The license is BSD (see LICENSE). The repository's own documentation site lives in docs/ and is published by the project at meta.github.io/fboss.

Where to Go Next

Building FBOSS: the Docker build environment and run-getdeps.py.
Quick Start: build with fake SAI and talk to a simulated agent.
Architecture: processes, ports, and the agent's internal layers.
Agent Configuration: agent.conf and every other config file.
Packaging and Running on a Switch: from build tree to /opt/fboss.
fboss2 CLI and Diagnostic Tools.
Running Tests and Test Suites.
Troubleshooting.