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 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 index and VLAN of the session. The interface index (ifindex) can be requested using the interfaces command or skipped. The first access interface is automatically used if the argument ifindex 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": {
        "ifindex": 10,
        "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
    }
}

Test

Attribute

Description

Mandatory Arguments

Optional Arguments

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

Attribute

Description

Mandatory Arguments

Optional Arguments

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

interface

interface-disable

Disable interface

interface

Sessions

Attribute

Description

Mandatory Arguments

Optional Arguments

session-info

Display session information

session-id

session-counters

Display session counters

sessions-pending

List all sessions not established

session-traffic

Display session traffic statistics

session-traffic-start

Enable/start session traffic

session-id

session-traffic-stop

Disable/stop session traffic

session-id

session-traffic-reset

Reset all session traffic streams

session-streams

Display session streams

session-id

session-start

Start session manually

session-id, session-group-id

session-stop

Stop sessions manually

session-id, session-group-id, reconnect-delay

session-restart

Restart sessions manually

session-id, session-group-id, reconnect-delay

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.

PPP

Attribute

Description

Mandatory Arguments

Optional Arguments

ipcp-open

Open IPCP

session-id

ipcp-close

Close IPCP

session-id

ip6cp-open

Open IP6CP

session-id

ip6cp-close

Close IP6CP

session-id

L2TP

Attribute

Description

Mandatory Arguments

Optional Arguments

l2tp-tunnels

Display all L2TP tunnels

l2tp-sessions

L2TP all matching sessions

tunnel-id, session-id

l2tp-csurq

Send L2TP CSURQ

tunnel-id

sessions (list of remote session-id)

l2tp-tunnel-terminate

Terminate L2TP tunnel

tunnel-id

result-code, error-code, error-message

l2tp-session-terminate

Terminate L2TP session

session-id

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

Attribute

Description

Mandatory Arguments

Optional Arguments

igmp-join

Join group

session-id, group

source1, source2, source3

igmp-join-iter

Join multiple groups over all sessions

group

group-iter, group-count, source1, source2, source3

igmp-leave

Leave group

session-id, group

igmp-leave-all

Leave all groups from all sessions

igmp-info

Display group information

session-id

zapping-start

Start IGMP zapping test

zapping-stop

Stop IGMP zapping test

zapping-stats

Return IGMP zapping stats

reset

Traffic

Attribute

Description

Mandatory Arguments

Optional Arguments

traffic-start

Start all traffic (session and streams)

traffic-stop

Stop all traffic (session and streams)

multicast-traffic-start

Start multicast traffic

multicast-traffic-stop

Stop multicast traffic

Streams

Attribute

Description

Mandatory Arguments

Optional Arguments

stream-stats

Display stream traffic statistics

stream-info

Display stream/flow information

flow-id

stream-summary

Display stream/flow summary information

stream-traffic-start

Enable/start traffic streams

session-id

stream-traffic-stop

Disable/stop traffic streams

session-id

stream-reset

Reset all traffic streams

ISIS

Attribute

Description

Mandatory Arguments

Optional Arguments

isis-adjacencies

Display ISIS adjacencies

isis-database

Display ISIS database (LSDB)

instance, level

isis-load-mrt

Load ISIS MRT file

instance, file

isis-lsp-update

Update ISIS LSP

instance, pdu

isis-lsp-purge

Purge ISIS LSP based on LSP identifier

instance, level, id

isis-lsp-flap

Flap ISIS LSP based on LSP identifier

instance, level, id

timer

isis-teardown

Teardown ISIS

OSPF

Attribute

Description

Mandatory Arguments

Optional Arguments

ospf-interfaces

Display OSPF interfaces

instance

ospf-neighbors

Display OSPF neighbors

instance

ospf-database

Display OSPF database (LSDB)

instance

ospf-load-mrt

Load OSPF MRT file

instance, file

ospf-lsa-update

Update OSPF LSA

instance, pdu

ospf-pdu-update

Update OSPF LSA from PDU

instance,

ospf-teardown

Teardown OSPF

BGP

Attribute

Description

Mandatory Arguments

Optional Arguments

bgp-sessions

Display all matching BGP sessions

local-ipv4-address, peer-ipv4-address

bgp-disconnect

Disconnect all matching BGP sessions

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 session

file

local-ipv4-address, peer-ipv4-address

LDP

Attribute

Description

Mandatory Arguments

Optional Arguments

ldp-adjacencies

Display all LDP adjacencies

ldp-instance-id

ldp-sessions

Display all matching LDP sessions

ldp-instance-id, local-ipv4-address, peer-ipv4-address

ldp-database

Display LDP database

ldp-instance-id

ldp-disconnect

Disconnect all matching LDP sessions

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

file

ldp-instance-id, local-ipv4-address, peer-ipv4-address

CFM

Attribute

Description

Mandatory Arguments

Optional Arguments

cfm-cc-start

Start EOAM CFM CC

session-id

cfm-cc-stop

Stop EOAM CFM CC

session-id

cfm-cc-rdi-on

Set EOAM CFM CC RDI

session-id

cfm-cc-rdi-off

Unset EOAM CFM CC RDI

session-id

HTTP

This is explained detailed in the HTTP section.

Attribute

Description

Mandatory Arguments

Optional Arguments

http-clients

Display all HTTP client instances

session-id

http-clients-start

Start all HTTP client instances

session-id

http-clients-stop

Stop all HTTP client instances

session-id