API/CLI

The control socket is an unix domain stream socket that allows interacting with the BNG Blaster using JSON RPC.

We developed this interface for the BNG Blaster Controller it can also be used by other tools. One example is the included CLI tool bngblaster-cli. You can use this for interactive communication with the BNG Blaster.

You need to enable the control socket by providing the path to the control socket file with the argument -S (bngblaster -S run.sock).

Each request must contain at least the command element which carries the actual command with optional arguments.

{
    "command": "<command>",
    "arguments": {
        "<argument-key>": "<argument-value>"
    }
}

The following is an example RPC request with its corresponding response.

$ cat command.json | jq .

{
    "command": "session-counters"
}

$ cat command.json | sudo nc -U run.sock | jq .

{
    "status": "ok",
    "code": 200,
    "session-counters": {
        "sessions": 3,
        "sessions-established": 3,
        "sessions-flapped": 3,
        "dhcpv6-sessions-established": 3
    }
}

The response contains at least the status element with the value ok and status code 2xx if the request was successful. The status can also be set to warning or error with corresponding error code and an optional error message.

$ cat command.json | sudo nc -U run.sock | jq .

{
    "status": "warning",
    "code": 404,
    "message": "session not found"
}

The session-id is the same as used for {session-global} in the configuration. This number starts with 1 and is increased per session added. For example, if the username is configured as user{session-global}@rtbrick.com and logged in user is user10@rtbrick.com the session-id of this user is 10.

Tip

The argument session-id can be alternatively replaced with interface and VLAN of the session. The first access interface is automatically used if the argument interface is not present in the command.

This is not supported for N:1 sessions because multiple sessions can be assigned to a single VLAN.

{
    "command": "session-info",
    "arguments": {
        "interface": "eth0",
        "outer-vlan": 1,
        "inner-vlan": 1
    }
}

BNG Blaster CLI

The python script bngblaster-cli provides a simple CLI tool for interactive communication with the BNG Blaster.

$ sudo bngblaster-cli
BNG Blaster CLI Tool

The CLI tool is a simple control socket client
for interactive communication with the BNG Blaster.

bngblaster-cli <socket> <command> [arguments]

Examples:
    bngblaster-cli run.sock session-info session-id 1
    bngblaster-cli run.sock interface-topology
    bngblaster-cli run.sock interface-topology interface eth0
    bngblaster-cli run.sock igmp-join session-id 1 group 239.0.0.1 source1 1.1.1.1 source2 2.2.2.2 source3 3.3.3.3
    bngblaster-cli run.sock igmp-info session-id 1
    bngblaster-cli run.sock l2tp-csurq tunnel-id 1 sessions [1,2]

Bash completion for bngblaster-cli is installed to /usr/share/bash-completion/completions/bngblaster-cli and picked up automatically by the bash-completion package (or can be sourced manually). It completes the socket path, the command name and its arguments by querying the commands endpoint of the running instance referenced by the socket path already typed, so suggestions always match that instance.

$ sudo bngblaster-cli run.sock session-counters | jq .

{
    "status": "ok",
    "code": 200,
    "session-counters": {
        "sessions": 1,
        "sessions-established": 1,
        "sessions-flapped": 0,
        "dhcpv6-sessions-established": 1
    }
}

Here’s a more complex example that chains CLI commands. The first command returns a list of all pending sessions. Then, it extracts the session.id from those sessions into a flat list. Finally, it iterates over this list, using each session-id as an argument for the session-restart command.

$ sudo bngblaster-cli run.sock sessions-pending | jq '.["sessions-pending"][]["session-id"]' | while read line; do sudo bngblaster-cli run.sock session-restart session-id $line; done

Test

Command	Description
test-info	Display information about the test instance, including its status (starting, running or stopping) and current task, which is available also during the startup (see below).
threads	Display the main thread and all I/O threads with the CPU they are pinned to, available once all threads are started.
test-stop	Stop/teardown the test (graceful, global).
terminate	Deprecated. Terminate the given `session-id`, or stop/teardown the whole test if no `session-id` is given. Use `session-start`/`session-stop` instead for terminating single sessions. Arguments: `session-id` `reconnect-delay`
monkey-start	Start monkey test.
monkey-stop	Stop monkey test.

The control socket is opened right after the log file, before the configuration is loaded, so that a controller can follow the startup and shutdown of the instance with test-info. During the startup and after the test has finished, only test-info, commands and threads (once all threads are started) are available, while all other commands are answered with status code 503 (not available while starting or not available while stopping). A controller should therefore wait until the status is running before sending other commands. During the teardown (task teardown), all commands remain available.

The startup can be aborted with test-stop or terminate (without session-id) via control socket, or with the signals SIGINT, SIGTERM or SIGHUP, also while waiting for the startup of other instances. The instance then restores the interface configuration, releases all resources and exits with status 3 without generating reports, which distinguishes an aborted startup from a test (0) or an error (1).

$ sudo bngblaster-cli run.sock test-info

{
    "status": "ok",
    "code": 200,
    "test-info": {
        "state": "init",
        "duration": 0,
        "status": "starting",
        "task": "wait-startup-lock",
        "pid": 4712,
        "startup-lock-pid": 4711
    }
}

The status is starting, running or stopping, and the task shows what the instance is currently doing:

Task	Description
load-config	Load the configuration (status starting).
wait-startup-lock	Wait for the startup of another instance, which is shown as `startup-lock-pid` (status starting).
init-dpdk	Initialize DPDK (status starting).
init-protocols	Initialize IS-IS, OSPF and LDP (status starting).
init-interfaces	Initialize the interfaces (status starting).
init-bgp	Initialize the BGP sessions (status starting).
init-streams	Initialize the traffic streams (status starting).
init-sessions	Initialize the access sessions (status starting).
start-threads	Select the CPUs and start the I/O threads (status starting).
resolve-gateways	Wait for the gateways of the network interfaces to be resolved (status running).
running	Test is running (status running).
teardown	Teardown of sessions and protocols (status stopping).
stop-threads	Stop the I/O threads (status stopping).
reports	Generate the final reports (status stopping).
cleanup	Restore the interface configuration and release all resources (status stopping).

The state (init, active or teardown) is kept for compatibility, where init lasts until all gateways are resolved.

$ sudo bngblaster-cli run.sock threads

{
    "status": "ok",
    "code": 200,
    "threads": [
        {
            "name": "main",
            "type": "main",
            "cpu": 2,
            "cpu-auto": true,
            "cpu-shared": false,
            "tid": 4712
        },
        {
            "name": "rx0-eth1",
            "type": "rx",
            "interface": "eth1",
            "cpu": 0,
            "cpu-auto": true,
            "cpu-shared": false,
            "tid": 4714
        }
    ]
}

The cpu is null for threads which are not pinned. cpu-auto shows whether the CPU was selected by the automatic CPU placement, and cpu-shared whether the CPU is shared with another thread of this or another instance. The tid is the Linux thread ID (e.g. for top -H or perf).

Interfaces

This is explained in detail in the interfaces section.

Command	Description
interfaces	List all interfaces with index.
access-interfaces	List all access interface functions.
access-protocol-stats	Display access interface protocol packet and timeout statistics as included in the final report (protocol-stats). Arguments: `interface`
network-interfaces	List all network interface functions.
a10nsp-interfaces	List all a10nsp interface functions.
lag-info	List all link aggregation (LAG) interfaces. Arguments: `interface`
interface-enable	Enable interface. Arguments: `interface` Mandatory
interface-disable	Disable interface. Arguments: `interface` Mandatory
interface-topology	Display NUMA node, local CPU set and I/O thread pinning (CPU, queue and state) per interface. Arguments: `interface`

The access protocol statistics include packet counters per protocol and timeout counters. The counter lcp-echo-timeout is incremented for each LCP echo request without response and lcp-echo-expired for each session terminated because all LCP echo requests (lcp keepalive-retry) remained without response.

$ sudo bngblaster-cli run.sock access-protocol-stats interface eth1

The interface topology command helps to verify NUMA locality and CPU pinning of the RX and TX threads configured with rx-cpuset, tx-cpuset, rx-auto-cpuset or tx-auto-cpuset. The queue is shown for DPDK and AF_XDP interfaces only.

$ sudo bngblaster-cli run.sock interface-topology interface eth1

interface: eth1
  io-mode: af_xdp
  numa-node: 0
  local-cpuset: [0, 1, 2, 3, 4, 5, 6, 7]
  rx-auto-cpuset: True
  rx-thread id=0 cpu=2 source=auto queue=0 active=True stopped=False
  rx-thread id=1 cpu=3 source=auto queue=1 active=True stopped=False
  tx-auto-cpuset: False
  tx-thread id=0 cpu=4 source=manual queue=0 active=True stopped=False

Sessions

Command	Description
session-info	Display session information. Arguments: `session-id` Mandatory `debug`
session-counters	Display session counters.
sessions-pending	List all sessions not established.
session-start session-stop	Start/stop sessions. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
session-restart	Restart sessions. The argument `reconnect-delay` is only applicable in combination with session reconnect enabled in the configuration. This argument delays the session reconnect by the defined amount of seconds. Arguments: `session-id` `session-group-id` (ignored if session-id is present) `reconnect-delay`
session-streams	Display session streams. Arguments: `session-id` Mandatory
session-traffic	Display session traffic statistics.
session-traffic-start session-traffic-stop	This command can be used to start or stop session-traffic flows. Arguments: `session-id` `session-group-id` (ignored if session-id is present) `direction` (upstream/downstream/both)
session-traffic-reset	Reset all session traffic streams. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
session-update	Update session configuration. Arguments: `session-id` Mandatory `username` update username `password` update password `agent-remote-id` update agent-remote-id `agent-circuit-id` update agent-circuit-id `ipv6-link-local` update ipv6-link-local
session-summary	Display session summary information. If `session-id` is present, only this session is returned. Otherwise the list `sessions` is used if present or the session range filtered by `session-group-id`. Arguments: `session-id` `sessions` list of session-ids, e.g. [1,2,3] `session-id-min` session range `session-id-max` `session-group-id`

PPP

This is explained in detail in the PPPoE section.

Command	Description
ipcp-open	Open IPCP. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
ipcp-close	Close IPCP. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
ip6cp-open	Open IP6CP. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
ip6cp-close	Close IP6CP. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
lcp-echo-request-ignore	Ignore LCP echo-request from BNG. This feature can be used to enforce LCP timeouts on the BNG. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
lcp-echo-request-accept	Accept LCP echo-request from BNG (restore default behavior). Arguments: `session-id` `session-group-id` (ignored if session-id is present)

L2TP

This is explained in detail in the L2TP section.

Command	Description
l2tp-tunnels	Display all L2TP tunnels.
l2tp-sessions	Display all matching L2TP sessions (LNS and LAC). Arguments: `tunnel-id` `session-id` L2TP session ID (only with `tunnel-id`)
l2tp-csurq	Send L2TP CSURQ. Arguments: `tunnel-id` Mandatory `sessions` list of remote session-id.
l2tp-tunnel-terminate	Terminate L2TP tunnel. Arguments: `tunnel-id` Mandatory `result-code` `error-code` `error-message`
l2tp-session-terminate	Terminate L2TP session. Arguments: `session-id` Mandatory `result-code` `error-code` `error-message` `disconnect-code` `disconnect-protocol` `disconnect-direction` `disconnect-message`
l2tp-lcp-restart	Restart LCP of an L2TP session terminated on the BNG Blaster LNS. Arguments: `session-id` Mandatory

The L2TP CSURQ command expects the local tunnel-id and a list of remote session-id for which a connect speed update is requested.

{
    "command": "l2tp-csurq",
    "arguments": {
        "tunnel-id": 1,
        "sessions": [
            1,
            2,
            3,
            4
        ]
    }
}

This command can be executed as shown below using the CLI tool.

$ sudo bngblaster-cli run.sock l2tp-csurq tunnel-id 1 sessions [1,2,3,4]

The L2TP session terminate command allows testing of result (RFC2661) and disconnect (RFC3145) codes.

$ sudo bngblaster-cli run.sock l2tp-session-terminate session-id 1 result-code 2 error-message "LCP request" disconnect-code 3 disconnect-message "LCP terminate request"

The L2TP LCP restart command lets the BNG Blaster LNS send a new LCP Configure-Request to the client of an established L2TP session, which forces LCP renegotiation, for example to test how the BNG behaves after proxy LCP. The session-id is the BNG Blaster session tunnelled to the BNG Blaster LNS.

$ sudo bngblaster-cli run.sock l2tp-lcp-restart session-id 1

IGMP

Command	Description
igmp-join	Join group. Arguments: `session-id` Mandatory `group` Mandatory `source1` first IGMPv3/SSM source address for the group. `source2` second IGMPv3/SSM source address for the group. `source3` third IGMPv3/SSM source address for the group.
igmp-join-iter	Join multiple groups over all sessions. Arguments: `group` Mandatory `group-iter` IPv4 address step used to iterate over multiple groups (e.g. `0.0.0.1`). Default: `0.0.0.1` `group-count` number of groups to iterate over. The groups are assigned round-robin to all sessions. `source1` first IGMPv3/SSM source address for the group. `source2` second IGMPv3/SSM source address for the group. `source3` third IGMPv3/SSM source address for the group.
igmp-leave	Leave group. Arguments: `session-id` Mandatory `group` Mandatory
igmp-leave-all	Leave all groups from all sessions.
igmp-info	Display group information. Arguments: `session-id` Mandatory
zapping-start	Start IGMP zapping test.
zapping-stop	Stop IGMP zapping test.
zapping-stats	Display IGMP zapping stats. Arguments: `reset`

DHCP

Command	Description
dhcp-start	Start DHCP client. Arguments: `session-id` `session-group-id` (ignored if session-id is present)
dhcp-stop	Stop DHCP client without sending a release message. Arguments: `session-id` `session-group-id` (ignored if session-id is present) `keep-address` remember last address (init-reboot)
dhcp-release	Stop DHCP client with sending release messages. Arguments: `session-id` `session-group-id` (ignored if session-id is present)

Traffic

Command

Description

traffic-start

traffic-stop

This command can be used to start or stop all traffic globally.
This command does not alter the current state of a traffic stream.
In example, if a stream has not been started or has been stopped,
it can’t be started with this command. Instead, this command acts
as a global block to control the transmission of traffic streams.

multicast-traffic-start

multicast-traffic-stop

This command can be used to start or stop all multicast traffic.
This includes auto generated multicast traffic and RAW streams
with multicast destination address.

Streams

This is explained in detail in the streams section.

Command	Description
stream-stats	Display stream traffic statistics.
stream-info	Display stream/flow information. Arguments: `flow-id` Mandatory `debug`
stream-summary	Display stream/flow summary information. Arguments: `flow-id` `flow-id-min` flow range `flow-id-max` `flows` list of flows (e.g. `[1,2,3]`) `session-id` `session-group-id` `name` stream name `interface` TX interface name `direction` [both(default), upstream, downstream] `verified-only` streams verified `bidirectional-verified-only` streams verified in both directions `pending-only` streams not verified
stream-reset	Reset all traffic streams except session-traffic.
stream-start stream-stop stream-stop-verified	This command can be used to start or stop traffic stream flows. This command applies to all flows except session-traffic and multicast. If you provide a specific `flow-id` or a list of `flows` as an argument, all other arguments are ignored. Use session-traffic-start/stop for session-traffic. The command stream-stop-verified works similarly to stream-stop but only verified streams will be stopped. This filter is not applied with `flow-id` or `flows`. Arguments: `flow-id` `flow-id-min` flow range `flow-id-max` `flows` list of flows (e.g. `[1,2,3]`) `session-id` `session-group-id` `name` stream name `interface` TX interface name `direction` [both(default), upstream, downstream] `verified-only` streams verified `bidirectional-verified-only` streams verified in both directions `pending-only` streams not verified
streams-pending	List flow-id of all pending (not verified) traffic streams.
stream-update	Update stream/flow configuration. Arguments: `flow-id` `flow-id-min` flow range `flow-id-max` `flows` list of flows (e.g. `[1,2,3]`) `session-id` `session-group-id` `name` stream name `interface` TX interface name `direction` [both(default), upstream, downstream] `verified-only` streams verified `bidirectional-verified-only` streams verified in both directions `pending-only` streams not verified `tcp-flags` [ack, fin, fin-ack, syn, syn-ack, rst, push, push-ack] `pps` Update the stream rate in packets per second.

ISIS

This is explained in detail in the ISIS section.

Command	Description
isis-adjacencies	Display ISIS adjacencies.
isis-database	Display ISIS database (LSDB). Arguments: `instance` Mandatory `level` Mandatory
isis-load-mrt	Load ISIS MRT file. Arguments: `instance` Mandatory `file` Mandatory
isis-lsp-update	Update ISIS LSP. Arguments: `instance` Mandatory `pdu` Mandatory
isis-lsp-purge	Purge ISIS LSP based on LSP identifier. Arguments: `instance` Mandatory `level` Mandatory `id` Mandatory LSP identifier
isis-lsp-flap	Flap ISIS LSP based on LSP identifier. Arguments: `instance` Mandatory `level` Mandatory `timer` Optional flap timer (default 30s) `id` Mandatory LSP identifier
isis-update-priority	Update ISIS interface priority. Arguments: `interface` Mandatory `level` Mandatory `priority` Mandatory priority (0-127)
isis-teardown	Teardown ISIS.

OSPF

This is explained in detail in the OSPF section.

Command	Description
ospf-interfaces	Display OSPF interfaces. Arguments: `instance` Mandatory
ospf-neighbors	Display OSPF neighbors. Arguments: `instance` Mandatory
ospf-database	Display OSPF database (LSDB). Arguments: `instance` Mandatory
ospf-load-mrt	Load OSPF MRT file. Arguments: `instance` Mandatory `file` Mandatory
ospf-lsa-update	Update OSPF LSA. Arguments: `instance` Mandatory `lsa` Mandatory list of hex-encoded LSAs
ospf-pdu-update	Update OSPF LSA from PDU. Arguments: `instance` Mandatory `pdu` Mandatory
ospf-teardown	Teardown OSPF.

BGP

This is explained in detail in the BGP section.

Command	Description
bgp-sessions	Display all matching BGP sessions. Arguments: `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`
bgp-disconnect	Disconnect all matching BGP sessions. Arguments: `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`
bgp-teardown	Teardown BGP.
bgp-raw-update-list	List all loaded BGP RAW update files.
bgp-raw-update	Update all matching BGP sessions. Arguments: `file` Mandatory path to BGP RAW update file. `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`
bgp-routes	Display learned IPv4/IPv6 routes of all matching BGP sessions with learn-routes enabled. Arguments: `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address` `family` Filter by family (ipv4-unicast, ipv6-unicast, ipv4-labeled-unicast, ipv6-labeled-unicast). `prefix` Filter by IPv4 or IPv6 prefix. `match` Prefix match (exact or longer). Default: exact
bgp-routes-stats	Display learned route counters of all matching BGP sessions. Arguments: `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`
bgp-evpn-routes	Display learned BGP EVPN routes of all matching BGP sessions with learn-routes enabled. Arguments: `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address` `route-type` Filter by route type (1-5). `rd` Filter by route distinguisher.

LDP

This is explained in detail in the LDP section.

Command	Description
ldp-adjacencies	Display all LDP adjacencies. Arguments: `ldp-instance-id`
ldp-sessions	Display all matching LDP sessions. Arguments: `ldp-instance-id` `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`
ldp-database	Display LDP database. Arguments: `ldp-instance-id` Mandatory
ldp-disconnect	Disconnect all matching LDP sessions. Arguments: `ldp-instance-id` `local-ipv4-address` `peer-ipv4-address`
ldp-teardown	Teardown LDP.
ldp-raw-update-list	List all loaded LDP RAW update files.
ldp-raw-update	Update all matching LDP sessions. Arguments: `file` Mandatory path to LDP RAW update file. `ldp-instance-id` `local-ipv4-address` `peer-ipv4-address` `local-ipv6-address` `peer-ipv6-address`

CFM

Command	Description
cfm-cc-start	Start EOAM CFM CC. Arguments: `session-id` `network-interface`
cfm-cc-stop	Stop EOAM CFM CC. Arguments: `session-id` `network-interface`
cfm-cc-rdi-on	Set EOAM CFM CC RDI. Arguments: `session-id` `network-interface`
cfm-cc-rdi-off	Unset EOAM CFM CC RDI. Arguments: `session-id` `network-interface`

Legal Interception (LI)

This is explained in detail in the Legal Interception (LI) section.

Command	Description
li-flows	List all LI flows with detailed statistics.

HTTP

This is explained in detail in the HTTP section.

Command	Description
http-clients	Display all HTTP client instances. Arguments: `session-id`
http-clients-start	Start all HTTP client instances. Arguments: `session-id`
http-clients-stop	Stop all HTTP client instances. Arguments: `session-id`

ICMP

This is explained in detail in the ICMP section.

Command	Description
icmp-clients	Display all ICMP client instances. Arguments: `session-id` `detail` include detailed results
icmp-clients-start	Start all ICMP client instances. Arguments: `session-id`
icmp-clients-stop	Stop all ICMP client instances. Arguments: `session-id`

ARP

Command	Description
arp-clients	Display all ARP client instances. Arguments: `session-id`
arp-clients-reset	Reset all ARP client instances. Arguments: `session-id`

PCAP

Command	Description
pcap-start	Start capturing using the specified PCAP file. If no file name is provided, the current PCAP file name remains in use. Arguments: `file` Path to the PCAP file to use for capture.
pcap-stop	Stop the capture and close the PCAP file.