Quick Start

This tutorial takes you from a fresh clone to a running FBOSS agent you can query with the fboss2 CLI, without any switch hardware. It uses the fake SAI build and the fboss-sim Docker runtime that ships in the repository. At the end you will have the software agent and a hardware agent running as systemd services in a container, and you will have changed a setting through a fboss2-dev config session.

Note: Nothing here touches real hardware. Fake SAI accepts the agent's programming calls but forwards no packets. Use it to learn the processes, the CLI, and the config workflow, or to develop CLI and agent logic quickly.

What You Need

  • A Linux host with Docker and sudo.
  • Roughly 50 GB of free disk for the build tree, and a machine with plenty of RAM.
  • A clone of the repository (see Building FBOSS).

Step 1: Build the Build Image and Start the Container

From the repository root:

sudo docker build . -t fboss_image -f fboss/oss/docker/Dockerfile

rm -rf build/deps/github_hashes/
tar xvzf fboss/oss/stable_commits/latest_stable_hashes.tar.gz

sudo docker run -d -it --name=FBOSS_BUILD_CONTAINER \
    -v $PWD:/var/FBOSS/fboss:z \
    -v /opt/app/localbuild:/var/FBOSS/tmp_bld_dir:z \
    fboss_image:latest bash

Expected result: docker build finishes with the image tagged fboss_image:latest, and docker run prints a container ID.

Step 2: Build FBOSS With Fake SAI

Enter the container and build your checkout. Because no --npu-sai-impl is given, the wrapper selects fake SAI:

sudo docker exec -it FBOSS_BUILD_CONTAINER bash
cd /var/FBOSS/fboss
time ./fboss/oss/scripts/run-getdeps.py build --allow-system-packages \
  --extra-cmake-defines='{"CMAKE_BUILD_TYPE": "MinSizeRel", "CMAKE_CXX_STANDARD": "20", "RANGE_V3_TESTS": "OFF", "RANGE_V3_PERF": "OFF"}' \
  --scratch-path /var/FBOSS/tmp_bld_dir --src-dir . fboss

Early in the output you should see lines like:

Starting run-getdeps.py
No SAI implementation provided, defaulting to fake SAI build (BUILD_SAI_FAKE=1)
=== Build pass 1/1: fake SAI ===
Set ENV BUILD_SAI_FAKE=1

The first build compiles every dependency and takes a long time. When it finishes, the binaries the simulator needs are in /var/FBOSS/tmp_bld_dir/build/fboss/: wedge_agent-sai_impl, fboss_sw_agent, fboss_hw_agent-sai_impl, fboss2, fboss2-dev, and fboss2_integration_test.

Step 3: Start the Simulator

Exit the build container and, on the host, start the simulator in local mode, which bind-mounts your build tree into a container instead of building a separate runtime image:

sudo fboss-sim/scripts/fboss-sim-docker-run.py --local \
  --build-dir /opt/app/localbuild \
  --runpath-dir /var/FBOSS/tmp_bld_dir \
  --build-image fboss_image:latest

Why these flags:

  • --build-dir is the host path of the getdeps scratch directory (it must contain build/ and installed/). Here it is the host side of the /var/FBOSS/tmp_bld_dir mount.
  • --runpath-dir must be the path the binaries were built at, because that path is baked into their RUNPATH. Without it, the script mounts the build tree at the same path as --build-dir.
  • --build-image is needed because the script's default image name is fboss_docker:latest, while the build instructions tag the image fboss_image:latest.

If you built in place on the host with a scratch path of /var/FBOSS/tmp_bld_dir, --build-dir /var/FBOSS/tmp_bld_dir alone is enough, which is the form the repo's CLI docs use.

The script creates an IPv6-enabled Docker network named fboss_sim_net_<user> (subnet fd00:fb05:5::/64) and a container named fboss_sim_runtime_<user>. Under sudo the user is root, so the container is fboss_sim_runtime_root; the commands below use that name.

Note: The IPv6 network matters. In split mode the hardware agent connects to the software agent at ::1. Docker's default bridge disables IPv6 on eth0, so the agent's Thrift servers would bind only to IPv4 and that connection would be refused.

Step 4: Check the Agents

By default (--mode multi) the container runs the agent in split mode: fboss_sw_agent plus fboss_hw_agent@0, each a systemd unit.

sudo docker exec fboss_sim_runtime_root systemctl status fboss_sw_agent
sudo docker exec fboss_sim_runtime_root systemctl status fboss_hw_agent@0

Both should report active (running). Their logs are in separate files:

sudo docker exec fboss_sim_runtime_root tail -f /var/facebook/logs/fboss/sw_agent.log
sudo docker exec fboss_sim_runtime_root tail -f /var/facebook/logs/fboss/hw_agent0.log

Step 5: Query the Agent With fboss2

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 port
sudo docker exec fboss_sim_runtime_root /opt/fboss/bin/fboss2 show hw-agent

show hw-agent prints one row per hardware agent with its sync state, similar to:

Output Format: <InSync/OutofSync - [Y]es/[N]o  | No. of Events sent | No. of Events received>
 SwitchIndex  SwitchId  State       Link  Stats  Fdb    RxPkt  TxPkt  SwitchReachability
 0            0         CONFIGURED  ...

(Illustrative: the exact counters depend on how long the agent has run.) Most show commands also accept --fmt json for scripting. See fboss2 CLI for the full command tree.

Step 6: Change the Configuration

fboss2-dev adds session-based configuration. Stage a change, review it, then commit:

sudo docker exec -it fboss_sim_runtime_root bash
cd /opt/fboss && source ./bin/setup_fboss_env
fboss2-dev config interface eth1/1/1 description "Peer link to device XYZ"
fboss2-dev config session diff
fboss2-dev config session commit
fboss2-dev config history

Staging prints a confirmation such as Successfully configured interface(s) eth1/1/1: description="Peer link to device XYZ". The diff is a unified diff of the agent config; the commit reports the new revision and how it was applied, for example Config session committed successfully as 21c94ca and config reloaded for fboss_sw_agent. Use an interface name that show interface listed in your container. The workflow is explained in fboss2-dev Config Sessions.

Step 7: Run the CLI Integration Tests (Optional)

sudo docker exec fboss_sim_runtime_root /opt/fboss/bin/fboss2_integration_test

This gtest binary exercises CLI commands against the running agent.

Iterating and Cleaning Up

  • After rebuilding, you only need to restart the agents; in --local mode the container runs the binaries from your build tree directly.
  • Switch to a single monolithic wedge_agent process with sudo docker exec fboss_sim_runtime_root switch-agent-mode.sh mono (and back with split).
  • Remove the container and its network with sudo fboss-sim/scripts/fboss-sim-docker-run.py --teardown.

Alternative: A Standalone Runtime Image

Instead of --local, you can bake a small (~1.2 GB) CentOS Stream 9 runtime image that contains only the needed binaries and their libraries:

python3 fboss-sim/scripts/fboss-sim-docker-package.py
python3 fboss-sim/scripts/fboss-sim-docker-run.py

The packager looks for binaries in <repo>/.build_dir/build/fboss/ (the scratch path getdeps uses when you build without --scratch-path). It has two phases, --collect-only (resolve libraries with ldd, which must run on a CentOS Stream 9 system such as the build container) and --build-only (run docker build on the host); with no flag it does both.

Next Steps