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
    }
}

Interfaces

Attribute

Description

Mandatory Arguments

Optional Arguments

interfaces

List all interfaces with index

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-streams

Display session streams

session-id

terminate

Terminate session

session-id, reconnect-delay

The argument reconnect-delay is only applicable in combination with session-id and reconnect enabled in configuration. This argument allows to delay 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

group

source1, source2, source3

igmp-leave

Leave group

group

igmp-info

Display group information

zapping-start

Start IGMP zapping test

zapping-stop

Stop IGMP zapping test

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-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-teardown

Teardown ISIS

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

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