fboss2 CLI

fboss2 is the operator CLI for FBOSS. It is a Thrift client: each command connects to the agent, qsfp_service, FSDB, or a platform service, calls an API, and formats the result as a table or JSON. This page covers the command structure, the global options (hosts, ports, output format, filtering, aggregation), and the complete command tree of the open source build. Session-based configuration with fboss2-dev has its own page: fboss2-dev Config Sessions.

Two Binaries

Binary Contents
fboss2 show, clear, set, bounce, start, stop, get, stream, help, and config gen agent
fboss2-dev Everything in fboss2, plus the config ... and delete ... configuration commands

Both are built by the fboss2_targets CMake target and installed in /opt/fboss/bin/. Bash completion is packaged as share/bash-completion/completions/ from fboss/oss/scripts/fboss2_completion.bash.

Note: The upstream CLI guide also lists create, reload, debug, and show version verbs. In the open source command tree (CmdList.cpp, oss/CmdList.cpp, CmdListConfig.cpp) these do not exist, except show bgp version and fboss2-dev config reload. They come from Meta-internal builds.

Command Syntax

fboss2 <verb> <object> [<sub-object> ...] [arguments] [options]
fboss2 --help
fboss2 show --help
fboss2 show interface --help

Examples:

fboss2 show port
fboss2 show port eth1/1/1
fboss2 show interface counters
fboss2 clear arp
fboss2 bounce interface eth1/1/1

Global Options

Option Default Meaning
-H, --host local switch Host(s) to query. Repeat for several switches.
--file FILE Query every host listed in the file (must exist).
--fmt tabular Output format: tabular or json.
-l, --loglevel DBG0 CLI debug log level.
--agent-port 5909 Agent Thrift port.
--qsfp-port 5910 qsfp_service Thrift port.
--fsdb-port 5908 FSDB Thrift port.
--color yes yes colors output on a TTY and not in a pipe; no disables color.
--filter EXPR Keep only rows matching the expression. See below.
--aggregate OP(column) Aggregate a column.
--aggregate-hosts false Aggregate across all queried hosts instead of per host.
--detail false Print detailed output (open source build).

Default ports for other services the CLI knows about include LED service 5930, hardware agents 5931 and 5932, sensor service 5970, data corral 5971, fan service 5972, and rackmon 5973.

Filtering and Aggregation

--filter takes terms of the form key op value, separated by single spaces, joined with && (and) and || (or):

fboss2 show port --filter "adminState == Enabled&&linkState == Down"
fboss2 show port --filter "name =^ eth1/1/||name =^ eth1/2/"
Operator Meaning
==, != Equal, not equal
<, <=, >, >= Comparisons
=^ Starts with
=~ Regular expression match

Rules from the parser in CmdGlobalOptions.cpp:

  • There are no parentheses. && binds tighter than ||, so A||B&&C means A || (B && C).
  • Each term must split on single spaces into exactly three parts. name==eth1 (no spaces) or a value containing a space fails with Each filter term must be of the form <key op value>.
  • An unknown operator fails with invalid operator passed for key <key>.
  • Valid keys are the fields of the command's output model. For show port these include id, name, adminState (Enabled, Disabled), linkState (Up, Down), speed, and profileId; the values in parentheses are the accepted values the command declares for those keys.

--aggregate takes OPERATOR(column) where the operator is SUM, MIN, MAX, AVG, or COUNT, for example --aggregate "COUNT(name)" on show port. A malformed argument fails with Expected aggregate argument in the form OPERATOR(column).

show Commands

show reads state and never changes the switch. Most show commands support --fmt json.

Command Description
show acl ACL entries per ACL table: priority, match fields, action
show agent ssl, show agent boot-type, show agent firmware Agent SSL information, cold or warm boot type, firmware information
show aggregate-port LAG (aggregate port) information
show arp ARP table: IP, MAC, interface, VLAN, state, TTL, class ID
show ndp NDP (IPv6 neighbor) table
show cpuport CPU port queues with ingress and discard packet counts
show fabric Fabric connectivity (VOQ / DSF systems)
show fabric reachability [uncached], show fabric topology, show fabric monitoring counters, show fabric monitoring details Fabric reachability (from SW cache, or directly from hardware with uncached), topology per virtual device, link monitoring
show fb303-counters Raw fb303 counters from an FBOSS service
show flowlet Flowlet switching information
show fsdb stats, show fsdb state, show fsdb subscribers, show fsdb publishers FSDB operational stats and state, and who is connected
show dsf subscription, show dsfnodes DSF subscriptions and the DSF node cluster
show host Connected hosts per port, with link, speed, FEC, error and discard counts
show hw-agent Per hardware agent: state and in-sync status of link, stats, FDB, RX/TX packet, and reachability streams
show hw-object [types...] [uncached] HW objects programmed in the ASIC; uncached queries hardware directly
show interface Interfaces: status, speed, VLAN, MTU, addresses, description
show interface counters Interface counters, with mka, fec (ber, uncorrectable, histogram, tail) sub-views
show interface errors, flaps, traffic, status Error counters, flap counters, traffic rates, status
show interface phy, phymap, capabilities PHY info for ASIC and/or external PHY, external PHY port map, supported port capabilities
show interface prbs capabilities, state, stats PRBS (pseudo-random bit sequence) testing
show interface transceiver, ... eeprom [dump], ... performance-monitoring Transceiver info per interface, EEPROM register reads, VDM performance monitoring
show l2 L2 table
show lldp LLDP neighbors
show mac, show mac blocked, show mac details MAC (L2) table and blocked MACs
show mirror Mirror sessions
show my-mac MY_MAC entries
show mysid SRv6 MySid entries
show mpls route MPLS routes
show nexthopgroups, show namednexthopgroups Next hop groups
show port Ports: ID, name, admin/link state, transceiver, speed, profile
show port queue Per-port queue configuration
show product, show product details Product (platform) information
show reboot-history The switch's reboot history and causes
show rif Router interfaces
show route, show route details, show route summary, show route counters Routing table, details, summary, route counters
show sdk dump Dump qsfp_service SDK state
show sdk agent Dump agent SDK state
show systemport System ports (VOQ switches)
show teflow TE flow entries
show transceiver, show transceiver loopback Transceivers, and loopback capability and state
show config running agent The agent's in-memory running config
show config history agent History of changes to the agent config
show bgp ... BGP state (neighbors, tables, policy, config, ...) from a BGP daemon on port 6909; under active development

show port cable-length exists only in Meta-internal builds.

clear, set, bounce, start, stop, get, stream

These verbs act on the running switch at runtime. Nothing is written to agent.conf: a later config reload, commit, or agent restart reverts them (see Config vs set).

Command Description
clear arp, clear ndp Flush the ARP or NDP table
clear interface counters [phy] Clear interface counters, or PHY counters
clear interface prbs stats Clear PRBS statistics
bounce interface <port> Shut and re-enable an interface
set port <ports> state <enable|disable> Set port admin state
set interface prbs state ... Enable or disable PRBS
set interface loopback <component> <enable|disable> Set loopback mode
set interface admin-state <xphy_system|xphy_line> <enable|disable> Set external PHY admin state
set transceiver loopback ... Set transceiver loopback mode
set fanhold ... Hold fans at a fixed PWM (talks to fan_service)
set sdk reg-dump ... Enable or disable SDK register/state dump logging to disk
start pcap, stop pcap, get pcap Start, stop, and fetch a packet capture
start port cable-length-measurement Trigger cable length measurement
stream fsdb stats, stream fsdb state Continuously stream FSDB data
config gen agent ... Generate agent configuration files (see Agent Configuration)

help

fboss2 help <object> lists every verb that applies to an object, which is the fastest way to discover what you can do with, say, interface:

fboss2 help interface

Recipes

Check that all hardware agents are in sync after a restart:

fboss2 show hw-agent

List only ports that are down, as JSON for a script:

fboss2 show port --filter "linkState == Down" --fmt json

Query two switches at once:

fboss2 -H switch1 -H switch2 show interface status

Talk to a test agent on a non-default port:

fboss2 --agent-port 5959 show port

Note: The CLI needs the target service to be running. When the agent or fboss_hw_agent is down, use the tools on Diagnostic Tools instead.

See Also