Skip to content

04-cli.md

Latest commit

 

History

History
305 lines (229 loc) · 7.85 KB

04-cli.md

File metadata and controls

305 lines (229 loc) · 7.85 KB

CLI Reference

Cobra reeflective/console ConnectRPC Formats

Complete reference for gobfdctl -- the CLI client for managing BFD sessions, monitoring events, and interacting with the gobfd daemon.

Table of Contents

Overview

gobfdctl communicates with the gobfd daemon via ConnectRPC (compatible with gRPC, Connect, and gRPC-Web protocols). It provides both non-interactive commands (via Cobra) and an interactive shell (via reeflective/console) with tab completion.

gobfdctl [global flags] <command> [subcommand] [flags]

Global Flags

Flag Default Description
--addr localhost:50051 gobfd daemon address (host:port)
--format table Output format: table, json, yaml

Session Commands

List all sessions

gobfdctl session list

Shows all BFD sessions with their current state, peer address, timers, and discriminators.

Show a specific session

# By peer address
gobfdctl session show 10.0.0.1

# By local discriminator
gobfdctl session show 42

Create a session

# Single-hop BFD session
gobfdctl session add \
  --peer 10.0.0.1 \
  --local 10.0.0.2 \
  --interface eth0 \
  --type single-hop \
  --tx-interval 100ms \
  --rx-interval 100ms \
  --detect-mult 3

# Multihop session
gobfdctl session add \
  --peer 192.168.1.1 \
  --local 192.168.2.1 \
  --type multi-hop \
  --tx-interval 300ms \
  --detect-mult 5

# Authenticated session
gobfdctl session add \
  --peer 10.0.0.1 \
  --local 10.0.0.2 \
  --auth-type keyed-sha1 \
  --auth-key-id 7 \
  --auth-secret api-auth-secret
Flag Required Default Description
--peer Yes -- Remote system IP address
--local Yes -- Local system IP address
--interface No -- Network interface (for SO_BINDTODEVICE)
--type No single-hop Session type: single-hop or multi-hop
--tx-interval No 1s Desired Min TX Interval
--rx-interval No 1s Required Min RX Interval
--detect-mult No 3 Detection Multiplier
--auth-type No none Auth type: none, simple-password, keyed-md5, meticulous-keyed-md5, keyed-sha1, meticulous-keyed-sha1
--auth-key-id If auth enabled 0 RFC 5880 Auth Key ID, range 0-255
--auth-secret If auth enabled -- Auth secret: 1-16 bytes for Simple Password/MD5, 1-20 bytes for SHA1

Delete a session

# By local discriminator
gobfdctl session delete 42

Echo Commands

RFC 9747 unaffiliated BFD echo sessions live under a separate command group because their timer model differs from RFC 5880 control sessions: TxInterval is locally provisioned and not negotiated with the peer.

List echo sessions

gobfdctl echo list

Create an echo session

gobfdctl echo add \
    --peer 10.0.0.1 \
    --local 10.0.0.2 \
    --tx-interval 50ms \
    --detect-mult 3
Flag Required Default Description
--peer Yes -- Echo target IP address
--local No -- Local IP address (fallback to default route)
--interface No -- Outbound interface for SO_BINDTODEVICE
--tx-interval No 1s Echo transmit interval (RFC 9747 Section 3.3)
--detect-mult No 3 Detection multiplier; DetectionTime = mult * TxInterval

Delete an echo session

gobfdctl echo delete 42

Micro-BFD Commands

RFC 7130 micro-BFD groups bind one BFD session per LAG member link. The CLI manages the group resource; per-member sessions are created in the daemon when the group is added.

List micro-BFD groups

gobfdctl micro list

Create a micro-BFD group

gobfdctl micro add \
    --lag bond0 \
    --members eth0,eth1,eth2 \
    --peer 10.0.0.1 \
    --local 10.0.0.2 \
    --tx-interval 300ms \
    --rx-interval 300ms \
    --detect-mult 3 \
    --min-active 2
Flag Required Default Description
--lag Yes -- LAG interface name (bond0, team0, port-channel1)
--members Yes -- Comma-separated member link names
--peer Yes -- Peer IP address shared by every member session
--local No -- Local IP address
--tx-interval No 1s Desired minimum TX interval
--rx-interval No 1s Required minimum RX interval
--detect-mult No 3 Detection multiplier (RFC 7130 Section 2.2)
--min-active No 1 Minimum active members for aggregate Up

The CLI rejects --min-active outside [1, len(--members)] before contacting the daemon.

Delete a micro-BFD group

gobfdctl micro delete bond0

Monitor Command

Stream live BFD events (state changes) from the daemon:

# Stream only new events
gobfdctl monitor

# Stream events with initial snapshot of all sessions
gobfdctl monitor --current
Flag Default Description
--current false Include current session states before streaming

The monitor uses gRPC server-side streaming. Each event includes:

  • Timestamp
  • Session identifier (peer address, local discriminator)
  • Old state and new state
  • Diagnostic code
  • Event trigger

Press Ctrl+C to stop monitoring.

Version Command

All binaries support version display with commit hash and build date:

gobfd --version
gobfdctl version
gobfd-haproxy-agent --version
gobfd-exabgp-bridge --version

Example output:

gobfdctl v0.1.0
  commit:  abc1234
  built:   2026-02-22T12:00:00Z

Version information is injected at build time via ldflags (see 09-development.md).

Interactive Shell

gobfdctl shell

Launches an interactive shell with:

  • Tab completion for commands and subcommands
  • Readline autocomplete via reeflective/console (derived from Cobra command tree)
  • Full access to all gobfdctl commands without the gobfdctl prefix

Example session:

gobfd> session list
gobfd> session show 10.0.0.1
gobfd> monitor --current
gobfd> exit

Output Formats

All commands support three output formats via the --format flag:

Format Use Case
table Human-readable terminal output (default)
json Machine-parseable, scripting, piping to jq
yaml Human-readable structured output 
# JSON output for scripting
gobfdctl session list --format json

# YAML output
gobfdctl session list --format yaml

# Pipe JSON to jq
gobfdctl session list --format json | jq '.sessions[].state'

Examples

# Connect to remote daemon
gobfdctl --addr 10.0.0.1:50051 session list

# Quick session setup for testing
gobfdctl session add --peer 10.0.0.1 --local 10.0.0.2 --interface eth0 \
  --tx-interval 100ms --detect-mult 3

# Watch for state changes in JSON
gobfdctl --format json monitor --current

# Scripted health check
if gobfdctl session show 10.0.0.1 --format json | jq -e '.state == "Up"' > /dev/null; then
  echo "BFD session is Up"
fi

Related Documents

Last updated: 2026-02-21