Flock Routing Suite Client: flockc

flockc is the CLI client bundled with flockd for monitoring and configuring the router. It talks to flockd over gRPC (Protocol Buffers over HTTP/2) and supports both read operations (querying operational state) and write operations (applying configuration updates, e.g. BGP neighbor and VRF configuration).

flockc connects to the gRPC endpoint (default http://[::1]:50051) and supports multiple output formats.

Global Options

flockc [OPTIONS] <COMMAND>

Options:
  -e, --endpoint <ENDPOINT>  [env: FLOCK_ENDPOINT=] [default: http://[::1]:50051]
  -f, --format <FORMAT>      [default: json] [possible values: debug, debug-pretty, json, json-pretty, yaml]
  -h, --help                 Print help
  -V, --version              Print version

-e selects the gRPC endpoint and -f the output format. Every command and subcommand accepts --help.

Connecting to a Remote Router

By default, flockc connects to the local flockd instance via IPv6 loopback, which is also the only address flockd listens on unless the system configuration names another:

"system": {
    "api": {
        "grpc": {
            "bind_ip_addr": "::",
            "bind_port": 50051
        }
    }
}

Both fields are optional and default to ::1 and 50051. flockd reads them only when it starts, so a change to them takes effect the next time flockd starts. To connect to a remote router, set the endpoint:

flockc -e http://10.0.1.1:50051 sys overview

Or via the FLOCK_ENDPOINT environment variable:

export FLOCK_ENDPOINT=http://10.0.1.1:50051
flockc sys overview

Commands

Each top-level command queries one component. This chapter covers sys and bgp in detail; the component chapters cover the rest.

System Commands

System Overview

Returns system information including hostname, software version, uptime, enabled protocols, software error count, and whether maintenance mode is set.

$ flockc -f json-pretty sys overview
{
  "host_info": {
    "hostname": "R01",
    "domain": null,
    ...
  },
  "system_info": {
    "name": "flockd",
    "description": "The Flock Networks Ltd Routing Suite Daemon",
    ...
    "version": "0.0.2",
    ...
  },
  "fire_info": {
    "name": "fire",
    "description": "Flock Internet Routing Engine (FIRE)",
    ...
    "version": "0.1.0",
    ...
  },
  "pid": 12345,
  "log_level": "info",
  "uptime": "days: 1, hours: 3, mins: 22, secs: 15",
  "enabled_protocols": ["BGPv4", "OSPFv2", "Static"],
  "software_errors": 0,
  "global_thread_pool_size": 10,
  "maintenance_mode": false
}

sys vrf <name>, sys list-interfaces and sys interface <name> are described in the System Component chapter.

List VRFs

Returns all VRFs configured on the system.

$ flockc sys list-vrfs
[{"vrf_id":254,"vrf_name":"default","underlay_vrf_name":null,...}]

BGP Commands

BGP Overview

Returns the BGP instance overview including BGP ID, ASN, route counts per VRF, and neighbor summary.

$ flockc -f json-pretty bgp overview
{
  "id": "70.0.100.70",
  "asn": 70,
  "route_server": false,
  "route_reflector": false,
  ...
  "total_event_loops": 571,
  ...
  "routes": {
    "unicast_routes": {
      "default": {
        "ipv4_unicast": { "route_count": 3, "attr_list_store_count": 1 },
        "ipv6_unicast": { "route_count": 0, "attr_list_store_count": 0 }
      }
    },
    "vpn_routes": {}
  },
  "neighbor_summary": {
    "default": {
      "count": 4,
      "established": 4,
      "send_converged": 4,
      "recv_converged": 4
    }
  }
}

List BGP VRFs

$ flockc bgp list-vrfs
[{"vrf_id":254,"vrf_name":"default","vrf_info":{...,"neighs":["90.0.93.61","70.0.100.73 70.0.100.70",...]},...}]

BGP Event Log

Returns the BGP event log showing neighbor state changes.

$ flockc -f json-pretty bgp event-log
{
  "object_oper": {
    "db": [
      {
        "event": "AddOrUpdate",
        "object_desc": "BGP Peer VrfId(254) 90.0.93.61",
        "time": "2026-02-27T13:42:00.015Z"
      },
      {
        "event": "Up",
        "object_desc": "BGP Peer VrfId(254) 90.0.93.61",
        "time": "2026-02-27T13:42:00.185Z"
      },
      ...
    ]
  }
}

BGP VRF Commands

All VRF-scoped commands use the form flockc bgp vrf <name> <command>.

Show a VRF

Returns the named VRF's row from bgp list-vrfs, including its neighbor list.

$ flockc bgp vrf default show

Unicast RIB Lookup

Look up a single prefix in the BGP unicast RIB.

$ flockc bgp vrf default rib lookup 50.0.0.0/8

Unicast RIB Walk

Walk the BGP unicast RIB starting from a root prefix. Supports pagination via --start-from and --max-entries.

# Walk all routes
$ flockc bgp vrf default rib walk 0.0.0.0/0

# Walk with pagination (1 entry at a time)
$ flockc bgp vrf default rib walk 0.0.0.0/0 --max-entries 1

# Continue from a specific prefix
$ flockc bgp vrf default rib walk 0.0.0.0/0 --start-from 60.0.0.0/8 --max-entries 1

Each entry in the walk response includes a finished field indicating whether there are more entries to retrieve.

Unicast RIB Statistics

# Basic counters
$ flockc bgp vrf default rib stats

# Include memory usage details
$ flockc bgp vrf default rib stats --memory

Returns IPv4 and IPv6 counters: total prefixes, path counts by type (iBGP, eBGP, originated, redistributed, VPN-imported), and optionally memory usage per RIB entry.

De-aggregation Labels

$ flockc bgp vrf default rib deagg-labels

Redistribution Policy

$ flockc bgp vrf default redist-policy

Returns the redistribution policy status and statistics including hit counts and accept/reject counters.

VPN Policy Statistics

$ flockc bgp vrf default vpn policy-stats

BGP Neighbor Commands

Neighbor commands use the form flockc bgp vrf <vrf> neigh <addr> <command>.

The neighbor address is the neighbor's IP address (90.0.93.61). A neighbor configured with a local source address, keyed "70.0.100.72 70.0.100.70" in the configuration, is named by its own address alone (70.0.100.72). A link-local IPv6 neighbor also names its interface as a scope (fe80::2%eth0).

Show Neighbor

# Basic neighbor info
$ flockc bgp vrf default neigh 90.0.93.61 show

# Include detailed statistics
$ flockc bgp vrf default neigh 90.0.93.61 show --stats

Returns neighbor state (Established/Idle/etc.), capabilities, timers, keepalive counters, and optionally per-AFI statistics including policy hit counts and adj-rib prefix counts.

Reset Neighbor

$ flockc bgp vrf default neigh 90.0.93.61 reset soft-in
$ flockc bgp vrf default neigh 90.0.93.61 reset soft-out
$ flockc bgp vrf default neigh 90.0.93.61 reset hard
$ flockc bgp vrf default neigh 90.0.93.61 reset refresh-in
$ flockc bgp vrf default neigh 90.0.93.61 reset refresh-out

Adjacency RIB Commands

Look up one prefix in, or walk the whole of, the routes received from or advertised to a specific neighbor. Every scope takes the direction, in or out, before the command.

# Routes received from neighbor (adj-rib-in)
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-unicast in walk 0.0.0.0/0

# Routes advertised to neighbor (adj-rib-out)
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-unicast out walk 0.0.0.0/0

# One prefix rather than the whole table
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-unicast in lookup 10.0.0.0/24

# RTC adj-rib
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-rtc in walk
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-rtc in lookup <rtc-net>

# VPN adj-rib, keyed by route distinguisher and prefix
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-vpn in lookup <rd> <ip-net>
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-vpn in walk <rd> <ip-net>

# Private adj-rib, which takes the address family before the direction
$ flockc bgp vrf default neigh 90.0.93.61 adj-rib-private ipv4-unicast in walk 0.0.0.0/0

Each adj-rib-in path carries not_in_rib_reason, which says why the path is not in the BGP RIB; see the BGP Component chapter.

BGP VPN RIB Commands

VPN RIB Lookup

$ flockc bgp vpn-rib lookup <rd> <ip-net>

VPN RIB Walk

$ flockc bgp vpn-rib walk <rd> <ip-net> [--start-from-rd <rd>] [--start-from-ip-net <ip-net>] [--max-entries N] [--walk-rds]

VPN RIB Statistics

$ flockc bgp vpn-rib stats [--af <ipv4|ipv6>] [--rd <rd>] [--memory]

BGP RTC RIB Commands

RTC RIB Lookup

$ flockc bgp rtc-rib lookup <rtc-net>

An RTC network is either Default or origin_as:<asn>,<route-target>, for example origin_as:200,route-target:0:100:100. The same form is taken by adj-rib-rtc ... lookup, and a malformed one is refused before any request is sent.

RTC RIB Walk

$ flockc bgp rtc-rib walk

BGP AFI RIB Commands

Query AFI-specific RIBs (e.g., EVPN).

$ flockc bgp vrf default afi-rib <afi> lookup <prefix>
$ flockc bgp vrf default afi-rib <afi> walk <root> [--start-from <prefix>] [--max-entries N]

BGP EVPN Commands

$ flockc bgp evpn rib walk [<rd>]
$ flockc bgp evpn rib lookup <rd> <ip-addr>
$ flockc bgp evpn nve walk [--vni <vni>]
$ flockc bgp evpn es walk
$ flockc bgp evpn es lookup <esi>

BGP Configuration Commands

The gRPC API supports reading and updating BGP configuration. Configuration changes use a pending-config workflow: changes are staged locally in a .bgp_pending_config file, then applied atomically to the running router.

Show Current Configuration

# Full configuration
$ flockc bgp config show

# Configuration for a specific VRF
$ flockc -f json-pretty bgp config show --vrf default
[
  {
    "name": "default",
    "multipath": false,
    "neighs": [
      {
        "key": { "dst": { "version": { "V4": 1509973309 } }, "src": null },
        "asn": 60,
        "local_as": 70,
        "route_reflector_client": false,
        "next_hop_self": false,
        "disabled": false,
        "connect_mode": "Both",
        ...
      }
    ],
    "networks": [
      { "prefix": "70.0.0.0/8", "originate_always": false }
    ],
    ...
  }
]

Pending Configuration Workflow

Configuration changes follow a four-step workflow: initialize, stage, review, apply.

Step 1: Initialize

Create a fresh pending configuration staging file:

$ flockc bgp config init
initialized .bgp_pending_config

Step 2: Stage Changes

Stage one or more changes. Multiple changes can be staged before applying:

$ flockc bgp config set --asn 65001
$ flockc bgp config vrf default set --multipath true
$ flockc bgp config vrf default neigh 10.0.0.1 set --asn 65002

Step 3: Review Pending Changes

Inspect what will be applied before committing:

$ flockc bgp config show-pending

Step 4: Apply

Apply all staged changes atomically to the running router:

$ flockc bgp config apply
config applied

Example: Adding a BGP Neighbor

# Initialize pending config
$ flockc bgp config init
initialized .bgp_pending_config

# Stage the new neighbor
$ flockc bgp config vrf default neigh 10.99.99.1 set --asn 65099 --local-as 70

# Review - the pending config shows the staged addition
$ flockc bgp config show-pending
{"asn":null,...,"vrfs":{"clear":false,"ops":[{"name":"default","delete":false,
  "neighs":{"clear":false,"ops":[{"key":{"dst":{"version":{"V4":174285569}},
  "src":null,"zone":null},"delete":false,"asn":{"v":{"Set":65099}},
  "local_as":{"v":{"Set":70}},...}]}}]}}

# Apply to the running router
$ flockc bgp config apply
config applied

# Verify - neighbor count increased and the new neighbor is visible
$ flockc bgp overview
{...,"neighbor_summary":{"default":{"count":5,"established":4,...}}}

$ flockc bgp vrf default neigh 10.99.99.1 show
{"common":{"neigh_key":"10.99.99.1","asn":65099,"local_as":70,
  "neigh_type":"External","connect_mode":"Both",...},...}

Example: Deleting a BGP Neighbor

# Initialize pending config
$ flockc bgp config init
initialized .bgp_pending_config

# Stage the deletion
$ flockc bgp config vrf default neigh 10.99.99.1 delete

# Review - the pending config shows delete:true
$ flockc bgp config show-pending
{"asn":null,...,"vrfs":{"clear":false,"ops":[{"name":"default","delete":false,
  "neighs":{"clear":false,"ops":[{"key":{"dst":{"version":{"V4":174285569}},
  "src":null,"zone":null},"delete":true,...}]}}]}}

# Apply to the running router
$ flockc bgp config apply
config applied

# Verify - neighbor count decreased and the neighbor is gone
$ flockc bgp overview
{...,"neighbor_summary":{"default":{"count":4,"established":4,...}}}

$ flockc bgp vrf default neigh 10.99.99.1 show
null

Configuration Set Options

Boolean options take an explicit true or false, so a staged change can turn a setting off as well as on.

Global BGP settings:

$ flockc bgp config set [--asn <ASN>] [--route-server <true|false>] [--route-reflector <true|false>]

VRF settings:

$ flockc bgp config vrf <name> set [--multipath <true|false>] [--redist-policy <policy>]
$ flockc bgp config vrf <name> delete

Neighbor settings:

$ flockc bgp config vrf <name> neigh <addr> set \
    [--asn <ASN>] [--local-as <ASN>] \
    [--route-reflector-client <true|false>] [--next-hop-self <true|false>] \
    [--disabled <true|false>] [--connect-mode <mode>] \
    [--auth-password-file <path> | --clear-auth-password-file]
$ flockc bgp config vrf <name> neigh <addr> delete

--connect-mode takes Active, Passive or Both, in any case; bgp config show writes it capitalised. --auth-password-file names a TCP-MD5 key file by its absolute path on the flockd host, and --clear-auth-password-file removes the key; see the BGP Component chapter.

Output Formats

flockc supports five output formats via the -f flag:

Example using YAML:

$ flockc -f yaml bgp vrf default rib stats
v4:
  counters:
    total_prefixes: 3
    num_ibgp_regular_paths: 0
    num_ebgp_regular_paths: 2
    num_originated_paths: 1
    ...
v6:
  counters:
    total_prefixes: 0
    ...

An object that does not exist is printed as null (or an empty list), and errors are written to standard error. flockc exits with status 0 when a command succeeds, including a lookup that finds nothing, and non-zero when it fails -- a command line it cannot parse, a connection it cannot make, or a request flockd refuses.

3rd Party gRPC Clients

Since the gRPC API uses standard Protocol Buffers and HTTP/2, any gRPC client library can connect to flockd. The .proto service definitions are located in the flock_grpc/proto/ directory.

Available Services

A service is served only when flockd is built with the component behind it.

Example: Connecting with grpcurl

flockd does not serve gRPC reflection, so give grpcurl the proto files:

# List the services a proto file defines
grpcurl -import-path flock_grpc/proto -proto sys_oper.proto list

# Get system overview
grpcurl -plaintext -import-path flock_grpc/proto -proto sys_oper.proto \
    '[::1]:50051' flock.sys.Sys/GetOverview

# Get BGP overview
grpcurl -plaintext -import-path flock_grpc/proto -proto bgp_oper.proto \
    -d '{}' '[::1]:50051' flock.bgp.Bgp/GetOverview

Example: Connecting with Python

import grpc
# Generated from sys_oper.proto and common.proto using grpc_tools.protoc
import sys_oper_pb2, sys_oper_pb2_grpc

channel = grpc.insecure_channel('[::1]:50051')
stub = sys_oper_pb2_grpc.SysStub(channel)
response = stub.GetOverview(sys_oper_pb2.GetOverviewRequest())
print(response)

gRPC Command Reference

The RPCs of the system and BGP services are listed below. Each other service's RPCs are listed in its proto file.

System Service RPCs (flock.sys.Sys)

BGP Operational Service RPCs (flock.bgp.Bgp)

BGP Configuration Service RPCs (flock.bgp.BgpConfiguration)