Monitoring and Configuration via the gRPC API

flockd supports a gRPC API for monitoring and configuring the router. The gRPC API uses Protocol Buffers for message serialization and HTTP/2 for transport. The flock_cli client uses the gRPC API.

Unlike the REST API which is read-only, the gRPC API also supports configuration updates (e.g. BGP neighbor and VRF configuration).

The flock_cli Client

flock_cli is the gRPC-based CLI client for flockd. It connects to the gRPC endpoint (default http://[::1]:50051) and supports multiple output formats.

Global Options

flock_cli [OPTIONS] <COMMAND>

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

Connecting to a Remote Router

By default, flock_cli connects to the local flockd instance via IPv6 loopback. To connect to a remote router, set the endpoint:

flock_cli -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
flock_cli sys overview

System Commands

System Overview

Returns system information including hostname, software version, uptime, enabled protocols, and software error count.

$ flock_cli -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,
  "uptime": "days: 1, hours: 3, mins: 22, secs: 15",
  "enabled_protocols": ["BGPv4", "OSPFv2", "Static"],
  "software_errors": 0,
  "global_thread_pool_size": 10
}

List VRFs

Returns all VRFs configured on the system.

$ flock_cli 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.

$ flock_cli -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

$ flock_cli 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.

$ flock_cli -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 flock_cli bgp vrf <name> <command>.

Unicast RIB Lookup

Look up a single prefix in the BGP unicast RIB.

$ flock_cli 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
$ flock_cli bgp vrf default rib walk 0.0.0.0/0

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

# Continue from a specific prefix
$ flock_cli 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
$ flock_cli bgp vrf default rib stats

# Include memory usage details
$ flock_cli 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

$ flock_cli bgp vrf default rib deagg-labels

Redistribution Policy

$ flock_cli bgp vrf default redist-policy

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

VPN Policy Statistics

$ flock_cli bgp vrf default vpn policy-stats

BGP Neighbor Commands

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

The neighbor address can be a simple IP (90.0.93.61) or include a source IP (70.0.100.72 70.0.100.70, space-separated and quoted).

Show Neighbor

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

# Include detailed statistics
$ flock_cli 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

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

Adjacency RIB Walk

Walk routes received from or advertised to a specific neighbor.

# Routes received from neighbor (adj-rib-in)
$ flock_cli 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)
$ flock_cli bgp vrf default neigh 90.0.93.61 adj-rib-unicast out walk 0.0.0.0/0

# RTC adj-rib
$ flock_cli bgp vrf default neigh 90.0.93.61 adj-rib-rtc in walk

BGP VPN RIB Commands

VPN RIB Lookup

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

VPN RIB Walk

$ flock_cli 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

$ flock_cli bgp vpn-rib stats [--ip-version <4|6>] [--memory]

BGP RTC RIB Commands

RTC RIB Lookup

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

RTC RIB Walk

$ flock_cli bgp rtc-rib walk

BGP AFI RIB Commands

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

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

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
$ flock_cli bgp config show

# Configuration for a specific VRF
$ flock_cli -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:

$ flock_cli bgp config init
initialized .bgp_pending_config

Step 2: Stage Changes

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

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

Step 3: Review Pending Changes

Inspect what will be applied before committing:

$ flock_cli bgp config show-pending

Step 4: Apply

Apply all staged changes atomically to the running router:

$ flock_cli bgp config apply
config applied

Example: Adding a BGP Neighbor

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

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

# Review - the pending config shows the staged addition
$ flock_cli 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
$ flock_cli bgp config apply
config applied

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

$ flock_cli 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
$ flock_cli bgp config init
initialized .bgp_pending_config

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

# Review - the pending config shows delete:true
$ flock_cli 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
$ flock_cli bgp config apply
config applied

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

$ flock_cli bgp vrf default neigh 10.99.99.1 show
null

Configuration Set Options

Global BGP settings:

$ flock_cli bgp config set [--asn <ASN>] [--route-server] [--route-reflector]

VRF settings:

$ flock_cli bgp config vrf <name> set [--multipath] [--redist-policy <policy>]
$ flock_cli bgp config vrf <name> delete

Neighbor settings:

$ flock_cli bgp config vrf <name> neigh <addr> set \
    [--asn <ASN>] [--local-as <ASN>] \
    [--route-reflector-client] [--next-hop-self] \
    [--disabled] [--connect-mode <mode>]
$ flock_cli bgp config vrf <name> neigh <addr> delete

Output Formats

flock_cli supports five output formats via the -f flag:

Example using YAML:

$ flock_cli -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
    ...

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

Example: Connecting with grpcurl

# List available services
grpcurl -plaintext [::1]:50051 list

# Get system overview
grpcurl -plaintext [::1]:50051 sys.SysService/GetOverview

# Get BGP overview
grpcurl -plaintext -d '{}' [::1]:50051 bgp_oper.BgpOperService/GetOverview

Example: Connecting with Python

import grpc
# Generated from proto files using grpc_tools.protoc
import sys_pb2, sys_pb2_grpc

channel = grpc.insecure_channel('[::1]:50051')
stub = sys_pb2_grpc.SysServiceStub(channel)
response = stub.GetOverview(sys_pb2.GetOverviewRequest())
print(response)

gRPC Command Reference

System Service RPCs

BGP Operational Service RPCs

BGP Configuration Service RPCs