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

ICMP

This is explained detailed in the ICMP section.

Command	Description
icmp-clients	Display all ICMP client instances. Arguments: session-id
icmp-clients-start	Start all ICMP client instances. Arguments: session-id
icmp-clients-stop	Stop all ICMP client instances. Arguments: session-id