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 but it can be also 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>"
    }
}

Following an example RPC request with 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 request was successfully. The status can be also set to warning or error with corresponding error code and an optional error message.

$ cat command.json | sudo nc -U test.socket | 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. In example if 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 last 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 Control Socket Client

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

Examples:
    bngblaster-cli run.sock session-info session-id 1
    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]

$ 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 running test instance.
test-stop	Stop/teardown the test.
terminate	Stop/teardown the test.
monkey-start	Start monkey test.
monkey-stop	Stop monkey test.

Interfaces

This is explained detailed in the interfaces section.

Command	Description
interfaces	List all interfaces with index.
access-interfaces	List all access interface functions.
network-interfaces	List all network interface functions.
a10nsp-interfaces	List all a10nsp interface functions.
lag-info	List all link aggregation (LAG) interfaces.
interface-enable	Enable interface. Arguments: `interface` Mandatory
interface-disable	Disable interface. Arguments: `interface` Mandatory

Sessions

Command	Description
session-info	Display session information. Arguments: `session-id`
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)

PPP

This is explained detailed 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 detailed in the L2TP section.

Command	Description
l2tp-tunnels	Display all L2TP tunnels.
l2tp-sessions	L2TP all matching sessions. Arguments: `tunnel-id` `session-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`

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 to test 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"

IGMP

Command	Description
igmp-join	Join group. Arguments: `session-id` Mandatory `group` Mandatory `source1` `source2` `source3`
igmp-join-iter	Join multiple groups over all sessions. Arguments: `group` Mandatory `group-iter` `group-count` `source1` `source2` `source3`
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	Return IGMP zapping stats. Arguments: `reset`

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 detailed in the streams section.

Command	Description
stream-stats	Display stream traffic statistics.
stream-info	Display stream/flow information. Arguments: `flow-id`
stream-summary	Display stream/flow summary information. Arguments: `session-group-id` `name` stream name `interface` TX interface name `direction` [both(default), upstream, downstream]
stream-reset	Reset all traffic streams.
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` as an argument, other arguments are ignored. In this particular case, you can also start and stop session-traffic and multicast. The command stream-stop-verified works similar to stream-stop but only verified streams will be stopped. Arguments: `flow-id` `session-id` `session-group-id` (ignored if session-id is present) `name` stream name `interface` TX interface name `direction` [both(default), upstream, downstream]
streams-pending	List flow-id of all pending (not verified) traffic streams.
stream-update	Update stream/flow configuration. Arguments: `flow-id` `tcp-flags` [ack, fin, fin-ack, syn, syn-ack, rst]

ISIS

This is explained detailed 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 detailed 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 `pdu` Mandatory `lsa` Mandatory LSA identifier
ospf-pdu-update	Update OSPF LSA from PDU. Arguments: `instance` Mandatory `pdu` Mandatory
ospf-teardown	Teardown OSPF.

BGP

This is explained detailed in the BGP section.

Command	Description
bgp-sessions	Display all matching BGP sessions. Arguments: `local-ipv4-address` `peer-ipv4-address`
bgp-disconnect	Disconnect all matching BGP sessions. Arguments: `local-ipv4-address` `peer-ipv4-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`

LDP

This is explained detailed 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`
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 session. Arguments: `file` Mandatory `ldp-instance-id` `local-ipv4-address` `peer-ipv4-address`

CFM

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

Legal Interception (LI)

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

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

HTTP

This is explained detailed 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`