diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..2246c49f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,24 @@ +# Makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = . + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +github: + @make html + @cp -a _build/html/. . + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 9273c4a9..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1,4 +0,0 @@ -title: RtBrick BNG Blaster -description: The BNG Blaster is a test tool to simulate thousands of PPPoE or IPoE subscribers including IPTV, traffic verification and convergence testing capabilities. -logo: images/rtbrick_logo.png -theme: jekyll-theme-minimal diff --git a/docs/a10nsp.md b/docs/a10nsp.md deleted file mode 100644 index bdab7fcb..00000000 --- a/docs/a10nsp.md +++ /dev/null @@ -1,74 +0,0 @@ -# A10NSP - -The A10NSP interface emulates an layer two provider interface. The term A10 -refers to the end-to-end ADSL network reference model from TR-025. - -Following a basic PPPoE/A10NSP configuration example which is -detailed explained in the configuration section. - -```json -{ - "interfaces": { - "rx-interval": 1, - "a10nsp": [ - { - "interface": "eth4", - "qinq": true, - "mac": "02:00:00:ff:ff:01" - }, - { - "interface": "eth5", - "qinq": true, - "mac": "02:00:00:ff:ff:01" - } - ], - "access": [ - { - "__comment__": "PPPoE", - "interface": "eth1", - "type": "pppoe", - "outer-vlan-min": 1, - "outer-vlan-max": 4000, - "inner-vlan": 7, - "stream-group-id": 1 - } - ] - }, - "pppoe": { - "reconnect": true, - "discovery-timeout": 3, - "discovery-retry": 10, - "host-uniq": true, - "vlan-priority": 6 - }, - "dhcpv6": { - "enable": false - }, - "session-traffic": { - "autostart": true, - "ipv4-pps": 10 - }, - "streams": [ - { - "stream-group-id": 2, - "name": "PPPOE-S1", - "type": "ipv4", - "direction": "both", - "priority": 128, - "length": 256, - "pps": 10, - "a10nsp-interface": "eth4" - }, - { - "stream-group-id": 2, - "name": "PPPOE-S2", - "type": "ipv4", - "direction": "both", - "priority": 128, - "length": 256, - "pps": 10, - "a10nsp-interface": "eth5" - } - ] -} -``` diff --git a/docs/bgp.md b/docs/bgp.md deleted file mode 100644 index e58ec2a7..00000000 --- a/docs/bgp.md +++ /dev/null @@ -1,170 +0,0 @@ -# BGP - -The Border Gateway Protocol (BGP) is a standardized exterior gateway protocol -designed to exchange routing and reachability information among autonomous systems -(AS) on the internet. BGP is classified as a path-vector routing protocol, and it -makes routing decisions based on paths, network policies, or rule-sets configured -by a network operator. - -Following an example BGP configuration with one session. - -```json -{ - "interfaces": { - "network": [ - { - "interface": "eth1", - "address": "10.0.1.2/24", - "gateway": "10.0.1.1" - } - ] - }, - "bgp": [ - { - "local-ipv4-address": "10.0.1.2", - "peer-ipv4-address": "10.0.1.1", - "raw-update-file": "test.bgp", - "local-as": 65001, - "peer-as": 65001 - } - ] -} -``` - -## BGP Sessions - -Every BGP session is opened with the capabilities for the following -address families: - -+ IPv4 unicast -+ IPv4 labelled unicast -+ IPv6 unicast -+ IPv6 labelled unicast - -## Limitations - -BGP authentication is currently not supported but already -planned as enhancement in one of the next releases. - -## RAW Update Files - -The BNG Blaster is able to inject BGP messages from a pre-compiled -RAW update file into the defined sessions. A RAW update file is not -more than a pre-compiled binary stream of BGP messages, typically -but not limited to update messages. - -```text - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - + + - | | - + + - | Marker | - + + - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length | Type | ... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++++ - . - . - . - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - + + - | | - + + - | Marker | - + + - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length | Type | ... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++++ -``` - -Those files can be created using the included BGP RAW update generator -script `bgpupdate` or manually using libraries like scapy or converters -from PCAP or MRT files. - -The configured `raw-update-file` under the BGP session is loaded -during Blaster startup phase and send as soon as the session is -established. - -The `bgp-raw-update` command allows to send further updates during -the session lifetime. - -`$ sudo bngblaster-cli run.sock bgp-raw-update file update1.bgp` - -This allows in example to load a full table after session has -started and manually trigger a series of changes using incremental -updates files. - -All BGP RAW update files are loaded once and can than be used by -multiple sessions. Meaning if two or more sessions reference the -same file identified by file name, this file is loaded once into -memory and used by multiple sessions. - -Therefore for incremental updates, it may makes sense to pre-load -via `bgp-raw-update-files` configuration. - -```json -{ - "bgp": [ - { - "local-ipv4-address": "10.0.1.2", - "peer-ipv4-address": "10.0.1.1", - "raw-update-file": "start.bgp", - "local-as": 65001, - "peer-as": 65001 - } - ], - "bgp-raw-update-files": [ - "update1.bgp", - "update2.bgp" - ] -} -``` - -Incremental updates not listed here will be loaded dynamically as soon -as referenced by first session. - -## BGP RAW Update Generator - -The BGP RAW update generator is a simple tool to generate BGP RAW update -streams for use with the BNG Blaster. - -```text -$ bgpupdate --help -usage: bgpupdate [-h] [-a ASN] -n ADDRESS [-N N] -p PREFIX [-P N] [-m LABEL] - [-M N] [-l LOCAL_PREF] [-f FILE] [-w] [--end-of-rib] - [--append] [--pcap FILE] [--log-level {warning,info,debug}] - -optional arguments: - -h, --help show this help message and exit - -a ASN, --asn ASN autonomous system number - -n ADDRESS, --next-hop-base ADDRESS - next-hop base address (IPv4 or IPv6) - -N N, --next-hop-num N - next-hop count - -p PREFIX, --prefix-base PREFIX - prefix base network (IPv4 or IPv6) - -P N, --prefix-num N prefix count - -m LABEL, --label-base LABEL - label base - -M N, --label-num N label count - -l LOCAL_PREF, --local-pref LOCAL_PREF - local preference - -f FILE, --file FILE output file - -w, --withdraw withdraw prefixes - --end-of-rib add end-of-rib message - --append append to file if exist - --pcap FILE write BGP updates to PCAP file - --log-level {warning,info,debug} - logging Level -``` - -The python BGP RAW update generator is a python script which uses -scapy to build BGP messages. Therefore this tool can be easily -modified, extend or used as blueprint for your own tools to generate -valid BGP update streams. diff --git a/docs/config.md b/docs/config.md deleted file mode 100644 index ad2c6c8f..00000000 --- a/docs/config.md +++ /dev/null @@ -1,950 +0,0 @@ -# Configuration - -Following an example configuration file which is explained in detail below. - -```json -{ - "interfaces": { - "network": { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2", - "address-ipv6": "fc66:1337:7331::1", - "gateway-ipv6": "fc66:1337:7331::2" - }, - "access": [ - { - "interface": "eth1", - "outer-vlan-min": 1000, - "outer-vlan-max": 1999, - "inner-vlan-min": 1, - "inner-vlan-max": 4049, - "authentication-protocol": "PAP" - }, - { - "interface": "eth1", - "outer-vlan-min": 2000, - "outer-vlan-max": 2999, - "inner-vlan-min": 1, - "inner-vlan-max": 4049, - "authentication-protocol": "CHAP" - } - ] - }, - "sessions": { - "count": 1000, - "session-time": 0, - "max-outstanding": 800, - "start-rate": 400, - "stop-rate": 400 - }, - "pppoe": { - "reconnect": true, - "discovery-timeout": 3, - "discovery-retry": 10 - }, - "ppp": { - "mru": 1492, - "authentication": { - "username": "user{session-global}@rtbrick.com", - "password": "test", - "timeout": 5, - "retry": 30 - }, - "lcp": { - "conf-request-timeout": 1, - "conf-request-retry": 10, - "keepalive-interval": 30, - "keepalive-retry": 3 - }, - "ipcp": { - "enable": true, - "request-ip": true, - "request-dns1": true, - "request-dns2": true, - "conf-request-timeout": 1, - "conf-request-retry": 10 - }, - "ip6cp": { - "enable": true, - "conf-request-timeout": 1, - "conf-request-retry": 10 - } - }, - "dhcpv6": { - "enable": true, - "rapid-commit": true - }, - "access-line": { - "agent-remote-id": "DEU.RTBRICK.{session-global}", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}", - "rate-up": 1024, - "rate-down": 16384 - }, - "session-traffic": { - "ipv4-pps": 1, - "ipv6-pps": 1, - "ipv6pd-pps": 1 - } -} -``` - -## Interfaces - -This section describes all attributes of the `interfaces` hierarchy -which allows to modify how to send and receive traffic. - -```json -{ - "interfaces": { - "tx-interval": 0.1, - "rx-interval": 0.1, - "io-slots": 2048, - } -} -``` - -Attribute | Description | Default ---------- | ----------- | ------- -`tx-interval` | TX ring polling interval in milliseconds | 5.0 -`rx-interval` | RX ring polling interval in milliseconds | 5.0 -`qdisc-bypass` | Bypass the kernel's qdisc layer | true -`io-mode` | IO mode | packet_mmap_raw -`io-slots` | IO slots (ring size) | 1024 -`io-stream-max-ppi` | IO traffic stream max packets per interval | 32 -`capture-include-streams` | Include traffic streams in capture | true - -The `tx-interval` and `rx-interval` should be set to at to at least `1.0` (1ms) -if more precise timestamps are needed. This is recommended for IGMP join/leave -or QoS delay measurements. For higher packet rates (>1g) it might be needed to -increase the `io-slots` from the default value of `1024` to `2048` or more. - -The supported IO modes are listed with `bngblaster -v` but except -`packet_mmap_raw` all other modes are currently considered as experimental. In -the default mode (`packet_mmap_raw`) all packets are received in a Packet MMAP -ring buffer and send directly trough RAW packet sockets. - -**WARNING**: Disable `qdisc-bypass` only if BNG Blaster is not sending traffic! - -The interfaces used in BNG Blaster do not need IP addresses configured in the host -operating system but they need to be in up state. - -```cli -sudo ip link set dev up -``` - -It is not possible to send packets larger than the interface MTU which is 1500 per default -but for PPPoE with multiple VLAN headers this might be not enough for large packets. -Therefore the interface MTU should be increased using the following commands. - -```cli -sudo ip link set mtu 9000 dev -``` - -This can be also archived via netplan using the following configuration for each BNG Blaster -interface. - -```yaml -network: - version: 2 - renderer: networkd - ethernets: - eth1: - dhcp4: no - dhcp6: no - link-local: [] - mtu: 9000 - eth2: - dhcp4: no - dhcp6: no - link-local: [] - mtu: 9000 -``` - -The number of interfaces is currently limited to 32! - -### Network Interface - -`"interfaces": { "network": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`interface` | Network interface name (e.g. eth0, ...) -`address` | Local network interface IPv4 address -`gateway` | Gateway network interface IPv4 address -`address-ipv6` | Local network interface IPv6 address (implicitly /64) | - -`gateway-ipv6` | Gateway network interface IPv6 address (implicitly /64) -`vlan` | Network interface VLAN | 0 (untagged) -`gateway-mac`| Optional set gateway MAC address manually -`gateway-resolve-wait` | Sessions will not start until gateways are resolved | true -`isis-instance-id` | Assign interface to ISIS instance | - -`isis-level` | ISIS interface level | 3 -`isis-p2p` | ISIS P2P interface | true -`isis-l1-metric` | ISIS level 1 interface metric | 10 -`isis-l2-metric` | ISIS level 2 interface metric | 10 - -The BNG Blaster supports also multiple network interfaces -or VLAN ranges as shown in the example below. - -```json -{ - "interfaces": { - "tx-interval": 1, - "rx-interval": 1, - "io-slots": 4096, - "network": [ - { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2", - "address-ipv6": "fc66:1337:7331::1", - "gateway-ipv6": "fc66:1337:7331::2" - }, - { - "interface": "eth3", - "address": "10.0.1.1", - "gateway": "10.0.1.2", - "address-ipv6": "fc66:1337:7331:1::1", - "gateway-ipv6": "fc66:1337:7331:1::2" - } - ], - } -} -``` - -Using multiple network interfaces requires to select which network interface -to be used otherwise one of the interface is selected automatically. Therefore -the option `network-interface` is supported in different sections. - -### Access Interfaces - -`"interfaces": { "access": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`interface` | Access interface name (e.g. eth0, ...) -`network-interface` | Select the corresponding network interface for this session | -`type` | Switch the access type between `pppoe` (PPP over Ethernet) and `ipoe` (IP over Ethernet) | pppoe -`vlan-mode` | Set VLAN mode `1:1` or `N:1` | 1:1 -`qinq` | Set outer VLAN ethertype to QinQ (0x88a8) | false -`outer-vlan-min` | Outer VLAN minimum value | 0 (untagged) -`outer-vlan-max` | Outer VLAN maximum value | 0 (untagged) -`outer-vlan` |Set outer-vlan-min/max equally -`inner-vlan-min` | Inner VLAN minimum value | 0 (untagged) -`inner-vlan-max` | Inner VLAN maximum value | 0 (untagged) -`inner-vlan` |Set inner-vlan-min/max equally -`third-vlan` | Add a fixed third VLAN (most inner VLAN) as required for some lab environments | 0 (untagged) -`address` | Static IPv4 base address (IPoE only) -`address-iter` | Static IPv4 base address iterator (IPoE only) -`gateway` | Static IPv4 gateway address (IPoE only) -`gateway-iter` | Static IPv4 gateway address iterator (IPoE only) -`username` | Optionally overwrite the username from authentication section per access configuration -`password` | Optionally overwrite the password from authentication section per access configuration -`authentication-protocol` | Optionally overwrite the username from authentication section per access configuration -`agent-circuit-id` | Optionally overwrite the agent-circuit-id from access-line section per access configuration -`agent-remote-id` | Optionally overwrite the agent-remote-id from access-line section per access configuration -`rate-up` | Optionally overwrite the rate-up from access-line section per access configuration -`rate-down` | Optionally overwrite the rate-down from access-line section per access configuration -`dsl-type` | Optionally overwrite the dsl-type from access-line section per access configuration -`ipcp` | Optionally enable/disable PPP IPCP per access configuration -`ip6cp` | Optionally enable/disable PPP IP6CP per access configuration -`ipv4` | Optionally enable/disable IPoE IPv4 per access configuration -`ipv6` | Optionally enable/disable IPoE IPv6 per access configuration -`dhcp` | Optionally enable/disable DHCP per access configuration -`dhcpv6` | Optionally enable/disable DHCPv6 per access configuration -`igmp-autostart` | Optionally overwrite IGMP autostart per access configuration -`igmp-version` | Optionally overwrite IGMP protocol version (1, 2 or 3) per access configuration -`stream-group-id` | Optional stream group identifier -`access-line-profile-id` | Optional access-line-profile identifier -`cfm-cc` | Optionally enable/disable EOAM CFM CC (IPoE only) | false -`cfm-level` | Set EOAM CFM maintenance domain level | 0 -`cfm-ma-id` | Set EOAM CFM maintenance association identifier | 0 -`cfm-ma-name` | Set EOAM CFM maintenance association short name -`i1-start` | Iterator for usage in strings `{i1}` | 1 -`i1-step` | Iterator step per session | 1 -`i2-start` | Iterator for usage in strings `{i2}` | 1 -`i2-step` | Iterator step per session | 1 - -For all modes it is possible to configure between zero and three VLAN -tags on the access interface as shown below. - -```text -[ethernet][outer-vlan][inner-vlan][third-vlan][pppoe]... -``` - -#### Untagged - -With untagged only one session is possible. - -```json -{ - "access": { - "interface": "eth1", - "outer-vlan-min": 0, - "outer-vlan-max": 0, - "inner-vlan-min": 0, - "inner-vlan-max": 0 - } -} -``` - -#### Single Tagged - -```json -{ - "access": { - "interface": "eth1", - "outer-vlan-min": 1, - "outer-vlan-max": 4049, - "inner-vlan-min": 0, - "inner-vlan-max": 0 - } -} -``` - -#### Double Tagged - -```json -{ - "access": { - "interface": "eth1", - "outer-vlan-min": 1, - "outer-vlan-max": 4049, - "inner-vlan-min": 7, - "inner-vlan-max": 7 - } -} -``` - -#### Triple Tagged - -```json -{ - "access": { - "interface": "eth1", - "outer-vlan-min": 10, - "outer-vlan-max": 20, - "inner-vlan-min": 128, - "inner-vlan-max": 4000, - "third-vlan": 7 - } -} -``` - -The BNG Blaster supports also multiple access interfaces -or VLAN ranges as shown in the example below. - -```json -{ - "access": [ - { - "interface": "eth1", - "type": "pppoe", - "username": "pta@rtbrick.com", - "outer-vlan-min": 1000, - "outer-vlan-max": 1999, - "inner-vlan-min": 7, - "inner-vlan-max": 7 - }, - { - "interface": "eth1", - "type": "pppoe", - "username": "l2tp@rtbrick.com", - "outer-vlan-min": 2000, - "outer-vlan-max": 2999, - "inner-vlan-min": 7, - "inner-vlan-max": 7 - }, - { - "interface": "eth3", - "type": "pppoe", - "username": "test@rtbrick.com", - "outer-vlan-min": 128, - "outer-vlan-max": 4000, - "inner-vlan-min": 7, - "inner-vlan-max": 7 - }, - { - "interface": "eth4", - "type": "ipoe", - "outer-vlan-min": 8, - "outer-vlan-max": 9, - "address": "200.0.0.1", - "address-iter": "0.0.0.4", - "gateway": "200.0.0.2", - "gateway-iter": "0.0.0.4" - } - ] -} -``` - -Both network and access interfaces are optional but obviously at least -one interface is required to start the BNG Blaster. - -The configuration attributes for username, agent-remote-id and agent-circuit-id -support also some variable substitution. The variable `{session-global}` will -be replaced with a number starting from 1 and incremented for every new session. -where as the variable `{session}` is incremented per interface section. - -In VLAN mode `N:1` only one VLAN combination is supported per access interface section. -This means that only VLAN min or max is considered as VLAN identifier. - -```json -{ - "access": [ - { - "interface": "eth1", - "type": "pppoe", - "vlan-mode": "N:1", - "username": "test@rtbrick.com", - "outer-vlan-min": 7 - }, - { - "interface": "eth2", - "type": "pppoe", - "vlan-mode": "N:1", - "username": "test@rtbrick.com", - "outer-vlan-min": 2000, - "inner-vlan-min": 7, - }, - ] -} -``` - -### A10NSP Interface - -`"interfaces": { "a10nsp": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`interface` | A10nSP interface name (e.g. eth0, ...) -`qinq` | Set outer VLAN ethertype to QinQ (0x88a8) | false -`mac`| Optional set gateway interface address manually - -The BNG Blaster supports also multiple A10NSP interfaces -as shown in the example below. - -```json -{ - "interfaces": { - "tx-interval": 1, - "rx-interval": 1, - "a10nsp": [ - { - "interface": "eth4", - "qinq": true, - "mac": "02:00:00:ff:ff:01" - }, - { - "interface": "eth5", - "qinq": false, - "mac": "02:00:00:ff:ff:02" - } - ], - } -} -``` - -## Sessions - -This section describes all attributes of the `sessions` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`count` | Sessions (PPPoE + IPoE) | 1 -`max-outstanding` | Max outstanding sessions | 800 -`start-rate` | Setup request rate in sessions per second | 400 -`stop-rate` | Teardown request rate in sessions per second | 400 -`iterate-vlan-outer` | Iterate on outer VLAN first | false -`start-delay` | Wait N seconds after all interface are resolved before starting sessions | 0 - -Per default sessions are created by iteration over inner VLAN range first and outer VLAN second. -Which can be changed by `iterate-vlan-outer` to iterate on outer VLAN first and inner VLAN second. - -Therefore the following configuration generates the sessions on VLAN (outer:inner) 1:3, 1:4, 2:3, 2:4 per default or alternative 1:3, 2:3, 1:4, 2:4 with `iterate-vlan-outer` enabled. - -```json -{ - "outer-vlan-min": 1, - "outer-vlan-max": 2, - "inner-vlan-min": 3, - "inner-vlan-max": 4 -} -``` - -## IPoE - -This section describes all attributes of the `ipoe` (IP over Ethernet) hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`ipv4` | Enable/disable IPv4 | true (enabled) -`arp-timeout` | Initial ARP resolve timeout/retry interval in seconds | 1 -`arp-interval` | Periodic ARP interval in seconds (0 means disabled) | 300 -`ipv6` | Enable/disable IPv6 | true (enabled) - -## PPPoE - -This section describes all attributes of the `pppoe` (PPP over Ethernet) hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`session-time` | Max PPPoE session time in seconds | 0 (infinity) -`reconnect` | Automatically reconnect sessions if terminated | false -`discovery-timeout` | PPPoE discovery (PADI and PADR) timeout in seconds | 5 -`discovery-retry` | PPPoE discovery (PADI and PADR) max retry | 10 -`service-name` | PPPoE discovery service name | -`host-uniq` | PPPoE discovery host-uniq | false -`vlan-priority` | VLAN PBIT for all PPPoE/PPP control traffic | 0 - -## PPP - -This section describes all attributes of the `ppp` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`mru` | Define the maximum receive unit proposed via PPP | 1492 - -### PPP Authentication - -`"ppp": { "authentication": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`username` | Username | user{session-global}@rtbrick.com -`password` |Password | test -`timeout` | Authentication request timeout in seconds | 5 -`retry` | Authentication request max retry | 30 -`protocol` | This value can be set to `PAP` or `CHAP` to reject the other protocol | allow PAP and CHAP - -### PPP LCP - -`"ppp": { "lcp": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`conf-request-timeout` | LCP configuration request timeout in seconds | 5 -`conf-request-retry` | LCP configuration request max retry | 10 -`keepalive-interval` | LCP echo request interval in seconds (0 means disabled) | 30 -`keepalive-retry` | PPP LCP echo request max retry | 3 -`start-delay` | PPP LCP initial request delay in milliseconds | 0 -`ignore-vendor-specific` | Ignore LCP vendor specific requests | false -`connection-status-message` | Accept LCP connection status messages | false - -### PPP IPCP - -`"ppp": { "ipcp": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`enable` | This option allows to enable or disable the IPCP protocol | true -`request-ip` | Include IP-Address with 0.0.0.0 in initial LCP configuration request | true -`request-dns1` | Request Primary DNS Server Address (option 129) | true -`request-dns2` | Request Secondary DNS Server Address (option 131) | true -`conf-request-timeout` | IPCP configuration request timeout in seconds | 5 -`conf-request-retry` | IPCP configuration request max retry | 10 - -### PPP IP6CP - -`"ppp": { "ipcp": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`enable` | This option allows to enable or disable the IP6CP protocol | true -`conf-request-timeout` | IP6CP configuration request timeout in seconds | 5 -`conf-request-retry` | IP6CP configuration request max retry | 10 - -## DHCP - -This section describes all attributes of the `dhcp` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`enable` | This option allows to enable or disable DHCP | false -`broadcast` | DHCP broadcast flag | false -`timeout` | DHCP timeout in seconds | 5 -`retry` | DHCP retry | 10 -`release-interval` | DHCP release interval | 1 -`release-retry` | DHCP release retry | 3 -`tos` | IPv4 TOS for all DHCP control traffic | 0 -`vlan-priority` | VLAN PBIT for all DHCP control traffic | 0 - -## DHCPv6 - -This section describes all attributes of the `dhcpv6` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`enable` | This option allows to enable or disable DHCPv6 | true -`rapid-commit` | DHCPv6 rapid commit (2 way handshake) | true -`timeout` | DHCPv6 timeout in seconds | 5 -`retry` | DHCPv6 retry | 10 - -## IGMP - -This section describes all attributes of the `igmp` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`autostart` | Automatically join after session is established | true -`version` | IGMP protocol version (1, 2 or 3) | 3 -`combined-leave-join` | Combine leave and join records within a single IGMPv3 report | true -`start-delay` | Delay between session established and initial IGMP join in seconds | 1 -`group` | Multicast group base address (e.g. 239.0.0.1) | 0.0.0.0 (disabled) -`group-iter` | Multicast group iterator | 0.0.0.1 -`group-count` | Multicast group count | 1 -`source` | Multicast source address (e.g. 1.1.1.1) | 0.0.0.0 (ASM) -`zapping-interval` | IGMP channel zapping interval in seconds | 0 (disabled) -`zapping-count` | Define the amount of channel changes before starting view duration | 0 (disabled) -`view-duration` | Define the view duration in seconds | 0 (disabled) -`send-multicast-traffic` | Generate multicast traffic | false -`multicast-traffic-length` | Multicast traffic IP length | 76 -`multicast-traffic-tos` | Multicast traffic TOS priority | 0 -`network-interface` | Multicast traffic source interface | - -Per default join and leave requests are send using dedicated reports. The option `combined-leave-join` allows -the combination of leave and join records within a single IGMPv3 report using multiple group records. -This option is applicable to IGMP version 3 only! - -If `send-multicast-traffic` is true, the BNG Blaster generates multicast traffic on the network interface -based on the specified group and source attributes mentioned before. This traffic includes some special -signatures for faster processing and more detailed analysis. - -If group is set to 293.0.0.1 with group-iter of 0.0.0.2, source 1.1.1.1 and group-count 3 the result are the following -three groups (S.G) 1.1.1.1,239.0.0.1, 1.1.1.1,239.0.0.3 and 1.1.1.1,239.0.0.5. - -## L2TP Server (LNS) - -This section describes all attributes of the `l2tp-server` (LNS) hierarchy -as explained in [L2TPv2](l2tp). - -The BNG Blaster supports multiple L2TPv2 servers (LNS) over the network interface -as shown in the example below. - -```json -{ - "interfaces": { - "network": { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2" - } - }, - "l2tp-server": [ - { - "name": "LNS1", - "address": "10.0.0.10", - "secret": "test1", - }, - { - "name": "LNS2", - "address": "10.0.0.11", - "secret": "test2", - }, - ] -} -``` - -There is actually no hard limit in the amount of L2TP servers. - -Attribute | Description | Default ---------- | ----------- | ------- -`name` | Mandatory L2TP LNS server hostname (AVP 7) | -`address` | Mandatory L2TP server address | -`secret` | Tunnel secret | -`receive-window-size` | Control messages receive window size | 4 -`max-retry` | Control messages max retry | 30 -`congestion-mode` | Control messages congestion mode | default -`data-control-priority` | Set the priority bit in the L2TP header for all non-IP data packets (LCP, IPCP, ...) | false -`data-length` | Set length bit for all data packets | false -`data-offset` | Set offset bit with offset zero for all data packets | false -`control-tos` | L2TP control traffic (SCCRQ, ICRQ, ...) TOS priority | 0 -`data-control-tos` | Set the L2TP tunnel TOS priority (outer IPv4 header) for all non-IP data packets (LCP, IPCP, ...) | 0 - -The BNG Blaster supports different congestion modes for the -reliable delivery of control messages. The `default` mode -is described in RFC2661 appendix A (Control Channel Slow Start and -Congestion Avoidance). The mode `slow` uses a fixed control window -size of 1 where `aggressive` sticks to max permitted based on peer -received window size. - -## Traffic - -This section describes all attributes of the `traffic` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`autostart` | Automatically start traffic | true -`stop-verified` | Automatically stop traffic streams if verified | false - -## Session Traffic - -This section describes all attributes of the `session-traffic` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`autostart` | Automatically start session traffic after session is established | true -`ipv4-pps` | Generate bidirectional IPv4 traffic between network interface and all session framed IPv4 addresses | 0 (disabled) -`ipv6-pps` | Generate bidirectional IPv6 traffic between network interface and all session framed IPv6 addresses | 0 (disabled) -`ipv6pd-pps` | Generate bidirectional Ipv6 traffic between network interface and all session delegated IPv6 addresses | 0 (disabled) - -## Traffic Streams - -This section describes all attributes of the `streams` hierarchy -as explained in [Traffic Streams](streams). - -Attribute | Description | Default ---------- | ----------- | ------- -`name` | Mandatory stream name | -`stream-group-id` | Stream group identifier | 0 (raw) -`type` | Mandatory stream type (`ipv4`, `ipv6` or `ipv6pd`) | -`direction` | Mandatory stream direction (`upstream`, `downstream` or `both`) | `both` -`priority` | IPv4 TOS / IPv6 TC | 0 -`vlan-priority` | VLAN priority | 0 -`length` | Layer 3 (IP + payload) traffic length (76 - 9000) | 128 -`pps` | Stream traffic rate in packets per second | 1 -`bps` | Stream traffic rate in bits per second (layer 3) | -`a10nsp-interface` | Select the corresponding A10NSP interface for this stream | -`network-interface` | Select the corresponding network interface for this stream | -`network-ipv4-address` | Overwrite network interface IPv4 address | -`network-ipv6-address` | Overwrite network interface IPv6 address | -`destination-ipv4-address` | Overwrite the IPv4 destination address | -`destination-ipv6-address` | Overwrite the IPv6 destination address | -`access-ipv4-source-address` | Overwrite the access IPv4 source address (client) | -`access-ipv6-source-address` | Overwrite the access IPv6 source address (client) | -`threaded` | Run those streams in separate threads | false -`thread-group` | Assign this stream to thread group (1-255) | 0 (thread per stream) -`max-packets` | Send a burst of N packets and stop | 0 (infinity) -`start-delay` | Wait N seconds after session is established before start | 0 -`tx-label1` | MPLS send (TX) label (outer label) | -`tx-label1-exp` | EXP bits of first label (outer label) | 0 -`tx-label1-ttl` | TTL of first label (outer label) | 255 -`tx-label2` | MPLS send (TX) label (inner label) | -`tx-label2-exp` | EXP bits of first label (inner label) | 0 -`tx-label2-ttl` | TTL of first label (inner label) | 255 -`rx-label1` | Expected receive MPLS label (outer label) | -`rx-label2` | Expected receive MPLS label (inner label) | - -For L2TP downstream traffic the IPv4 TOS is applied to the outer IPv4 and inner IPv4 header. - -The `pps` option supports also float numbers like 0.1, or 2.5 PPS and has priority over `bps` -where second is only a helper to calculate the `pps` based on given `bps` and `length`. - -The options `access-ipv4-source-address` and `access-ipv6-source-address` are used -to test the BNG RPF functionality with traffic send from source addresses different -to those assigned to the client. - -## Access-Line - -This section describes all attributes of the `access-line` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`agent-circuit-id` | Agent-Circuit-Id | -`agent-remote-id` | Agent-Remote-Id | -`rate-up` | Actual Data Rate Upstream | -`rate-down` | Actual Data Rate Downstream | -`dsl-type` | DSL-Type | - -## Access-Line-Profiles - -This section describes all attributes of the `access-line-profiles` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`access-line-profile-id` | Mandatory access-line-profile identifier -`act-up` | Actual Data Rate Upstream | 0 -`act-down` | Actual Data Rate Downstream | 0 -`min-up` | Minimum Data Rate Upstream | 0 -`min-down` | Minimum Data Rate Downstream | 0 -`att-up` | Attainable DataRate Upstream | 0 -`att-down` | Attainable DataRate Downstream | 0 -`max-up` | Maximum Data Rate Upstream | 0 -`max-down` | Maximum Data Rate Downstream | 0 -`min-up-low` | Min Data Rate Upstream in low power state | 0 -`min-down-low` | Min Data Rate Downstream in low power state | 0 -`max-interl-delay-up` | Max Interleaving Delay Upstream | 0 -`act-interl-delay-up` | Actual Interleaving Delay Upstream | 0 -`max-interl-delay-down` | Max Interleaving Delay Downstream | 0 -`act-interl-delay-down` | Actual Interleaving Delay Downstream | 0 -`data-link-encaps` | Data Link Encapsulation | 0 -`dsl-type` | DSL Type | 0 -`pon-type` | PON Access Type | 0 -`etr-up` | Expected Throughput (ETR) Upstream | 0 -`etr-down` | Expected Throughput (ETR) Downstream | 0 -`attetr-up` | Attainable Expected Throughput (ATTETR) Upstream | 0 -`attetr-down` | Attainable Expected Throughput (ATTETR) Downstream | 0 -`gdr-up` | Gamma Data Rate (GDR) Upstream | 0 -`gdr-down` | Gamma Data Rate (GDR) Downstream | 0 -`attgdr-up` | Attainable Gamma Data Rate (ATTGDR) Upstream | 0 -`attgdr-down` | Attainable Gamma Data Rate (ATTGDR) Downstream | 0 -`ont-onu-avg-down` | ONT/ONU Average Data Rate Downstream | 0 -`ont-onu-peak-down` | ONT/ONUPeak Data Rate Downstream | 0 -`ont-onu-max-up` | ONT/ONU Maximum Data Rate Upstream | 0 -`ont-onu-ass-up` | ONT/ONU Assured Data Rate Upstream | 0 -`pon-max-up` | PON Tree Maximum Data Rate Upstream | 0 -`pon-max-down` | PON Tree Maximum Data Rate Downstream | 0 - -Attributes with value set to 0 will not be send. - -The values for `rate-up`, `rate-down` and `dsl-type` defined in the -access-line or interface section have priority over those defined -here. - -```json -{ - "access-line-profiles": [ - { - "access-line-profile-id": 1, - "act-up": 2000, - "act-down": 16000, - "min-up": 64, - "min-down": 1024, - "att-up": 2048, - "att-down": 16384, - "max-up": 2040, - "max-down": 16380, - "min-up-low": 32, - "min-down-low": 1024, - "max-interl-delay-up": 100, - "act-interl-delay-up": 10, - "max-interl-delay-down": 100, - "act-interl-delay-down": 10, - "data-link-encaps": 525061, - "dsl-type": 5, - }, - { - "access-line-profile-id": 2, - "act-up": 40000, - "act-down": 100000, - "pon-type": 1, - "etr-up": 40000, - "etr-down": 100000, - "attetr-up": 40000, - "attetr-down": 100000, - "gdr-up": 40000, - "gdr-down": 100000, - "attgdr-up": 40000, - "attgdr-down": 100000, - "ont-onu-avg-down": 100000, - "ont-onu-peak-down": 100000, - "ont-onu-max-up": 40000, - "ont-onu-ass-up": 40000, - "pon-max-up": 1000000, - "pon-max-down": 2400000 - } - ] -} -``` - -## ISIS - -This section describes all attributes of the `isis` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`instance-id` | ISIS instance identifier | -`level` | ISIS level | 3 -`overload` | ISIS overload | false -`protocol-ipv4` | Enable/disable IPv4 | true -`protocol-ipv6` | Enable/disable IPv6 | true -`level1-auth-key` | ISIS level 1 authentication key | -`level1-auth-type` | ISIS level 1 authentication type (simple or md5) | disabled -`level2-auth-key` | ISIS level 2 authentication key | -`level2-auth-type` | ISIS level 2 authentication type (simple or md5) | disabled -`hello-interval` | ISIS hello interval in seconds | 10 -`hello-padding` | ISIS hello padding | false -`holding-time` | ISIS holding time in seconds | 30 -`lsp-lifetime` | ISIS LSP lifetime in seconds | 65535 -`lsp-refresh-interval` | ISIS LSP refresh interval in seconds | 300 -`lsp-retry-interval` | ISIS LSP retry interval in seconds | 5 -`lsp-tx-interval` | ISIS LSP TX interval in ms (time between LSP send windows) | 10 -`lsp-tx-window-size` | ISIS LSP TX window size (LSP send per window) | 1 -`csnp-interval` | ISIS CSNP interval in seconds | 30 -`hostname` | ISIS hostname | bngblaster -`router-id` | ISIS router identifier | 10.10.10.10 -`system-id` | ISIS system identifier | 0100.1001.0010 -`area` | ISIS area(s) | 49.0001/24 -`sr-base` | ISIS SR base | -`sr-range` | ISIS SR range | -`sr-node-sid` | ISIS SR node SID | -`teardown-time` | ISIS teardown time in seconds | 5 - -### ISIS External - -The BNG Blaster allows to inject LSP's via MRT files as defined in -[RFC6396](https://datatracker.ietf.org/doc/html/rfc6396). Details -to MRT files can be found in [ISIS](isis). - -`"isis": { "external": { ... } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`mrt-file` | ISIS MRT file | - -It is also possible to define external connections as required -to connect the ISIS instance with the link state graph in the MTR -file. - -`"isis": { "external": { "connections": [] } }` - -Attribute | Description | Default ---------- | ----------- | ------- -`system-id` | ISIS system identifier | -`l1-metric` | ISIS level 1 interface metric | 10 -`l2-metric` | ISIS level 2 interface metric | 10 - -```json -{ - "isis": [ - { - "instance-id": 1, - "system-id": "0100.1001.0010", - "router-id": "10.10.10.10", - "hostname": "R1", - "external": { - "mrt-file": "test.mrt", - "connections": [ - { - "system-id": "0000.0000.0001", - "l1-metric": 1000, - "l2-metric": 2000 - } - ] - } - } - ] -} -``` - -## BGP - -This section describes all attributes of the `bgp` hierarchy. - -Attribute | Description | Default ---------- | ----------- | ------- -`network-interface` | BGP local interface (source-interface) | first network interface -`local-ipv4-address` | BGP local IPv4 address (source-address) | network interface address -`local-as` | BGP local AS | 65000 -`peer-ipv4-address` | BGP peer address | -`peer-as` | BGP peer AS | local AS -`holdtime` | BGP holdtime in seconds | 90 -`id` | BGP identifier | 1.2.3.4 -`reconnect` | BGP reconnect | true -`start-traffic` | BGP start global traffic after RAW update | false -`teardown-time` | BGP teardown time in seconds | 5 -`raw-update-file` | BGP RAW update file | - -```json -{ - "bgp": [ - { - "local-ipv4-address": "10.0.1.2", - "peer-ipv4-address": "10.0.1.1", - "raw-update-file": "start.bgp", - "local-as": 65001, - "peer-as": 65001 - } - ] -} -``` \ No newline at end of file diff --git a/docs/ctrl.md b/docs/ctrl.md deleted file mode 100644 index e0a6fa05..00000000 --- a/docs/ctrl.md +++ /dev/null @@ -1,292 +0,0 @@ -# Control Socket - -The control socket is an unix domain stream socket which allows the control daemon to -interact with the BNG Blaster using JSON RPC. This interface was primary developed for -the BNG Blaster Controller but can be also used manually or by other tools like the -simple CLI tool `bngblaster-cli` for interactive communication with the BNG Blaster. - -The control socket will be optionally enabled by providing the path to the socket file -using the argument `-S` (`bngblaster -S test.socket`). - -`$ cat command.json | jq .` - -```json -{ - "command": "session-counters" -} -``` - -`$ cat command.json | sudo nc -U test.socket | jq .` - -```json -{ - "status": "ok", - "code": 200, - "session-counters": { - "sessions": 3, - "sessions-established": 3, - "sessions-flapped": 3, - "dhcpv6-sessions-established": 3 - } -} -``` - -Each request must contain at least the `command` element which carries -the actual command which is invoked with optional arguments. - -`$ cat command.json | jq .` - -```json -{ - "command": "session-info", - "arguments": { - "session-id": 1 - } -} -``` - -`$ cat command.json | sudo nc -U test.socket | jq .` - -```json -{ - "status": "ok", - "code": 200, - "session-info": { - "type": "pppoe", - "session-id": 1, - "session-state": "Established", - "interface": "eth1", - "outer-vlan": 1000, - "inner-vlan": 1, - "mac": "02:00:00:00:00:01", - "username": "user1@rtbrick.com", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:1", - "agent-remote-id": "DEU.RTBRICK.1", - "lcp-state": "Opened", - "ipcp-state": "Opened", - "ip6cp-state": "Opened", - "ipv4-address": "10.100.128.0", - "ipv4-dns1": "10.0.0.3", - "ipv4-dns2": "10.0.0.4", - "ipv6-prefix": "fc66:1000:1::/64", - "ipv6-delegated-prefix": "fc66:2000::/56", - "ipv6-dns1": "fc66::3", - "ipv6-dns2": "fc66::4", - "dhcpv6-state": "Bound", - "dhcpv6-dns1": "fc66::3", - "dhcpv6-dns2": "fc66::4", - "tx-packets": 30, - "rx-packets": 26, - "rx-fragmented-packets": 0, - "session-traffic": { - "total-flows": 6, - "verified-flows": 6, - "first-seq-rx-access-ipv4": 2, - "first-seq-rx-access-ipv6": 2, - "first-seq-rx-access-ipv6pd": 1, - "first-seq-rx-network-ipv4": 2, - "first-seq-rx-network-ipv6": 2, - "first-seq-rx-network-ipv6pd": 1, - "access-tx-session-packets": 5, - "access-rx-session-packets": 4, - "access-rx-session-packets-loss": 0, - "network-tx-session-packets": 5, - "network-rx-session-packets": 4, - "network-rx-session-packets-loss": 0, - "access-tx-session-packets-ipv6": 5, - "access-rx-session-packets-ipv6": 4, - "access-rx-session-packets-ipv6-loss": 0, - "network-tx-session-packets-ipv6": 5, - "network-rx-session-packets-ipv6": 4, - "network-rx-session-packets-ipv6-loss": 0, - "access-tx-session-packets-ipv6pd": 4, - "access-rx-session-packets-ipv6pd": 4, - "access-rx-session-packets-ipv6pd-loss": 0, - "network-tx-session-packets-ipv6pd": 4, - "network-rx-session-packets-ipv6pd": 4, - "network-rx-session-packets-ipv6pd-loss": 0 - } - } -} -``` - -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 .` - -```json -{ - "status": "warning", - "code": 404, - "message": "session not found" -} -``` - -## BNG Blaster CLI - -The python script `bngblaster-cli` provides a simple CLI tool -for interactive communication with the BNG Blaster. - -```cli -$ sudo bngblaster-cli -BNG Blaster Control Socket Client - -bngblaster-cli [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 .` - -```json -{ - "status": "ok", - "code": 200, - "session-counters": { - "sessions": 1, - "sessions-established": 1, - "sessions-flapped": 0, - "dhcpv6-sessions-established": 1 - } -} -``` - -## Control Socket Commands - -### Global Commands - -Attribute | Description ---------- | ----------- -`interfaces` | List all interfaces with index -`session-counters` | Return session counters -`terminate` | Terminate all sessions similar to sending SIGINT (ctr+c) -`session-traffic` | Display session traffic statistics -`session-traffic-start` (Alias: `session-traffic-enabled`) | Start sending session traffic for all sessions -`session-traffic-stop` (Alias: `session-traffic-disabled`) | Stop sending session traffic for all sessions -`stream-traffic-start` (Alias: `stream-traffic-enabled`) | Start sending stream traffic for all sessions -`stream-traffic-stop` (Alias: `stream-traffic-disabled`) | Stop sending stream traffic for all sessions -`stream-stats` | Display global stream traffic statistics -`stream-info` | Display stream traffic statistics identified by flow identifier (`flow-id `) -`multicast-traffic-start` | Start sending multicast traffic from network interface -`multicast-traffic-stop` | Stop sending multicast traffic from network interface -`li-flows` | List all LI flows with detailed statistics -`sessions-pending` | List all sessions not established -`cfm-cc-start` | Start EOAM CFM CC -`cfm-cc-stop` | Stop EOAM CFM CC -`cfm-cc-rdi-on` | Set EOAM CFM CC RDI -`cfm-cc-rdi-off` | Unset EOAM CFM CC RDI -`traffic-start` | Start all traffic (session and streams) -`traffic-stop` | Stop all traffic (session and streams) - -### Session Commands - -The following commands must be execute with either `session-id` or alternative with -interface index and VLAN of the session for which the command is executed. The interface -index (`ifindex`) can be requests using the `interfaces` command or skipped. The first -access interface is automatically used if the argument `ifindex` is not present in the -command. For N:1 sessions only `session-id` is supported because multiple sessions can -be assigned to a single VLAN in this mode. - -`$ cat command.json | jq .` - -```json -{ - "command": "session-info", - "arguments": { - "ifindex": 10, - "outer-vlan": 1, - "inner-vlan": 1 - } -} -``` - -Attribute | Description | Mandatory Arguments | Optional Arguments ---------- | ----------- | ------------------- | ------------------ -`session-info` | Session information | | -`terminate` | Terminate session | | -`ipcp-open` | Open IPCP | | -`ipcp-close` | Close IPCP | | -`ip6cp-open`| Open IP6CP | | -`ip6cp-close` | Close IP6CP | | -`session-traffic-start` (Alias: `session-traffic-enabled`) | Enable session traffic | | -`session-traffic-stop` (Alias: `session-traffic-disabled`) | Disable session traffic | | -`session-streams` | Session traffic stream information | | -`stream-traffic-start` (Alias: `stream-traffic-enabled`) | Enable session stream traffic | | -`stream-traffic-stop` (Alias: `stream-traffic-disabled`) | Disable session stream traffic | | -`igmp-join` | Join group | `group` | `source1`, `source2`, `source3` -`igmp-leave` | Leave group | `group` | -`igmp-info` | IGMP information | | -`cfm-cc-start` | Start EOAM CFM CC -`cfm-cc-stop` | Stop EOAM CFM CC -`cfm-cc-rdi-on` | Set EOAM CFM CC RDI -`cfm-cc-rdi-off` | Unset EOAM CFM CC RDI - -The `session-id` is the same as used for `{session-global}` in the -configuration section. 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`. - -### L2TP Commands - -Attribute | Description | Mandatory Arguments | Optional Arguments ---------- | ----------- | ------------------- | ------------------ -`l2tp-tunnels` | L2TP tunnel information | | -`l2tp-sessions` | L2TP session information | | `tunnel-id`, `session-id` -`l2tp-csurq`| Send L2TP CSURQ | `tunnel-id` | `sessions` -`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. - -`$ cat command.json | jq .` - -```json -{ - "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"` - -### ISIS Commands - -Attribute | Description | Mandatory Arguments | Optional Arguments ---------- | ----------- | ------------------- | ------------------ -`isis-adjacencies` | Display all ISIS adjacencies | | -`isis-database` | ISIS database information | `instance`, `level` | -`isis-load-mrt` | Load ISIS MRT file | `instance`, `file` | -`isis-lsp-update` | Update ISIS LSP | `instance`, `pdu` | -`isis-teardown` | Teardown all ISIS adjacencies | | - -### BGP Commands - -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 all BGP sessions | | -`bgp-raw-update-list` | List all loaded BGP RAW update files in memory | | -`bgp-raw-update` | Update all matching BGP session | `file` | `local-ipv4-address`, `peer-ipv4-address` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 6c804672..00000000 --- a/docs/index.md +++ /dev/null @@ -1,42 +0,0 @@ -# Documentation - -- [Introduction](intro) -- [Installation](install) -- [Configuration](config) -- [Reports](reports) -- [Control Socket](ctrl) -- [PPPoE](pppoe) -- [L2TPv2](l2tp) -- [IPoE](ipoe) -- [Traffic](traffic) -- [Traffic Streams](streams) -- [Multicast](multicast) -- [Legal Interception](li) -- [A10NSP](a10nsp) -- [ISIS](isis) -- [BGP](bgp) - -The BNG Blaster is an open source network test tool which is able to simulate more -than hundred thousand PPPoE and IPoE subscribers including IPTV, L2TPv2, QoS, forwarding -verification and convergence testing capabilities. The BNG Blaster is also contently -enhanced for more common (non-BNG) network testing. - -A short [introduction](https://youtu.be/EHJ70p0_Sw0 "BNG Blaster") and good presentation -from [DENOG13](https://youtu.be/LVg6rlVEfNU "DENOG13") can be found on YouTube. - -![BBL Interactive](images/bbl_interactive.png "BNG Blaster (Interactive Mode)") - -## License - -BNG Blaster is licensed under the BSD 3-Clause License, which means that you are free to get and use it for -commercial and non-commercial purposes as long as you fulfill its conditions. - -See the LICENSE file for more details. - -## Copyright - -Copyright (C) 2020-2022, RtBrick, Inc. - -## Contact - -bngblaster@rtbrick.com \ No newline at end of file diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index da8141b7..00000000 --- a/docs/install.md +++ /dev/null @@ -1,149 +0,0 @@ -# Installation - -The BNG Blaster should run on any modern linux distribution -but is primary tested on Ubuntu 18.04 LTS and Ubuntu 20.04 LTS. - -## Install Ubuntu - -Install dependencies: - -```cli -sudo apt install -y libssl1.1 libncurses5 libjansson4 -``` - -Download and install debian package: -[https://github.com/rtbrick/bngblaster/releases](https://github.com/rtbrick/bngblaster/releases) - -```cli -sudo dpkg -i -``` - -This command installs the BNG Blaster to `/usr/sbin/bngblaster`. - -## Build from Sources - -### Dependencies - -The BNG Blaster has dependencies to the RtBrick -[libdict fork](https://github.com/rtbrick/libdict) -and the following standard dependencies: - -```cli -# libdict -wget https://github.com/rtbrick/libdict/releases/download/v1.0.1/libdict-debian.zip -sudo dpkg -i libdict_1.0.1_amd64.deb -sudo dpkg -i libdict-dev_1.0.1_amd64.deb - -# standard dependencies -sudo apt install -y cmake \ - libcunit1-dev \ - libncurses5-dev \ - libssl-dev \ - libjansson-dev -``` - -### Build - -Per default cmake (`cmake .`) will build the BNG Blaster as release -version with optimization and without debug symbols. - -```cli -mkdir build -cd build -cmake -DCMAKE_BUILD_TYPE=Release .. -make all -``` - -Alternative it is also possible to build a debug -version for detailed troubleshooting using gdb. - -```cli -mkdir build -cd build -cmake -DCMAKE_BUILD_TYPE=Debug .. -make all -``` - -There are also CPack files generated which allows to easily generate a debian -package by just executing `cpack` from build directory. - -It is also recommended to provide the GIT commit details to be included in the -manually build version as shown below: - -```cli -cmake -DGIT_REF=`git rev-parse --abbrev-ref HEAD` -DGIT_SHA=`git rev-parse HEAD` . -``` - -*Example:* - -```cli -$ bngblaster -v -GIT: - REF: dev - SHA: df453a5ee9dbf6440aefbfb9630fa0f06e326d44 -IO Modes: packet_mmap_raw (default), packet_mmap, raw -``` - -### Install - -Then BNG Blaster can be installed using make install target. - -```cli -sudo make install -``` - -This command installs the BNG Blaster to `/usr/sbin/bngblaster`. - -### Build and Run Unit Tests - -Building and running unit tests requires CMocka to be installed: - -```cli -sudo apt install libcmocka-dev -``` - -The option `BNGBLASTER_TESTS` enables to build unit tests. - -```cli -cmake -DCMAKE_BUILD_TYPE=Debug -DBNGBLASTER_TESTS=ON . -make all -make test -``` - -*Example:* - -```cli -$ make test -Running tests... -Test project - Start 1: TestProtocols -1/1 Test #1: TestProtocols .................... Passed 0.00 sec - -100% tests passed, 0 tests failed out of 1 - -Total Test time (real) = 0.00 sec -``` - -### Running BNG Blaster - -The BNG Blaster needs permissions to send raw packets and change network interface -settings. The easiest way to run the BNG Blaster is either as the root user or with -sudo: - -```cli -# As root -bngblaster -C config.json -I - -# As a normal user: -sudo bngblaster -C config.json -I -``` - -A third option is to set capabilities on the binary with in example `setcap` -as shown below: - -```cli -sudo setcap cap_net_raw,cap_net_admin,cap_dac_read_search+eip `which bngblaster` - -# As normal user: -bngblaster -C config.json -I -``` diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index b540a3ef..00000000 --- a/docs/intro.md +++ /dev/null @@ -1,115 +0,0 @@ -# Introduction - -Building a BNG from scratch requires a lot of testing but commercial BNG test software -is often very expensive, resource intensive and provide a lot of administrative overhead -to maintain such. - -Therefore we decided to build an open source network test software initially focused on BNG -and IPTV testing but constantly enhanced and planned for more common (non-BNG) network testing. -The BNG Blaster was completely build from scratch, targeted for max scaling with small -resource footprint, simple to use and easy to integrate in any test automation infrastructure. - -The BNG Blaster is able to simulate more than hundred thousand PPPoE and IPoE (DHCP) subscribers including -IPTV, L2TPv2 (LNS emulation), L2BSA, QoS, forwarding verification and convergence testing capabilities. - -* *High Scaling:* > 100K sessions, > 1M PPS, and > 1M traffic flows -* *Low CPU and Memory Footprint:* ~300MB memory for 16K sessions -* *Portable:* runs on every modern linux, virtual machines and containers -* *User Space:* all protocols implemented in user-space from scratch and optimized for performance -* *IPTV:* IGMP version 1, 2 and 3 with automated channel zapping test -* *QoS:* define and analyze traffic streams -* *Automation:* the BNG Blaster Controller provides an automation friendly REST API and robot keywords - -**Info:** _The BNG Blaster Controller is not yet published but you can send -a mail to bngblaster@rtbrick.com if you are interested to get early access!_ - -```cli -$ bngblaster --help - - - ____ __ ____ _ __ ,/ - / __ \ / /_ / __ ) _____ (_)_____ / /__ ,'/ - / /_/ // __// __ |/ ___// // ___// //_/ ,' / - / _, _// /_ / /_/ // / / // /__ / ,< ,' /_____, - /_/ |_| \__//_____//_/ /_/ \___//_/|_| .'____ ,' - ____ _ _ ______ ____ _ _ / ,' - / __ ) / | / // ____/ / __ ) / /____ _ _____ / /_ ___ ____ / ,' - / __ |/ |/ // / __ / __ |/ // __ `// ___// __// _ \ / ___/ /,' - / /_/ // /| // /_/ / / /_/ // // /_/ /(__ )/ /_ / __// / / - /_____//_/ |_/ \____/ /_____//_/ \__,_//____/ \__/ \___//_/ - -Usage: bngblaster [OPTIONS] - - -v --version - -h --help - -C --config - -T --stream-config - -l --logging debug|error|igmp|io|pppoe|info|pcap|timer|timer-detail|ip|loss|l2tp|dhcp - -L --log-file - -u --username - -p --password - -P --pcap-capture - -j --json-report-content sessions|streams - -J --json-report-file - -c --session-count - -g --mc-group - -s --mc-source - -r --mc-group-count - -z --mc-zapping-interval - -S --control-socket - -I --interactive - -b --hide-banner - -f --force - -``` - -The BNG Blaster includes an optional interactive mode (`-I`) with realtime stats and -log viewer as shown below. - -![BNG Blaster Interactive](images/bbl_interactive.png) - -## Theory Of Operation - -The BNG Blaster has been completely built from scratch, including user-space implementations of the entire protocol -stack you need for interfacing with a BNG. It’s core is based on a very simple event loop which serves timers and signals. -The timers have been built using a lightweight constant time (`O(1)`) library which we built purposely to start, restart -and delete the protocol session FSM timers quickly and at scale. - -The BNG Blaster expects a Linux kernel network interface which is up, but not configured with any IP addresses or VLAN as it -expects to receive and transmit RAW ethernet packets. - -The BNG Blaster does I/O using high-speed polling timers with a mix of Linux -[RAW Packet Sockets](https://man7.org/linux/man-pages/man7/packet.7.html) and -[Packet MMAP](https://www.kernel.org/doc/html/latest/networking/packet_mmap.html). - -The second one is a so-called PACKET_RX_RING/PACKET_TX_RING abstraction where a user-space program gets a fast-lane into reading -and writing to kernel interfaces using a shared ring buffer. The shared ring buffer is a memory mapped "window" that is shared -between kernel and user-space. This low overhead abstraction allows to transmit and receive traffic without doing expensive system calls. -Sending and transmitting traffic via Packet MMAP is as easy as just by copying a packet into a buffer and setting a flag. - -![BNG Blaster Architecture](images/bbl_arch.png) - -The BNG Blaster supports multiple configurable I/O modes listed with `bngblaster -v` but except `packet_mmap_raw` all other modes -are currently considered as experimental. In the default mode (`packet_mmap_raw`) all packets are received in a Packet MMAP ring -buffer and send directly trough RAW packet sockets. This combination was the most efficient in our benchmark tests. - -BNG Blasters primary design goal is to simulate thousands of subscriber CPE's with a small hardware resource footprint. Simple -to use and easy to integrate in our robot test automation infrastructure. This allows to simulate more than hundred thousand -PPPoE or IPoE (DHCP) subscribers including IPTV, traffic verification and convergence testing from a single medium scale -virtual machine or to run the blaster directly from a laptop. - -The BNG Blaster provides three types of interfaces. The first interface is called the access interface which emulates the PPPoE -sessions. The second interface-type is called network interface. This is used for emulating the core-facing side of the -internet. The last type is called a10nsp interface which emulates an layer two provider interface. The term A10 -refers to the end-to-end ADSL network reference model from TR-025. - -![BNG Blaster Interfaces](images/bbl_interfaces.png) - -This allows to verify IP reachability by sending bidirectional traffic between all PPPoE sessions on access-interface and the -network interface. The network interface is also used to inject downstream multicast test traffic for IPTV tests. It is also -possible to send RAW traffic streams between multiple network interfaces without any access interface defined for non-BNG -testing. - -One popular example for non-BNG tests with the BNG Blaster is the verification of a BGP full-table by injecting around 1M -prefixes and setting up traffic streams for all prefixes with at least one PPS (1M PPS). The BNG Blaster is able to verify -and analyze every single flow with detailed per flow statistics (receive rate, loss, latency, ...). diff --git a/docs/ipoe.md b/docs/ipoe.md deleted file mode 100644 index 2f291bf9..00000000 --- a/docs/ipoe.md +++ /dev/null @@ -1,151 +0,0 @@ -# IPoE - -The BNG Blaster is able to emulate IP over Ethernet (IPoE) -subscribers with static and dynamic address assignment -supporting 1:1 and N:1 VLAN mode. - -## Static Addresses - -Static addresses means that the IP address and gateway is assigned -statically as shown in the example below. - -```json -{ - "interfaces": { - "access": [ - { - "interface": "eth1", - "type": "ipoe", - "vlan-mode": "1:1", - "outer-vlan-min": 128, - "outer-vlan-max": 4000, - "address": "200.0.0.1", - "address-iter": "0.0.0.4", - "gateway": "200.0.0.2", - "gateway-iter": "0.0.0.4", - } - ] - } -} -``` - -## DHCPv4/v6 - -The most common case for IPoE is using DHCPv4/v6 as shown below. - -```json -{ - "interfaces": { - "access": [ - { - "interface": "eth1", - "type": "ipoe", - "outer-vlan": 7, - "vlan-mode": "N:1" - } - ] - }, - "dhcp": { - "enable": true, - }, - "dhcpv6": { - "enable": true - }, - "access-line": { - "agent-remote-id": "DEU.RTBRICK.{session-global}", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}" - } -} -``` - -## IPoE Session Information - -The control socket command `session-info session-id ` provides -detailed information for IPoE sessions. - -`$ sudo bngblaster-cli run.sock session-info session-id 1 | jq .` - -```json -{ - "status": "ok", - "code": 200, - "session-information": { - "type": "ipoe", - "session-id": 1, - "session-state": "Established", - "interface": "eth1", - "outer-vlan": 8, - "inner-vlan": 1, - "mac": "02:00:00:00:00:01", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:1", - "agent-remote-id": "DEU.RTBRICK.1", - "ipv4-address": "1.1.1.3", - "ipv4-netmask": "255.255.255.255", - "ipv4-gateway": "1.1.1.1", - "ipv4-dns1": "10.0.0.3", - "ipv4-dns2": "10.0.0.4", - "ipv6-prefix": "fc66:1337:2222::3/128", - "ipv6-delegated-prefix": "fc66:1337:3333:2::/64", - "dhcp-state": "Bound", - "dhcp-server": "1.1.1.1", - "dhcp-lease-time": 300, - "dhcp-lease-expire": 299, - "dhcp-lease-expire-t1": 149, - "dhcp-lease-expire-t2": 261, - "dhcp-tx": 2, - "dhcp-rx": 2, - "dhcp-tx-discover": 1, - "dhcp-rx-offer": 1, - "dhcp-tx-request": 1, - "dhcp-rx-ack": 1, - "dhcp-rx-nak": 0, - "dhcp-tx-release": 0, - "dhcpv6-state": "Bound", - "dhcpv6-lease-time": 14400, - "dhcpv6-lease-expire": 14399, - "dhcpv6-lease-expire-t1": 899, - "dhcpv6-lease-expire-t2": 1439, - "dhcpv6-tx": 1, - "dhcpv6-rx": 1, - "dhcpv6-tx-solicit": 1, - "dhcpv6-rx-advertise": 0, - "dhcpv6-tx-request": 0, - "dhcpv6-rx-reply": 1, - "dhcpv6-tx-renew": 0, - "dhcpv6-tx-release": 0, - "dhcpv6-dns1": "fc66::3", - "dhcpv6-dns2": "fc66::4", - "tx-packets": 6, - "rx-packets": 6, - "rx-fragmented-packets": 0, - "session-traffic": { - "total-flows": 6, - "verified-flows": 0, - "first-seq-rx-access-ipv4": 0, - "first-seq-rx-access-ipv6": 0, - "first-seq-rx-access-ipv6pd": 0, - "first-seq-rx-network-ipv4": 0, - "first-seq-rx-network-ipv6": 0, - "first-seq-rx-network-ipv6pd": 0, - "access-tx-session-packets": 0, - "access-rx-session-packets": 0, - "access-rx-session-packets-loss": 0, - "network-tx-session-packets": 0, - "network-rx-session-packets": 0, - "network-rx-session-packets-loss": 0, - "access-tx-session-packets-ipv6": 0, - "access-rx-session-packets-ipv6": 0, - "access-rx-session-packets-ipv6-loss": 0, - "network-tx-session-packets-ipv6": 0, - "network-rx-session-packets-ipv6": 0, - "network-rx-session-packets-ipv6-loss": 0, - "access-tx-session-packets-ipv6pd": 0, - "access-rx-session-packets-ipv6pd": 0, - "access-rx-session-packets-ipv6pd-loss": 0, - "network-tx-session-packets-ipv6pd": 0, - "network-rx-session-packets-ipv6pd": 0, - "network-rx-session-packets-ipv6pd-loss": 0 - } - } -} -``` diff --git a/docs/isis.md b/docs/isis.md deleted file mode 100644 index e3f7ff4f..00000000 --- a/docs/isis.md +++ /dev/null @@ -1,339 +0,0 @@ -# ISIS - -Intermediate System to Intermediate System (ISIS, also written IS-IS) -is a routing protocol designed to move information efficiently within -a network. - -The ISIS protocol is defined in ISO/IEC 10589:2002 as an international -standard within the Open Systems Interconnection (OSI) reference design. -The Internet Engineering Task Force (IETF) republished ISIS in RFC 1142, -but that RFC was later marked as historic by RFC 7142 because it republished -a draft rather than a final version of the ISO standard, causing confusion. - -ISIS has been called the de facto standard for large service provider -network backbones. - -The BNG Blaster is able to emulate multiple ISIS instances. An ISIS instance -is a virtual ISIS node with one or more network interfaces attached. Such a -node behaves like a "real router" including database synchronization and -flooding. Every instance generates a `self` originated LSP describing the -node itself. - -Following an example ISIS configuration with one instance -attached to two network interfaces. - -```json -{ - "interfaces": { - "network": [ - { - "interface": "eth1", - "address": "10.0.1.2/24", - "gateway": "10.0.1.1", - "address-ipv6": "fc66:1337:7331:1::2/64", - "gateway-ipv6": "fc66:1337:7331:1::1", - "isis-instance-id": 1, - "isis-level": 1, - "isis-l1-metric": 100, - }, - { - "interface": "eth2", - "address": "10.0.2.2/24", - "gateway": "10.0.2.1", - "address-ipv6": "fc66:1337:7331:2::2/64", - "gateway-ipv6": "fc66:1337:7331:2::1", - "isis-instance-id": 1 - } - ] - }, - "isis": [ - { - "instance-id": 1, - "system-id": "0100.1001.0010", - "router-id": "10.10.10.10", - "hostname": "R1", - "area": [ - "49.0001/24", - "49.0002/24" - ], - "hello-padding": true, - "lsp-lifetime": 65535, - "level1-auth-key": "secret", - "level1-auth-type": "md5", - "sr-base": 2000, - "sr-range": 3600 - } - ] -} -``` - -All supported ISIS [configuration](config) options and [commands](ctrl) are -detailed explained corresponding sections of this documentation. - -The support for multiple instances allows different use cases. One example might -be to create two instances connected to the device or network under test. Now -inject a LSP on one instance and check if learned over the tested network on -the other instance. - -Every ISIS instance can be also connected to an emulated link state graph loaded -by MRT files as shown in the example below. - -![BBL ISIS](images/bbl_isis.png "ISIS") - -```json -{ - "isis": [ - { - "instance-id": 1, - "system-id": "0100.1001.0011", - "router-id": "10.10.10.11", - "hostname": "B1", - "external": { - "mrt-file": "test.mrt", - "connections": [ - { - "system-id": "0000.0000.0001", - "l1-metric": 1000, - "l2-metric": 2000 - } - ] - } - }, - { - "instance-id": 1, - "system-id": "0100.1001.0011", - "router-id": "10.10.10.12", - "hostname": "B2" - } - ] -} -``` - -The node `N1` in this example also needs to advertise the -reachability to the node `B1`. - -## Adjacencies - -The BNG Blaster supports P2P adjacencies with 3-way-handshake only. - -`$ sudo bngblaster-cli run.sock isis-adjacencies` -```json -{ - "status": "ok", - "code": 200, - "isis-adjacencies": [ - { - "interface": "eth1", - "type": "P2P", - "level": "L1", - "instance-id": 2, - "adjacency-state": "Up", - "peer": { - "system-id": "0100.1001.0022" - } - }, - { - "interface": "eth2", - "type": "P2P", - "level": "L1", - "instance-id": 1, - "adjacency-state": "Up", - "peer": { - "system-id": "0100.1001.0021" - } - } - ] -} -``` - -## Database - -The BNG Blaster distinguishes between three different source types of -LSP entries in the ISIS database. - -The type `self` is used for the self originated LSP describing the own -BNG Blaster ISIS instance. LSP entries of type `adjacency` are learned -via ISIS adjacencies. The type `external` is used for those LSP entries -learned via MRT files or injected via `isis-lsp-update` command. - -`$ sudo bngblaster-cli run.sock isis-database instance 1 level 1` -```json -{ - "status": "ok", - "code": 200, - "isis-database": [ - { - "id": "0000.0000.0001.00-00", - "seq": 1, - "lifetime": 65535, - "lifetime-remaining": 65529, - "source-type": "external" - }, - { - "id": "0100.1001.0011.00-00", - "seq": 2, - "lifetime": 65535, - "lifetime-remaining": 65507, - "source-type": "self" - }, - { - "id": "0100.1001.0021.00-00", - "seq": 2, - "lifetime": 65524, - "lifetime-remaining": 65506, - "source-type": "adjacency", - "source-system-id": "0100.1001.0021" - }, - { - "id": "0100.1001.0022.00-00", - "seq": 2, - "lifetime": 65524, - "lifetime-remaining": 65506, - "source-type": "adjacency", - "source-system-id": "0100.1001.0021" - } - ] -} -``` - -The BNG Blaster automatically purges all LSP's of type -`self` and `external` during teardown. This is done by -generating LSP's with a newer sequence numbers and lifetime -of 30 seconds only. This lifetime is enough to flood the purge -LSP over te whole network under test. - -## Flooding - -The BNG Blaster floods LSP's received to all other active -adjacencies of the ISIS instance except to those with peer -system-id equal to the source system-id of the LSP. - -## Limitations - -Currently only ISIS P2P links are supported. There is also -no support for route leaking between levels. - -## MRT Files - -The BNG Blaster is able to load LSP's from a MRT file as defined in -[RFC6396](https://datatracker.ietf.org/doc/html/rfc6396). - -```text - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Timestamp | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Subtype | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Message... (variable) - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - -The message field contains the complete ISIS LSP PDU including -the ISIS common header starting with `0x83`. - -Those files can be loaded at startup via configuration option -`"isis": { "external": { "mrt-file": "" } }` or alternative -via `isis-load-mrt` command. - -`$ sudo bngblaster-cli run.sock isis-load-mrt file test.mrt instance 1` - -## LSP Update Command - -It is also possible to inject external LSP's using the `isis-lsp-update` -command. - -The command expects a list of hex encoded PDU's including -the ISIS common header starting with `0x83`, - -`$ cat command.json | jq .` -```json -{ - "command": "isis-lsp-update", - "arguments": { - "instance": 1, - "pdu": [ - "831b0100120100000021ffff010203040506000000000003c0d103010403490001", - "831b0100120100000021ffff010203040506000100000003bad603010403490001" - ] - } -} -``` - -## LSPGEN - -The BNG Blaster includes a tool called `lspgen` which is able to generate -link state packets and topologies for export as MRT and PCAP files or directly -injected via BNG Blaster LSP update command. This tool is detailed explained -in the chapter [LSPGEN](lspgen) of this documentation. - -## LSP Update via Scapy - -The following example shows how to generate LSP's via Scapy -and inject them using the `isis-lsp-update` command. - -```python -import sys -import socket -import os -import json - -from scapy.contrib.isis import * - -def error(*args, **kwargs): - """print error and exit""" - print(*args, file=sys.stderr, **kwargs) - sys.exit(1) - - -def execute_command(socket_path, request): - if os.path.exists(socket_path): - client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) - try: - client.connect(socket_path) - client.send(json.dumps(request).encode('utf-8')) - data = "" - while True: - junk = client.recv(1024) - if junk: - data += junk.decode('utf-8') - else: - break - print(json.dumps(json.loads(data), indent=4)) - except Exception as e: - error(e) - finally: - client.close() - else: - error("socket %s not found" % socket_path) - - -def main(): - """main function""" - socket_path = sys.argv[1] - - command = { - "command": "isis-lsp-update", - "arguments": { - "instance": 1, - "pdu": [] - } - } - - tlvs = ISIS_AreaTlv(areas=ISIS_AreaEntry(areaid='49.0001')) - pdu = ISIS_CommonHdr()/ISIS_L1_LSP(lifetime=65535, lspid='0102.0304.0506.00-00', seqnum=3, tlvs=tlvs) - command["arguments"]["pdu"].append(pdu.build().hex()) - - pdu = ISIS_CommonHdr()/ISIS_L1_LSP(lifetime=65535, lspid='0102.0304.0506.00-01', seqnum=3, tlvs=tlvs) - command["arguments"]["pdu"].append(pdu.build().hex()) - - execute_command(socket_path, command) - - -if __name__ == "__main__": - main() - -``` \ No newline at end of file diff --git a/docs/l2tp.md b/docs/l2tp.md deleted file mode 100644 index efddf250..00000000 --- a/docs/l2tp.md +++ /dev/null @@ -1,387 +0,0 @@ -# L2TPv2 - -The BNG Blaster is able to emulate L2TPv2 (RFC2661) LNS servers to -be able to test the L2TPv2 LAC functionality of the BNG device under -test. - -Following an example with 30 L2TP LNS servers. - -```json -{ - "interfaces": { - "network": { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2", - "address-ipv6": "fc66:1337:7331:8::10", - "gateway-ipv6": "fc66:1337:7331:8::1" - }, - "access": [ - { - "interface": "eth1", - "outer-vlan-min": 1, - "outer-vlan-max": 4000, - "inner-vlan-min": 7, - "inner-vlan-max": 7, - "authentication-protocol": "PAP" - }, - { - "interface": "eth1", - "outer-vlan-min": 1, - "outer-vlan-max": 4000, - "inner-vlan-min": 8, - "inner-vlan-max": 8, - "authentication-protocol": "CHAP" - } - ] - }, - "pppoe": { - "reconnect": true, - "discovery-timeout": 3, - "discovery-retry": 10 - }, - "ppp": { - "mru": 1492, - "authentication": { - "username": "blaster@l2tp.de", - "password": "test", - "timeout": 1, - "retry": 60 - }, - "lcp": { - "conf-request-timeout": 5, - "conf-request-retry": 30, - "keepalive-interval": 30, - "keepalive-retry": 3 - }, - "ipcp": { - "enable": true - }, - "ip6cp": { - "enable": true - } - }, - "access-line": { - "agent-remote-id": "DEU.RTBRICK.{session}", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session}", - "rate-up": 1024, - "rate-down": 16384 - }, - "l2tp-server": [ - { - "name": "LNS1", - "address": "10.0.0.11", - "secret": "test1", - "receive-window-size": 8 - }, - { - "name": "LNS2", - "address": "10.0.0.12", - "secret": "test2", - "receive-window-size": 8 - }, - { - "name": "LNS3", - "address": "10.0.0.13", - "secret": "test3", - "receive-window-size": 8 - }, - { - "name": "LNS4", - "address": "10.0.0.14", - "secret": "test4", - "receive-window-size": 8 - }, - { - "name": "LNS5", - "address": "10.0.0.15", - "secret": "test5", - "receive-window-size": 8 - }, - { - "name": "LNS6", - "address": "10.0.0.16", - "secret": "test6", - "receive-window-size": 8 - }, - { - "name": "LNS7", - "address": "10.0.0.17", - "secret": "test7", - "receive-window-size": 8 - }, - { - "name": "LNS8", - "address": "10.0.0.18", - "secret": "test8", - "receive-window-size": 8 - }, - { - "name": "LNS9", - "address": "10.0.0.19", - "secret": "test9", - "receive-window-size": 8 - }, - { - "name": "LNS10", - "address": "10.0.0.20", - "secret": "test10", - "receive-window-size": 8 - }, - { - "name": "LNS11", - "address": "10.0.0.21", - "secret": "test11", - "receive-window-size": 8 - }, - { - "name": "LNS12", - "address": "10.0.0.22", - "secret": "test12", - "receive-window-size": 8 - }, - { - "name": "LNS13", - "address": "10.0.0.23", - "secret": "test13", - "receive-window-size": 8 - }, - { - "name": "LNS14", - "address": "10.0.0.24", - "secret": "test14", - "receive-window-size": 8 - }, - { - "name": "LNS15", - "address": "10.0.0.25", - "secret": "test15", - "receive-window-size": 8 - }, - { - "name": "LNS16", - "address": "10.0.0.26", - "secret": "test16", - "receive-window-size": 8 - }, - { - "name": "LNS17", - "address": "10.0.0.27", - "secret": "test17", - "receive-window-size": 8 - }, - { - "name": "LNS18", - "address": "10.0.0.28", - "secret": "test18", - "receive-window-size": 8 - }, - { - "name": "LNS19", - "address": "10.0.0.29", - "secret": "test19", - "receive-window-size": 8 - }, - { - "name": "LNS20", - "address": "10.0.0.30", - "secret": "test20", - "receive-window-size": 8 - }, - { - "name": "LNS21", - "address": "10.0.0.31", - "secret": "test21", - "receive-window-size": 8 - }, - { - "name": "LNS22", - "address": "10.0.0.32", - "secret": "test22", - "receive-window-size": 8 - }, - { - "name": "LNS23", - "address": "10.0.0.33", - "secret": "test23", - "receive-window-size": 8 - }, - { - "name": "LNS24", - "address": "10.0.0.34", - "secret": "test24", - "receive-window-size": 8 - }, - { - "name": "LNS25", - "address": "10.0.0.35", - "secret": "test25", - "receive-window-size": 8 - }, - { - "name": "LNS26", - "address": "10.0.0.36", - "secret": "test26", - "receive-window-size": 8 - }, - { - "name": "LNS27", - "address": "10.0.0.37", - "secret": "test27", - "receive-window-size": 8 - }, - { - "name": "LNS28", - "address": "10.0.0.38", - "secret": "test28", - "receive-window-size": 8 - }, - { - "name": "LNS29", - "address": "10.0.0.39", - "secret": "test29", - "receive-window-size": 8 - }, - { - "name": "LNS30", - "address": "10.0.0.40", - "secret": "test30", - "receive-window-size": 8 - } - ], - "session-traffic": { - "autostart": true, - "ipv4-pps": 1 - } -} -``` - -## Receive Tunnel Information - -`$ sudo bngblaster-cli run.sock l2tp-tunnels` - -```json -{ - "status": "ok", - "code": 200, - "l2tp-tunnels": [ - { - "state": "Established", - "server-name": "LNS1", - "server-address": "10.0.0.11", - "tunnel-id": 1, - "peer-tunnel-id": 50011, - "peer-name": "BNG", - "peer-address": "10.0.0.2", - "peer-vendor": "RtBrick, Inc.", - "secret": "test1", - "control-packets-rx": 102, - "control-packets-rx-dup": 0, - "control-packets-rx-out-of-order": 0, - "control-packets-tx": 102, - "control-packets-tx-retry": 0, - "data-packets-rx": 1406, - "data-packets-tx": 206 - } - ] -} -``` - -## Receive Session Information - -The `l2tp-sessions` command returns all L2TP sessions. - -`$ sudo bngblaster-cli run.sock l2tp-sessions` - -```json -{ - "status": "ok", - "code": 200, - "l2tp-sessions": [ - { - "state": "Established", - "tunnel-id": 1, - "session-id": 1, - "peer-tunnel-id": 50011, - "peer-session-id": 32867, - "peer-proxy-auth-name": "blaster@l2tp.de", - "peer-called-number": "N/A", - "peer-calling-number": "N/A", - "peer-sub-address": "N/A", - "peer-tx-bps": 48000, - "peer-rx-bps": 1000, - "peer-ari": "DEU.RTBRICK.1", - "peer-aci": "0.0.0.0/0.0.0.0 eth 0:1", - "data-packets-rx": 79, - "data-packets-tx": 79, - "data-ipv4-packets-rx": 15, - "data-ipv4-packets-tx": 15 - } - ] -} -``` - -This output can be also filtered to return only sessions -of a given tunnel. - -`sudo bngblaster-cli run.sock l2tp-sessions tunnel-id 1` - -It is also possible to display a single session. - -`$ sudo bngblaster-cli run.sock l2tp-sessions tunnel-id 1 session-id 1` - -## RFC5515 - -The Agent-Circuit-Id and Agent-Remote-Id AVP defined in RFC5515 -is supported and stored for each session if received. Received -CSUN messages are processed correctly and via control socket it -is possible to send also CSURQ requests to the LAC. - -## Variable Data Header - -The L2TP protocol allows different data header options resulting in -variable header lengths. The most common options can be tested with just -four servers as shown in the example below. - -```json -{ - "l2tp-server": [ - { - "name": "LNS1", - "address": "10.0.0.11", - "secret": "test1", - "receive-window-size": 8, - "congestion-mode": "default", - "data-control-priority": true - }, - { - "name": "LNS2", - "address": "10.0.0.12", - "secret": "test2", - "receive-window-size": 8, - "congestion-mode": "default", - "data-control-priority": true, - "data-length": true - }, - { - "name": "LNS3", - "address": "10.0.0.11", - "secret": "test3", - "receive-window-size": 8, - "congestion-mode": "default", - "data-control-priority": true, - "data-offset": true - }, - { - "name": "LNS4", - "address": "10.0.0.12", - "secret": "test4", - "receive-window-size": 8, - "congestion-mode": "default", - "data-control-priority": true, - "data-length": true, - "data-offset": true - } - ] -} -``` diff --git a/docs/li.md b/docs/li.md deleted file mode 100644 index 5c1ab058..00000000 --- a/docs/li.md +++ /dev/null @@ -1,92 +0,0 @@ -# Legal Interception (LI) - -The BNG Blaster can be used to emulate a mediation device providing detailed statistics -about the received flows. Today only the BCM QMX LI header format is supported but further -headers can be easily integrated. - -*BCM QMX LI Header Format* - -```text - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| D | PT | SPT | LIID | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - -The functionality is automatically enabled on the network interface -and works combined with sessions in one instance or as standalone -mediation device as shown in the following example. - -```json -{ - "interfaces": { - "tx-interval": 10, - "rx-interval": 1, - "network": { - "interface": "eth2", - "address": "100.0.0.10", - "gateway": "100.0.0.2" - } - } -} -``` - -The received flows can be queried using the control socket. - -`$ sudo bngblaster-cli run.sock li-flows` - -```json -{ - "status": "ok", - "code": 200, - "li-flows": [ - { - "source-address": "1.1.1.1", - "source-port": 49152, - "destination-address": "1.1.1.2", - "destination-port": 49152, - "direction": "downstream", - "packet-type": "ethernet", - "sub-packet-type": "double-tagged", - "liid": 4194301, - "bytes-rx": 94, - "packets-rx": 1, - "packets-rx-ipv4": 0, - "packets-rx-ipv4-tcp": 0, - "packets-rx-ipv4-udp": 0, - "packets-rx-ipv4-host-internal": 0, - "packets-rx-ipv6": 0, - "packets-rx-ipv6-tcp": 0, - "packets-rx-ipv6-udp": 0, - "packets-rx-ipv6-host-internal": 0, - "packets-rx-ipv6-no-next-header": 0 - }, - { - "source-address": "1.1.1.1", - "source-port": 49152, - "destination-address": "1.1.1.2", - "destination-port": 49152, - "direction": "upstream", - "packet-type": "ethernet", - "sub-packet-type": "double-tagged", - "liid": 4194301, - "bytes-rx": 160720, - "packets-rx": 820, - "packets-rx-ipv4": 820, - "packets-rx-ipv4-tcp": 0, - "packets-rx-ipv4-udp": 0, - "packets-rx-ipv4-host-internal": 820, - "packets-rx-ipv6": 0, - "packets-rx-ipv6-tcp": 0, - "packets-rx-ipv6-udp": 0, - "packets-rx-ipv6-host-internal": 0, - "packets-rx-ipv6-no-next-header": 0 - } - ] -} -``` - -The `packets-rx-ipv4-host-internal` refers to the IPv4 protocol number 61 (any host internal protocol) -which is used by some network testers as default type for traffic streams. -The same is valid for `packets-rx-ipv6-host-internal` which refers to next header 61 and -`packets-rx-ipv6-no-next-header` with next header 59. diff --git a/docs/lspgen.md b/docs/lspgen.md deleted file mode 100644 index 0bd55af8..00000000 --- a/docs/lspgen.md +++ /dev/null @@ -1 +0,0 @@ -# LSPGEN \ No newline at end of file diff --git a/docs/multicast.md b/docs/multicast.md deleted file mode 100644 index 1a930c64..00000000 --- a/docs/multicast.md +++ /dev/null @@ -1,203 +0,0 @@ -# Multicast - -The BNG Blaster provides advanced functionalities for testing multicast -over PPPoE sessions with focus on IPTV. Therefore IGMP version 1, 2 and 3 -is implemented with support for up to 8 group records per session and 3 -sources per group. - -Multicast testing is supported using external multicast traffic like real -world IPTV traffic or by generating multicast traffic on the network interface. - -## Generate Multicast Traffic - -The BNG Blaster is recognizing loss using the BNG Blaster header sequence numbers. -After first multicast traffic is received for a particular group, for every further -packet it checks if there is a gap between last and new sequence number which is than -reported as loss. The loss logging option (-l loss) allows also to search for the missing -packets in the corresponding capture files (see test.log). - -It is also possible to start a dedicated BNG Blaster instance to generate multicast -traffic which can be consumed by multiple BNG Blaster instances. The BNG Blaster -header allows to do the same measurements on traffic generated from same or different -BNG Blaster instance. - -The following example shows generates traffic for 100 multicast groups -with one packet per millisecond for every group as required to measure the join and leave -delay in milliseconds. - -```json -{ - "interfaces": { - "tx-interval": 1.0, - "rx-interval": 1.0, - "network": { - "interface": "eth2", - "address": "100.0.0.10", - "gateway": "100.0.0.2" - } - }, - "igmp": { - "group": "239.0.0.1", - "group-iter": "0.0.0.1", - "group-count": 100, - "source": "100.0.0.10", - "send-multicast-traffic": true - } -} -``` - -The `tx-interval` and `rx-interval` should be set to at to at least `1.0` (1ms) for more -precise IGMP join/leave delay measurements. - -It is also possible to generate multicast traffic using RAW streams as shown in the -example below: - -```json -{ - "streams": [ - { - "name": "MC1", - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "network-ipv4-address": "1.1.1.1", - "destination-ipv4-address": "239.0.0.1", - "length": 256, - "pps": 1, - "network-interface": "eth1" - }, - { - "name": "MC2", - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "network-ipv4-address": "2.2.2.2", - "destination-ipv4-address": "239.0.0.2", - "length": 256, - "pps": 1, - "network-interface": "eth2" - } - ] -} -``` - -Using RAW streams allows to generate streams distributed over multiple network interfaces. -Setting the `destination-ipv4-address` to an multicast IPv4 address is enough to generate -proper multicast streams. All headers including the BNG Blaster header will be automatically -set for multicast. Therefore such streams can be also used to measure the IGMP join and leave -delay. - -## Manual Join/Leave Testing - -It is possible to join and leave multicast groups manually using the <> as -shown in the example below. - -`$ sudo bngblaster-cli run.sock igmp-join session-id 1 group 232.1.1.1 source1 202.11.23.101 source2 202.11.23.102 source3 202.11.23.103` - -```json -{ - "status": "ok" -} -``` - -`$ sudo bngblaster-cli run.sock igmp-info session-id 1` - -```json -{ - "status": "ok", - "igmp-groups": [ - { - "group": "232.1.1.1", - "igmp-sources": [ - "202.11.23.101", - "202.11.23.102", - "202.11.23.103" - ], - "packets": 1291, - "loss": 0, - "state": "active", - "join-delay-ms": 139 - } - ] -} -``` - -`$ sudo bngblaster-cli run.sock igmp-leave session-id 1 group 232.1.1.1` - -```json -{ - "status": "ok" -} -``` - -`$ sudo bngblaster-cli run.sock igmp-info session-id 1` - -```json -{ - "status": "ok", - "igmp-groups": [ - { - "group": "232.1.1.1", - "igmp-sources": [ - "202.11.23.101", - "202.11.23.102", - "202.11.23.103" - ], - "packets": 7456, - "loss": 0, - "state": "idle", - "leave-delay-ms": 114 - } - ] -} -``` - -## IPTV Zapping Test - -A key element of IPTV services is the delay in changing channels. -How long does it take to change from one channel to another, is -the right channel received and the old channel stopped without overlap -between old and new channel which may leads into traffic congestions if -both channels are send at the same time. Verify that fast channel changes -(zapping) works reliable as well. - -The BNG Blaster is able to emulate different client zapping behaviors and -measure the resulting join/leave delays and possible multicast traffic loss. - -The join delay is the time in milliseconds between sending join and receiving -first multicast packet of the requested group. The leave delay is the time between -sending leave and the last multicast packet received for this group. Multicast packets -received for the leaved group after first packet of joined group is received are counted -as overlap. - -The following <> output shows an example for the `igmp` section -for a typical zapping test. - -```json -{ - "igmp": { - "version": 3, - "start-delay": 10, - "group": "239.0.0.1", - "group-iter": "0.0.0.1", - "group-count": 20, - "source": "100.0.0.10", - "zapping-interval": 5, - "zapping-count": 5, - "zapping-view-duration": 30, - "zapping-wait": false, - "combined-leave-join": true, - "send-multicast-traffic": true - } -} -``` - -## Multicast Limitations - -The BNG Blaster IGMP implementation supports up to 3 sources per group record -and 8 group records per session. - -The IGMP protocol stops working if IPCP has closed also if session IPCP renegotiates. -The whole session needs to be disconnected to restart IGMP. - -The check for overlapping multicast traffic is supported for zapping tests only. diff --git a/docs/pppoe.md b/docs/pppoe.md deleted file mode 100644 index a4e8ba9b..00000000 --- a/docs/pppoe.md +++ /dev/null @@ -1,181 +0,0 @@ -# PPPoE - -Emulating PPP over Ethernet (PPPoE) sessions was initial -use case of the BNG Blaster supporting 1:1 and N:1 VLAN -mode. - -Following a basic PPPoE configuration example which is -detailed explained in the configuration section. - -```json -{ - "interfaces": { - "network": { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2", - "address-ipv6": "fc66:1337:7331::1", - "gateway-ipv6": "fc66:1337:7331::2" - }, - "access": [ - { - "interface": "eth1", - "type": "pppoe", - "outer-vlan-min": 1000, - "outer-vlan-max": 1999, - "inner-vlan-min": 1, - "inner-vlan-max": 4049, - "authentication-protocol": "PAP" - }, - { - "interface": "eth1", - "type": "pppoe", - "outer-vlan-min": 2000, - "outer-vlan-max": 2999, - "inner-vlan-min": 1, - "inner-vlan-max": 4049, - "authentication-protocol": "CHAP" - } - ] - }, - "sessions": { - "count": 1000, - "session-time": 0, - "max-outstanding": 800, - "start-rate": 400, - "stop-rate": 400 - }, - "pppoe": { - "reconnect": true, - "discovery-timeout": 3, - "discovery-retry": 10 - }, - "ppp": { - "mru": 1492, - "authentication": { - "username": "user{session-global}@rtbrick.com", - "password": "test", - "timeout": 5, - "retry": 30 - }, - "lcp": { - "conf-request-timeout": 1, - "conf-request-retry": 10, - "keepalive-interval": 30, - "keepalive-retry": 3 - }, - "ipcp": { - "enable": true, - "request-ip": true, - "request-dns1": true, - "request-dns2": true, - "conf-request-timeout": 1, - "conf-request-retry": 10 - }, - "ip6cp": { - "enable": true, - "conf-request-timeout": 1, - "conf-request-retry": 10 - } - }, - "dhcpv6": { - "enable": true, - "rapid-commit": true - }, - "access-line": { - "agent-remote-id": "DEU.RTBRICK.{session-global}", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}", - "rate-up": 1024, - "rate-down": 16384 - }, - "session-traffic": { - "ipv4-pps": 1, - "ipv6-pps": 1, - "ipv6pd-pps": 1 - } -} -``` - -## LCP Vendor Extension - -This chapter refers to RFC 2153 PPP vendor extensions. - -Per default all LCP vendor specific requests will be rejected sending a -LCP code reject message. With `ppp->lcp->ignore-vendor-specific` enabled, -those messages will be ignored as required to emulate different CPE -behaviors. - -The option `ppp->lcp->connection-status-message` allows to accept LCP vendor requests -with any OUI if kind is set to `1` by responding with vendor request of -kind `2`. The OUI from request is copied to response in this case. -The value from request is stored in the session as `connection-status-message`. - -## PPPoE Session Information - -The control socket command `session-info session-id ` provides -detailed information for PPPoE sessions. - -`$ sudo bngblaster-cli run.sock session-info session-id 1 | jq .` - -```json -{ - "status": "ok", - "code": 200, - "session-information": { - "type": "pppoe", - "session-id": 1, - "session-state": "Established", - "interface": "eth1", - "outer-vlan": 1000, - "inner-vlan": 1, - "mac": "02:00:00:00:00:01", - "username": "user1@rtbrick.com", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:1", - "agent-remote-id": "DEU.RTBRICK.1", - "lcp-state": "Opened", - "ipcp-state": "Opened", - "ip6cp-state": "Opened", - "ipv4-address": "10.100.128.0", - "ipv4-dns1": "10.0.0.3", - "ipv4-dns2": "10.0.0.4", - "ipv6-prefix": "fc66:1000:1::/64", - "ipv6-delegated-prefix": "fc66:2000::/56", - "ipv6-dns1": "fc66::3", - "ipv6-dns2": "fc66::4", - "dhcpv6-state": "Bound", - "dhcpv6-dns1": "fc66::3", - "dhcpv6-dns2": "fc66::4", - "tx-packets": 10036, - "rx-packets": 10083, - "rx-fragmented-packets": 0, - "session-traffic": { - "total-flows": 6, - "verified-flows": 6, - "first-seq-rx-access-ipv4": 2, - "first-seq-rx-access-ipv6": 3, - "first-seq-rx-access-ipv6pd": 3, - "first-seq-rx-network-ipv4": 2, - "first-seq-rx-network-ipv6": 3, - "first-seq-rx-network-ipv6pd": 3, - "access-tx-session-packets": 3266, - "access-rx-session-packets": 3265, - "access-rx-session-packets-loss": 0, - "network-tx-session-packets": 3266, - "network-rx-session-packets": 3265, - "network-rx-session-packets-loss": 0, - "access-tx-session-packets-ipv6": 3266, - "access-rx-session-packets-ipv6": 3264, - "access-rx-session-packets-ipv6-loss": 0, - "network-tx-session-packets-ipv6": 3266, - "network-rx-session-packets-ipv6": 3264, - "network-rx-session-packets-ipv6-loss": 0, - "access-tx-session-packets-ipv6pd": 3266, - "access-rx-session-packets-ipv6pd": 3264, - "access-rx-session-packets-ipv6pd-loss": 0, - "network-tx-session-packets-ipv6pd": 3266, - "network-rx-session-packets-ipv6pd": 3264, - "network-rx-session-packets-ipv6pd-loss": 0 - } - } -} -``` diff --git a/docs/reports.md b/docs/reports.md deleted file mode 100644 index 2fbc6722..00000000 --- a/docs/reports.md +++ /dev/null @@ -1,412 +0,0 @@ -# Reports - -The BNG Blaster is able to generate detailed result reports -at the end of of the test execution. - -## Standard Output Reports - -```text - - ____ __ ____ _ __ ,/ - / __ \ / /_ / __ ) _____ (_)_____ / /__ ,'/ - / /_/ // __// __ |/ ___// // ___// //_/ ,' / - / _, _// /_ / /_/ // / / // /__ / ,< ,' /_____, - /_/ |_| \__//_____//_/ /_/ \___//_/|_| .'____ ,' - ____ _ _ ______ ____ _ _ / ,' - / __ ) / | / // ____/ / __ ) / /____ _ _____ / /_ ___ ____ / ,' - / __ |/ |/ // / __ / __ |/ // __ `// ___// __// _ \ / ___/ /,' - / /_/ // /| // /_/ / / /_/ // // /_/ /(__ )/ /_ / __// / / - /_____//_/ |_/ \____/ /_____//_/ \__,_//____/ \__/ \___//_/ - -Report: - -Sessions PPPoE: 500 IPoE: 0 -Sessions established: 500/500 -DHCPv6 sessions established: 500 -Setup Time: 396 ms -Setup Rate: 1262.63 CPS (MIN: 1262.63 AVG: 1262.63 MAX: 1262.63) -Flapped: 0 - -Network Interface ( eth2 ): - TX: 25503 packets - RX: 24254 packets - TX Session: 8500 packets - RX Session: 8248 packets (0 loss) - TX Session IPv6: 8500 packets - RX Session IPv6: 8000 packets (0 loss) - TX Session IPv6PD: 8500 packets - RX Session IPv6PD: 8000 packets (0 loss) - TX Multicast: 0 packets - RX Drop Unknown: 1 packets - TX Encode Error: 0 - RX Decode Error: 0 packets - TX Send Failed: 0 - TX No Buffer: 0 - TX Poll Kernel: 0 - RX Poll Kernel: 3932 - -Access Interface ( eth1 ): - TX: 33250 packets - RX: 34047 packets - TX Session: 8500 packets - RX Session: 8248 packets (0 loss, 0 wrong session) - TX Session IPv6: 8500 packets - RX Session IPv6: 8000 packets (0 loss, 0 wrong session) - TX Session IPv6PD: 8500 packets - RX Session IPv6PD: 8000 packets (0 loss, 0 wrong session) - RX Multicast: 0 packets (0 loss) - RX Drop Unknown: 1 packets - TX Encode Error: 33250 packets - RX Decode Error: 0 packets - TX Send Failed: 0 - TX No Buffer: 0 - TX Poll Kernel: 0 - RX Poll Kernel: 3932 - - Access Interface Protocol Packet Stats: - ARP TX: 0 RX: 0 - PADI TX: 500 RX: 0 - PADO TX: 0 RX: 500 - PADR TX: 500 RX: 0 - PADS TX: 0 RX: 500 - PADT TX: 1 RX: 499 - LCP TX: 2249 RX: 2249 - PAP TX: 250 RX: 250 - CHAP TX: 250 RX: 500 - IPCP TX: 1500 RX: 1500 - IP6CP TX: 1500 RX: 1500 - IGMP TX: 0 RX: 1298 - ICMP TX: 0 RX: 0 - ICMPv6 TX: 500 RX: 500 - DHCPv6 TX: 500 RX: 500 - - Access Interface Protocol Timeout Stats: - LCP Echo Request: 0 - LCP Request: 0 - IPCP Request: 0 - IP6CP Request: 0 - PAP: 0 - CHAP: 0 - ICMPv6 RS: 0 - DHCPv6 Request: 0 - -Session Traffic: - Config: - IPv4 PPS: 1 - IPv6 PPS: 1 - IPv6PD PPS: 1 - Verified Traffic Flows: 3000/3000 - Access IPv4: 500 - Access IPv6: 500 - Access IPv6PD: 500 - Network IPv4: 500 - Network IPv6: 500 - Network IPv6PD: 500 - First Sequence Number Received: - Access IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) - Access IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) - Access IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) - Network IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) - Network IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) - Network IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) -``` - -## JSON Reports - -A detailed JSON report is generated if enabled using the optional argument `-J ` -as shown in the example below. - -```json -{ - "report": { - "sessions": 500, - "sessions-pppoe": 500, - "sessions-ipoe": 0, - "sessions-established": 500, - "sessions-flapped": 0, - "setup-time-ms": 396, - "setup-rate-cps": 1263, - "setup-rate-cps-min": 1263, - "setup-rate-cps-avg": 1263, - "setup-rate-cps-max": 1263, - "dhcpv6-sessions-established": 500, - "network-interfaces": [ - { - "name": "eth2", - "tx-packets": 25503, - "rx-packets": 24254, - "tx-session-packets": 8500, - "rx-session-packets": 8248, - "rx-session-packets-loss": 0, - "tx-session-packets-avg-pps-max": 500, - "rx-session-packets-avg-pps-max": 500, - "tx-session-packets-ipv6": 8500, - "rx-session-packets-ipv6": 8000, - "rx-session-packets-ipv6-loss": 0, - "tx-session-packets-avg-pps-max-ipv6": 500, - "rx-session-packets-avg-pps-max-ipv6": 500, - "tx-session-packets-ipv6pd": 8500, - "rx-session-packets-ipv6pd": 8000, - "rx-session-packets-ipv6pd-loss": 0, - "tx-session-packets-avg-pps-max-ipv6pd": 500, - "rx-session-packets-avg-pps-max-ipv6pd": 500, - "tx-multicast-packets": 0 - } - ], - "access-interfaces": [ - { - "name": "eth1", - "tx-packets": 33250, - "rx-packets": 34047, - "tx-session-packets": 8500, - "rx-session-packets": 8248, - "rx-session-packets-loss": 0, - "rx-session-packets-wrong-session": 0, - "tx-session-packets-avg-pps-max": 500, - "rx-session-packets-avg-pps-max": 500, - "tx-session-packets-ipv6": 8500, - "rx-session-packets-ipv6": 8000, - "rx-session-packets-ipv6-loss": 0, - "rx-session-packets-ipv6-wrong-session": 0, - "tx-session-packets-avg-pps-max-ipv6": 500, - "rx-session-packets-avg-pps-max-ipv6": 500, - "tx-session-packets-ipv6pd": 8500, - "rx-session-packets-ipv6pd": 8000, - "rx-session-packets-ipv6pd-loss": 0, - "rx-session-packets-ipv6pd-wrong-session": 0, - "tx-session-packets-avg-pps-max-ipv6pd": 500, - "rx-session-packets-avg-pps-max-ipv6pd": 500, - "rx-multicast-packets": 0, - "rx-multicast-packets-loss": 0, - "protocol-stats": { - "arp-tx": 0, - "arp-rx": 0, - "padi-tx": 500, - "pado-rx": 500, - "padr-tx": 500, - "pads-rx": 500, - "padt-tx": 1, - "padt-rx": 499, - "lcp-tx": 2249, - "lcp-rx": 2249, - "pap-tx": 250, - "pap-rx": 250, - "chap-tx": 250, - "chap-rx": 500, - "ipcp-tx": 1500, - "ipcp-rx": 1500, - "ip6cp-tx": 1500, - "ip6cp-rx": 1500, - "igmp-tx": 0, - "igmp-rx": 1298, - "icmp-tx": 0, - "icmp-rx": 0, - "icmpv6-tx": 500, - "icmpv6-rx": 500, - "dhcpv6-tx": 500, - "dhcpv6-rx": 500, - "lcp-echo-timeout": 0, - "lcp-request-timeout": 0, - "ipcp-request-timeout": 0, - "ip6cp-request-timeout": 0, - "pap-timeout": 0, - "chap-timeout": 0, - "icmpv6-rs-timeout": 0, - "dhcpv6-timeout": 0 - } - } - ], - "session-traffic": { - "config-ipv4-pps": 1, - "config-ipv6-pps": 1, - "config-ipv6pd-pps": 1, - "total-flows": 3000, - "verified-flows": 3000, - "verified-flows-access-ipv4": 500, - "verified-flows-access-ipv6": 500, - "verified-flows-access-ipv6pd": 500, - "verified-flows-network-ipv4": 500, - "verified-flows-network-ipv6": 500, - "verified-flows-network-ipv6pd": 500, - "first-seq-rx-access-ipv4-min": 1, - "first-seq-rx-access-ipv4-max": 2, - "first-seq-rx-access-ipv6-min": 2, - "first-seq-rx-access-ipv6-max": 2, - "first-seq-rx-access-ipv6pd-min": 2, - "first-seq-rx-access-ipv6pd-max": 2, - "first-seq-rx-network-ipv4-min": 1, - "first-seq-rx-network-ipv4-max": 2, - "first-seq-rx-network-ipv6-min": 2, - "first-seq-rx-network-ipv6-max": 2, - "first-seq-rx-network-ipv6pd-min": 2, - "first-seq-rx-network-ipv6pd-max": 2 - } - } -} -``` - -The optional argument `-j sessions` allows to include per session statistics -in the report file. Similar with `-j streams` which allows to include per stream -statistics. Both options could be also combined. - -## Interface Statistics - -## Session Traffic Statistics - -Those statistics are related to the test traffic send between PPPoE sessions -and the network interface. - -Flow | Description ----- | ----------- -Access RX | Network traffic received on access interface (downstream) -Access TX | Network traffic send from access interface (Upstream) -Network RX | Access traffic received on network interface (Upstream) -Network TX | Access traffic send from network interface (downstream) - -### Verified Traffic Flows - -Counts the verified traffic flows per type and direction. - -The `Access IPv4` tells how many sessions have successfully received -session verification traffic IPv4 traffic on the access interface. Similar -for IPv6 or IPv6PD (prefix delegation). Session verification traffic received -on the network interface is counted similar using the `Network IP...` statistics. - -Assuming session traffic is enabled for IPv4, IPv6 and IPv6PD, in this case -all statics should be equal matching the number of sessions. - -*Example report output for 100 sessions:* - -```text -Session Traffic: - Config: - IPv4 PPS: 1 - IPv6 PPS: 1 - IPv6PD PPS: 1 - Verified Traffic Flows: 3000/3000 - Access IPv4: 500 - Access IPv6: 500 - Access IPv6PD: 500 - Network IPv4: 500 - Network IPv6: 500 - Network IPv6PD: 500 - First Sequence Number Received: - Access IPv4 MIN: 1 MAX: 2 - Access IPv6 MIN: 2 MAX: 2 - Access IPv6PD MIN: 2 MAX: 2 - Network IPv4 MIN: 1 MAX: 2 - Network IPv6 MIN: 2 MAX: 2 - Network IPv6PD MIN: 2 MAX: 2 -``` - -JSON: - -```json -{ - "session-traffic": { - "config-ipv4-pps": 1, - "config-ipv6-pps": 1, - "config-ipv6pd-pps": 1, - "total-flows": 3000, - "verified-flows": 3000, - "verified-flows-access-ipv4": 500, - "verified-flows-access-ipv6": 500, - "verified-flows-access-ipv6pd": 500, - "verified-flows-network-ipv4": 500, - "verified-flows-network-ipv6": 500, - "verified-flows-network-ipv6pd": 500, - "first-seq-rx-access-ipv4-min": 1, - "first-seq-rx-access-ipv4-max": 2, - "first-seq-rx-access-ipv6-min": 2, - "first-seq-rx-access-ipv6-max": 2, - "first-seq-rx-access-ipv6pd-min": 2, - "first-seq-rx-access-ipv6pd-max": 2, - "first-seq-rx-network-ipv4-min": 1, - "first-seq-rx-network-ipv4-max": 2, - "first-seq-rx-network-ipv6-min": 2, - "first-seq-rx-network-ipv6-max": 2, - "first-seq-rx-network-ipv6pd-min": 2, - "first-seq-rx-network-ipv6pd-max": 2 - } -} -``` - -The flow verification status can be also queried via -global control socket command `session-traffic`. - -`$ cat command.json | jq .` - -```json -{ - "command": "session-traffic" -} -``` - -`$ cat command.json | sudo nc -U test.socket | jq .` - -```json -{ - "status": "ok", - "code": 200, - "session-traffic": { - "total-flows": 3000, - "verified-flows": 3000 - } -} -``` - -### First Sequence Number Received - -If session traffic is enabled, the BNG Blaster will start sending bidirectional -traffic between PPPoE session and network interface as soon as the session is -established using the rate as configured starting with sequence number 1 for -each flow. - -*Example config output with 1 packet per second:* - -```json -{ - "session-traffic": { - "ipv4-pps": 1, - "ipv6-pps": 1, - "ipv6pd-pps": 1 - } -} -``` - -Assuming the first sequence number received for given flow is 5 -combined with a rate of 1 PPS would mean that it took between 4 -and 5 seconds until forwarding is working. - -*Example report output with 1 packet per second:* - -```text -STDOUT: - - First Sequence Number Received: - Access IPv4 MIN: 1 MAX: 1 - Access IPv6 MIN: 1 MAX: 1 - Access IPv6PD MIN: 1 MAX: 1 - Network IPv4 MIN: 1 MAX: 1 - Network IPv6 MIN: 1 MAX: 1 - Network IPv6PD MIN: 1 MAX: 1 -``` - -JSON: - -```json -{ - "first-seq-rx-access-ipv4-min": 1, - "first-seq-rx-access-ipv4-max": 1, - "first-seq-rx-access-ipv6-min": 1, - "first-seq-rx-access-ipv6-max": 1, - "first-seq-rx-access-ipv6pd-min": 1, - "first-seq-rx-access-ipv6pd-max": 1, - "first-seq-rx-network-ipv4-min": 1, - "first-seq-rx-network-ipv4-max": 1, - "first-seq-rx-network-ipv6-min": 1, - "first-seq-rx-network-ipv6-max": 1, - "first-seq-rx-network-ipv6pd-min": 1, - "first-seq-rx-network-ipv6pd-max": 1 -} -``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..b334d495 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +sphinx-rtd-theme +sphinx-tabs \ No newline at end of file diff --git a/docs/source/access/index.rst b/docs/source/access/index.rst new file mode 100644 index 00000000..84977079 --- /dev/null +++ b/docs/source/access/index.rst @@ -0,0 +1,13 @@ +Access Protocols +================ + +.. toctree:: + :maxdepth: 1 + + pppoe.rst + ipoe.rst + l2tp.rst + l2bsa.rst + traffic.rst + multicast.rst + li.rst diff --git a/docs/source/access/ipoe.rst b/docs/source/access/ipoe.rst new file mode 100644 index 00000000..ee5e56e3 --- /dev/null +++ b/docs/source/access/ipoe.rst @@ -0,0 +1,169 @@ +.. _ipoe: + +IPoE +---- + +The BNG Blaster is able to emulate IP over Ethernet (IPoE) +subscribers with static and dynamic address assignment +supporting 1:1 and N:1 VLAN mode. + +Static Addresses +~~~~~~~~~~~~~~~~ + +Static addresses means that the IP address and gateway is assigned +statically as shown in the example below. + +.. code-block:: json + + { + "interfaces": { + "access": [ + { + "interface": "eth1", + "type": "ipoe", + "vlan-mode": "1:1", + "outer-vlan-min": 128, + "outer-vlan-max": 4000, + "address": "200.0.0.1", + "address-iter": "0.0.0.4", + "gateway": "200.0.0.2", + "gateway-iter": "0.0.0.4", + } + ] + } + } + +DHCPv4/v6 +~~~~~~~~~ + +The most common case for IPoE is using DHCPv4/v6 as shown below. + +.. code-block:: json + + { + "interfaces": { + "access": [ + { + "interface": "eth1", + "type": "ipoe", + "outer-vlan": 7, + "vlan-mode": "N:1" + } + ] + }, + "dhcp": { + "enable": true, + }, + "dhcpv6": { + "enable": true + }, + "access-line": { + "agent-remote-id": "DEU.RTBRICK.{session-global}", + "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}" + } + } + +IPoE +^^^^^ +.. include:: ../configuration/ipoe.rst + +DHCP +^^^^ +.. include:: ../configuration/dhcp.rst + +DHCPv6 +^^^^^^ +.. include:: ../configuration/dhcpv6.rst + +IPoE Commands +~~~~~~~~~~~~~ + +The control socket command ``session-info session-id `` provides +detailed information for IPoE sessions. + +``$ sudo bngblaster-cli run.sock session-info session-id 1 | jq .`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "session-information": { + "type": "ipoe", + "session-id": 1, + "session-state": "Established", + "interface": "eth1", + "outer-vlan": 8, + "inner-vlan": 1, + "mac": "02:00:00:00:00:01", + "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:1", + "agent-remote-id": "DEU.RTBRICK.1", + "ipv4-address": "1.1.1.3", + "ipv4-netmask": "255.255.255.255", + "ipv4-gateway": "1.1.1.1", + "ipv4-dns1": "10.0.0.3", + "ipv4-dns2": "10.0.0.4", + "ipv6-prefix": "fc66:1337:2222::3/128", + "ipv6-delegated-prefix": "fc66:1337:3333:2::/64", + "dhcp-state": "Bound", + "dhcp-server": "1.1.1.1", + "dhcp-lease-time": 300, + "dhcp-lease-expire": 299, + "dhcp-lease-expire-t1": 149, + "dhcp-lease-expire-t2": 261, + "dhcp-tx": 2, + "dhcp-rx": 2, + "dhcp-tx-discover": 1, + "dhcp-rx-offer": 1, + "dhcp-tx-request": 1, + "dhcp-rx-ack": 1, + "dhcp-rx-nak": 0, + "dhcp-tx-release": 0, + "dhcpv6-state": "Bound", + "dhcpv6-lease-time": 14400, + "dhcpv6-lease-expire": 14399, + "dhcpv6-lease-expire-t1": 899, + "dhcpv6-lease-expire-t2": 1439, + "dhcpv6-tx": 1, + "dhcpv6-rx": 1, + "dhcpv6-tx-solicit": 1, + "dhcpv6-rx-advertise": 0, + "dhcpv6-tx-request": 0, + "dhcpv6-rx-reply": 1, + "dhcpv6-tx-renew": 0, + "dhcpv6-tx-release": 0, + "dhcpv6-dns1": "fc66::3", + "dhcpv6-dns2": "fc66::4", + "tx-packets": 6, + "rx-packets": 6, + "rx-fragmented-packets": 0, + "session-traffic": { + "total-flows": 6, + "verified-flows": 0, + "first-seq-rx-access-ipv4": 0, + "first-seq-rx-access-ipv6": 0, + "first-seq-rx-access-ipv6pd": 0, + "first-seq-rx-network-ipv4": 0, + "first-seq-rx-network-ipv6": 0, + "first-seq-rx-network-ipv6pd": 0, + "access-tx-session-packets": 0, + "access-rx-session-packets": 0, + "access-rx-session-packets-loss": 0, + "network-tx-session-packets": 0, + "network-rx-session-packets": 0, + "network-rx-session-packets-loss": 0, + "access-tx-session-packets-ipv6": 0, + "access-rx-session-packets-ipv6": 0, + "access-rx-session-packets-ipv6-loss": 0, + "network-tx-session-packets-ipv6": 0, + "network-rx-session-packets-ipv6": 0, + "network-rx-session-packets-ipv6-loss": 0, + "access-tx-session-packets-ipv6pd": 0, + "access-rx-session-packets-ipv6pd": 0, + "access-rx-session-packets-ipv6pd-loss": 0, + "network-tx-session-packets-ipv6pd": 0, + "network-rx-session-packets-ipv6pd": 0, + "network-rx-session-packets-ipv6pd-loss": 0 + } + } + } diff --git a/docs/source/access/l2bsa.rst b/docs/source/access/l2bsa.rst new file mode 100644 index 00000000..e3578037 --- /dev/null +++ b/docs/source/access/l2bsa.rst @@ -0,0 +1,76 @@ +.. _l2bsa: + +L2BSA +----- + +The A10NSP interface emulates an layer two provider interface. The term A10 +refers to the end-to-end ADSL network reference model from TR-025. + +Following a basic PPPoE/A10NSP configuration example which is +detailed explained in the configuration section. + +.. code-block:: json + + { + "interfaces": { + "a10nsp": [ + { + "interface": "eth4", + "qinq": true, + "mac": "02:00:00:ff:ff:01" + }, + { + "interface": "eth5", + "qinq": true, + "mac": "02:00:00:ff:ff:01" + } + ], + "access": [ + { + "__comment__": "PPPoE", + "interface": "eth1", + "type": "pppoe", + "outer-vlan-min": 1, + "outer-vlan-max": 4000, + "inner-vlan": 7, + "stream-group-id": 1 + } + ] + }, + "pppoe": { + "reconnect": true, + "discovery-timeout": 3, + "discovery-retry": 10, + "host-uniq": true, + "vlan-priority": 6 + }, + "dhcpv6": { + "enable": false + }, + "session-traffic": { + "autostart": true, + "ipv4-pps": 10 + }, + "streams": [ + { + "stream-group-id": 2, + "name": "PPPOE-S1", + "type": "ipv4", + "direction": "both", + "priority": 128, + "length": 256, + "pps": 10, + "a10nsp-interface": "eth4" + }, + { + "stream-group-id": 2, + "name": "PPPOE-S2", + "type": "ipv4", + "direction": "both", + "priority": 128, + "length": 256, + "pps": 10, + "a10nsp-interface": "eth5" + } + ] + } diff --git a/docs/source/access/l2tp.rst b/docs/source/access/l2tp.rst new file mode 100644 index 00000000..6269fede --- /dev/null +++ b/docs/source/access/l2tp.rst @@ -0,0 +1,400 @@ +.. _l2tp: + +L2TP +---- + +The BNG Blaster is able to emulate L2TPv2 (RFC2661) LNS servers to +be able to test the L2TPv2 LAC functionality of the BNG device under +test. + +Configuration +~~~~~~~~~~~~~ + +Following an example with 30 L2TP LNS servers. + +.. code-block:: json + + { + "interfaces": { + "network": { + "interface": "eth2", + "address": "10.0.0.1", + "gateway": "10.0.0.2", + "address-ipv6": "fc66:1337:7331:8::10", + "gateway-ipv6": "fc66:1337:7331:8::1" + }, + "access": [ + { + "interface": "eth1", + "outer-vlan-min": 1, + "outer-vlan-max": 4000, + "inner-vlan-min": 7, + "inner-vlan-max": 7, + "authentication-protocol": "PAP" + }, + { + "interface": "eth1", + "outer-vlan-min": 1, + "outer-vlan-max": 4000, + "inner-vlan-min": 8, + "inner-vlan-max": 8, + "authentication-protocol": "CHAP" + } + ] + }, + "pppoe": { + "reconnect": true, + "discovery-timeout": 3, + "discovery-retry": 10 + }, + "ppp": { + "mru": 1492, + "authentication": { + "username": "blaster@l2tp.de", + "password": "test", + "timeout": 1, + "retry": 60 + }, + "lcp": { + "conf-request-timeout": 5, + "conf-request-retry": 30, + "keepalive-interval": 30, + "keepalive-retry": 3 + }, + "ipcp": { + "enable": true + }, + "ip6cp": { + "enable": true + } + }, + "access-line": { + "agent-remote-id": "DEU.RTBRICK.{session}", + "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session}", + "rate-up": 1024, + "rate-down": 16384 + }, + "l2tp-server": [ + { + "name": "LNS1", + "address": "10.0.0.11", + "secret": "test1", + "receive-window-size": 8 + }, + { + "name": "LNS2", + "address": "10.0.0.12", + "secret": "test2", + "receive-window-size": 8 + }, + { + "name": "LNS3", + "address": "10.0.0.13", + "secret": "test3", + "receive-window-size": 8 + }, + { + "name": "LNS4", + "address": "10.0.0.14", + "secret": "test4", + "receive-window-size": 8 + }, + { + "name": "LNS5", + "address": "10.0.0.15", + "secret": "test5", + "receive-window-size": 8 + }, + { + "name": "LNS6", + "address": "10.0.0.16", + "secret": "test6", + "receive-window-size": 8 + }, + { + "name": "LNS7", + "address": "10.0.0.17", + "secret": "test7", + "receive-window-size": 8 + }, + { + "name": "LNS8", + "address": "10.0.0.18", + "secret": "test8", + "receive-window-size": 8 + }, + { + "name": "LNS9", + "address": "10.0.0.19", + "secret": "test9", + "receive-window-size": 8 + }, + { + "name": "LNS10", + "address": "10.0.0.20", + "secret": "test10", + "receive-window-size": 8 + }, + { + "name": "LNS11", + "address": "10.0.0.21", + "secret": "test11", + "receive-window-size": 8 + }, + { + "name": "LNS12", + "address": "10.0.0.22", + "secret": "test12", + "receive-window-size": 8 + }, + { + "name": "LNS13", + "address": "10.0.0.23", + "secret": "test13", + "receive-window-size": 8 + }, + { + "name": "LNS14", + "address": "10.0.0.24", + "secret": "test14", + "receive-window-size": 8 + }, + { + "name": "LNS15", + "address": "10.0.0.25", + "secret": "test15", + "receive-window-size": 8 + }, + { + "name": "LNS16", + "address": "10.0.0.26", + "secret": "test16", + "receive-window-size": 8 + }, + { + "name": "LNS17", + "address": "10.0.0.27", + "secret": "test17", + "receive-window-size": 8 + }, + { + "name": "LNS18", + "address": "10.0.0.28", + "secret": "test18", + "receive-window-size": 8 + }, + { + "name": "LNS19", + "address": "10.0.0.29", + "secret": "test19", + "receive-window-size": 8 + }, + { + "name": "LNS20", + "address": "10.0.0.30", + "secret": "test20", + "receive-window-size": 8 + }, + { + "name": "LNS21", + "address": "10.0.0.31", + "secret": "test21", + "receive-window-size": 8 + }, + { + "name": "LNS22", + "address": "10.0.0.32", + "secret": "test22", + "receive-window-size": 8 + }, + { + "name": "LNS23", + "address": "10.0.0.33", + "secret": "test23", + "receive-window-size": 8 + }, + { + "name": "LNS24", + "address": "10.0.0.34", + "secret": "test24", + "receive-window-size": 8 + }, + { + "name": "LNS25", + "address": "10.0.0.35", + "secret": "test25", + "receive-window-size": 8 + }, + { + "name": "LNS26", + "address": "10.0.0.36", + "secret": "test26", + "receive-window-size": 8 + }, + { + "name": "LNS27", + "address": "10.0.0.37", + "secret": "test27", + "receive-window-size": 8 + }, + { + "name": "LNS28", + "address": "10.0.0.38", + "secret": "test28", + "receive-window-size": 8 + }, + { + "name": "LNS29", + "address": "10.0.0.39", + "secret": "test29", + "receive-window-size": 8 + }, + { + "name": "LNS30", + "address": "10.0.0.40", + "secret": "test30", + "receive-window-size": 8 + } + ], + "session-traffic": { + "autostart": true, + "ipv4-pps": 1 + } + } + +.. include:: ../configuration/lns.rst + +Variable Data Header +~~~~~~~~~~~~~~~~~~~~ + +The L2TP protocol allows different data header options resulting in +variable header lengths. The most common options can be tested with just +four servers as shown in the example below. + +.. code-block:: json + + { + "l2tp-server": [ + { + "name": "LNS1", + "address": "10.0.0.11", + "secret": "test1", + "receive-window-size": 8, + "congestion-mode": "default", + "data-control-priority": true + }, + { + "name": "LNS2", + "address": "10.0.0.12", + "secret": "test2", + "receive-window-size": 8, + "congestion-mode": "default", + "data-control-priority": true, + "data-length": true + }, + { + "name": "LNS3", + "address": "10.0.0.11", + "secret": "test3", + "receive-window-size": 8, + "congestion-mode": "default", + "data-control-priority": true, + "data-offset": true + }, + { + "name": "LNS4", + "address": "10.0.0.12", + "secret": "test4", + "receive-window-size": 8, + "congestion-mode": "default", + "data-control-priority": true, + "data-length": true, + "data-offset": true + } + ] + } + +RFC5515 +~~~~~~~ + +The Agent-Circuit-Id and Agent-Remote-Id AVP defined in RFC5515 +is supported and stored for each session if received. Received +CSUN messages are processed correctly and via control socket it +is possible to send also CSURQ requests to the LAC. + +L2TP Commands +~~~~~~~~~~~~~ + +The control socket command ``session-info l2tp-tunnels`` provides +detailed information about L2TP tunnels. + +``$ sudo bngblaster-cli run.sock l2tp-tunnels`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "l2tp-tunnels": [ + { + "state": "Established", + "server-name": "LNS1", + "server-address": "10.0.0.11", + "tunnel-id": 1, + "peer-tunnel-id": 50011, + "peer-name": "BNG", + "peer-address": "10.0.0.2", + "peer-vendor": "RtBrick, Inc.", + "secret": "test1", + "control-packets-rx": 102, + "control-packets-rx-dup": 0, + "control-packets-rx-out-of-order": 0, + "control-packets-tx": 102, + "control-packets-tx-retry": 0, + "data-packets-rx": 1406, + "data-packets-tx": 206 + } + ] + } + +The ``l2tp-sessions`` command returns all L2TP sessions. + +``$ sudo bngblaster-cli run.sock l2tp-sessions`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "l2tp-sessions": [ + { + "state": "Established", + "tunnel-id": 1, + "session-id": 1, + "peer-tunnel-id": 50011, + "peer-session-id": 32867, + "peer-proxy-auth-name": "blaster@l2tp.de", + "peer-called-number": "N/A", + "peer-calling-number": "N/A", + "peer-sub-address": "N/A", + "peer-tx-bps": 48000, + "peer-rx-bps": 1000, + "peer-ari": "DEU.RTBRICK.1", + "peer-aci": "0.0.0.0/0.0.0.0 eth 0:1", + "data-packets-rx": 79, + "data-packets-tx": 79, + "data-ipv4-packets-rx": 15, + "data-ipv4-packets-tx": 15 + } + ] + } + +This output can be also filtered to return only sessions +of a given tunnel. + +``sudo bngblaster-cli run.sock l2tp-sessions tunnel-id 1`` + +It is also possible to display a single session. + +``$ sudo bngblaster-cli run.sock l2tp-sessions tunnel-id 1 session-id 1`` + diff --git a/docs/source/access/li.rst b/docs/source/access/li.rst new file mode 100644 index 00000000..6c5cbdfb --- /dev/null +++ b/docs/source/access/li.rst @@ -0,0 +1,96 @@ +.. _li: + +Legal Interception (LI) +----------------------- + +The BNG Blaster can be used to emulate a mediation device providing detailed statistics +about the received flows. Today only the BCM QMX LI header format is supported but further +headers can be easily integrated. + +*BCM QMX LI Header Format* + +.. code-block:: none + + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | D | PT | SPT | LIID | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +The functionality is automatically enabled on the network interface +and works combined with sessions in one instance or as standalone +mediation device as shown in the following example. + +.. code-block:: json + + { + "interfaces": { + "tx-interval": 10, + "rx-interval": 1, + "network": { + "interface": "eth2", + "address": "100.0.0.10/24", + "gateway": "100.0.0.2" + } + } + } + +The received flows can be displayed with the command `li-flows`. + +``$ sudo bngblaster-cli run.sock li-flows`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "li-flows": [ + { + "source-address": "1.1.1.1", + "source-port": 49152, + "destination-address": "1.1.1.2", + "destination-port": 49152, + "direction": "downstream", + "packet-type": "ethernet", + "sub-packet-type": "double-tagged", + "liid": 4194301, + "bytes-rx": 94, + "packets-rx": 1, + "packets-rx-ipv4": 0, + "packets-rx-ipv4-tcp": 0, + "packets-rx-ipv4-udp": 0, + "packets-rx-ipv4-host-internal": 0, + "packets-rx-ipv6": 0, + "packets-rx-ipv6-tcp": 0, + "packets-rx-ipv6-udp": 0, + "packets-rx-ipv6-host-internal": 0, + "packets-rx-ipv6-no-next-header": 0 + }, + { + "source-address": "1.1.1.1", + "source-port": 49152, + "destination-address": "1.1.1.2", + "destination-port": 49152, + "direction": "upstream", + "packet-type": "ethernet", + "sub-packet-type": "double-tagged", + "liid": 4194301, + "bytes-rx": 160720, + "packets-rx": 820, + "packets-rx-ipv4": 820, + "packets-rx-ipv4-tcp": 0, + "packets-rx-ipv4-udp": 0, + "packets-rx-ipv4-host-internal": 820, + "packets-rx-ipv6": 0, + "packets-rx-ipv6-tcp": 0, + "packets-rx-ipv6-udp": 0, + "packets-rx-ipv6-host-internal": 0, + "packets-rx-ipv6-no-next-header": 0 + } + ] + } + +The ``packets-rx-ipv4-host-internal`` refers to the IPv4 protocol number 61 +(any host internal protocol) which is used by some network testers as default +type for traffic streams. The same is valid for ``packets-rx-ipv6-host-internal`` +which refers to next header 61 and ``packets-rx-ipv6-no-next-header`` with next +header 59. diff --git a/docs/source/access/multicast.rst b/docs/source/access/multicast.rst new file mode 100644 index 00000000..8e3f2326 --- /dev/null +++ b/docs/source/access/multicast.rst @@ -0,0 +1,217 @@ +.. _multicast: + +Multicast and IPTV +------------------ + +The BNG Blaster provides advanced functionalities for testing multicast +over PPPoE sessions with focus on IPTV. Therefore IGMP version 1, 2 and 3 +is implemented with support for up to 8 group records per session and 3 +sources per group. + +Multicast testing is supported using external multicast traffic like real +world IPTV traffic or by generating multicast traffic on the network interface. + +Generate Multicast Traffic +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The BNG Blaster supports different ways to generate multicast traffic. The first +one is via igmp configuration and second one using raw streams. + +The following example shows how to generate traffic for 100 multicast groups +with one packet per millisecond for every group. + +.. code-block:: json + + { + "interfaces": { + "tx-interval": 1.0, + "rx-interval": 1.0, + "network": { + "interface": "eth2", + "address": "100.0.0.10", + "gateway": "100.0.0.2" + } + }, + "igmp": { + "group": "239.0.0.1", + "group-iter": "0.0.0.1", + "group-count": 100, + "source": "100.0.0.10", + "send-multicast-traffic": true + } + } + +It is recommended to send multicast traffic with 1000 PPS per group +to measure the join and leave delay in milliseconds. Therefore the +``tx-interval`` and ``rx-interval`` should be set to at to at least +`1.0` (1ms) for more precise IGMP join/leave delay measurements. + +It is also possible to generate multicast traffic using RAW streams as shown in the +example below: + +.. code-block:: json + + { + "streams": [ + { + "name": "MC1", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "network-ipv4-address": "1.1.1.1", + "destination-ipv4-address": "239.0.0.1", + "length": 256, + "pps": 1, + "network-interface": "eth1" + }, + { + "name": "MC2", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "network-ipv4-address": "2.2.2.2", + "destination-ipv4-address": "239.0.0.2", + "length": 256, + "pps": 1, + "network-interface": "eth2" + } + ] + } + +Using RAW streams allows to generate streams distributed over multiple network interfaces +with higher transmit rate using threaded streams if needed. + +Setting the ``destination-ipv4-address`` to an multicast IPv4 address is enough to generate +proper multicast streams. All headers including the BNG Blaster header will be automatically +set for multicast. Therefore such streams can be also used to measure the IGMP join and leave +delay. + +The BNG Blaster is recognizing loss using the :ref:`BNG Blaster header ` +sequence numbers. After first multicast traffic is received for a particular group, +for every further packet it checks if there is a gap between last and new sequence number +which is than reported as loss. The argument option ``-l loss`` enables loss logging which +allows to search for the missing packets in the corresponding capture files. + +.. tip:: + It is also possible to start a dedicated BNG Blaster instance to generate multicast + traffic which can be consumed by multiple BNG Blaster instances. The BNG Blaster + header allows to do the same measurements on traffic generated from same or different + BNG Blaster instance. + +Manual Join/Leave Testing +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to join and leave multicast groups manually using the <> as +shown in the example below. + +``$ sudo bngblaster-cli run.sock igmp-join session-id 1 group 232.1.1.1 source1 202.11.23.101 source2 202.11.23.102 source3 202.11.23.103`` + +.. code-block:: json + + { + "status": "ok" + } + +``$ sudo bngblaster-cli run.sock igmp-info session-id 1`` + +.. code-block:: json + + { + "status": "ok", + "igmp-groups": [ + { + "group": "232.1.1.1", + "igmp-sources": [ + "202.11.23.101", + "202.11.23.102", + "202.11.23.103" + ], + "packets": 1291, + "loss": 0, + "state": "active", + "join-delay-ms": 139 + } + ] + } + +``$ sudo bngblaster-cli run.sock igmp-leave session-id 1 group 232.1.1.1`` + +.. code-block:: json + + { + "status": "ok" + } + +``$ sudo bngblaster-cli run.sock igmp-info session-id 1`` + +.. code-block:: json + + { + "status": "ok", + "igmp-groups": [ + { + "group": "232.1.1.1", + "igmp-sources": [ + "202.11.23.101", + "202.11.23.102", + "202.11.23.103" + ], + "packets": 7456, + "loss": 0, + "state": "idle", + "leave-delay-ms": 114 + } + ] + } + +IPTV Zapping Test +~~~~~~~~~~~~~~~~~ + +A key element of IPTV services is the delay in changing channels. +How long does it take to change from one channel to another, is +the right channel received and the old channel stopped without overlap +between old and new channel which may leads into traffic congestions if +both channels are send at the same time. Verify that fast channel changes +(zapping) works reliable as well. + +The BNG Blaster is able to emulate different client zapping behaviors and +measure the resulting join/leave delays and possible multicast traffic loss. + +The join delay is the time in milliseconds between sending join and receiving +first multicast packet of the requested group. The leave delay is the time between +sending leave and the last multicast packet received for this group. Multicast packets +received for the leaved group after first packet of joined group is received are counted +as overlap. + +The following configuration shows an example of the `igmp` section +for a typical zapping test. + +.. code-block:: json + + { + "igmp": { + "version": 3, + "start-delay": 10, + "group": "239.0.0.1", + "group-iter": "0.0.0.1", + "group-count": 20, + "source": "100.0.0.10", + "zapping-interval": 5, + "zapping-count": 5, + "zapping-view-duration": 30, + "zapping-wait": false, + "combined-leave-join": true, + "send-multicast-traffic": true + } + } + +Multicast Limitations +~~~~~~~~~~~~~~~~~~~~~ + +The BNG Blaster IGMP implementation supports up to 3 sources per group record +and 8 group records per session. + +The IGMP protocol stops working if IPCP has closed also if session IPCP renegotiates. +The whole session needs to be disconnected to restart IGMP. + +The check for overlapping multicast traffic is supported for zapping tests only. diff --git a/docs/source/access/pppoe.rst b/docs/source/access/pppoe.rst new file mode 100644 index 00000000..1e59b58f --- /dev/null +++ b/docs/source/access/pppoe.rst @@ -0,0 +1,213 @@ +.. _pppoe: + +PPPoE +----- + +Emulating PPP over Ethernet (PPPoE) sessions was initial +use case of the BNG Blaster supporting 1:1 and N:1 VLAN +mode. + +Configuration +~~~~~~~~~~~~~ + +Following a basic PPPoE configuration example. + +.. code-block:: json + + { + "interfaces": { + "network": { + "interface": "eth2", + "address": "10.0.0.1", + "gateway": "10.0.0.2", + "address-ipv6": "fc66:1337:7331::1", + "gateway-ipv6": "fc66:1337:7331::2" + }, + "access": [ + { + "interface": "eth1", + "type": "pppoe", + "outer-vlan-min": 1000, + "outer-vlan-max": 1999, + "inner-vlan-min": 1, + "inner-vlan-max": 4049, + "authentication-protocol": "PAP" + }, + { + "interface": "eth1", + "type": "pppoe", + "outer-vlan-min": 2000, + "outer-vlan-max": 2999, + "inner-vlan-min": 1, + "inner-vlan-max": 4049, + "authentication-protocol": "CHAP" + } + ] + }, + "sessions": { + "count": 1000, + "session-time": 0, + "max-outstanding": 800, + "start-rate": 400, + "stop-rate": 400 + }, + "pppoe": { + "reconnect": true, + "discovery-timeout": 3, + "discovery-retry": 10 + }, + "ppp": { + "mru": 1492, + "authentication": { + "username": "user{session-global}@rtbrick.com", + "password": "test", + "timeout": 5, + "retry": 30 + }, + "lcp": { + "conf-request-timeout": 1, + "conf-request-retry": 10, + "keepalive-interval": 30, + "keepalive-retry": 3 + }, + "ipcp": { + "enable": true, + "request-ip": true, + "request-dns1": true, + "request-dns2": true, + "conf-request-timeout": 1, + "conf-request-retry": 10 + }, + "ip6cp": { + "enable": true, + "conf-request-timeout": 1, + "conf-request-retry": 10 + } + }, + "dhcpv6": { + "enable": true, + "rapid-commit": true + }, + "access-line": { + "agent-remote-id": "DEU.RTBRICK.{session-global}", + "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}", + "rate-up": 1024, + "rate-down": 16384 + }, + "session-traffic": { + "ipv4-pps": 1, + "ipv6-pps": 1, + "ipv6pd-pps": 1 + } + } + +PPPoE +^^^^^ +.. include:: ../configuration/pppoe.rst + +PPP +^^^ +.. include:: ../configuration/ppp.rst + +PPP Authentication +^^^^^^^^^^^^^^^^^^ +.. include:: ../configuration/ppp_authentication.rst + +PPP LCP +^^^^^^^ +.. include:: ../configuration/ppp_lcp.rst + +PPP IPCP (IPv4) +^^^^^^^^^^^^^^^ +.. include:: ../configuration/ppp_ipcp.rst + +PPP IP6CP (IPv6) +^^^^^^^^^^^^^^^^ +.. include:: ../configuration/ppp_ip6cp.rst + + +LCP Vendor Extension +~~~~~~~~~~~~~~~~~~~~ + +This chapter refers to RFC 2153 PPP vendor extensions. + +Per default all LCP vendor specific requests will be rejected sending a +LCP code reject message. With the LCP option ``ignore-vendor-specific`` +enabled, those messages will be ignored as required to emulate different CPE +behaviors. + +The LCP option ``connection-status-message`` allows to accept LCP vendor requests +with any OUI if kind is set to ``1`` by responding with vendor request of +kind ``2``. The OUI from request is copied to response in this case. +The value from request is stored in the session as ``connection-status-message``. + +PPPoE Commands +~~~~~~~~~~~~~~ + +The control socket command ``session-info session-id `` provides +detailed information for PPPoE sessions. + +``$ sudo bngblaster-cli run.sock session-info session-id 1 | jq .`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "session-information": { + "type": "pppoe", + "session-id": 1, + "session-state": "Established", + "interface": "eth1", + "outer-vlan": 1000, + "inner-vlan": 1, + "mac": "02:00:00:00:00:01", + "username": "user1@rtbrick.com", + "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:1", + "agent-remote-id": "DEU.RTBRICK.1", + "lcp-state": "Opened", + "ipcp-state": "Opened", + "ip6cp-state": "Opened", + "ipv4-address": "10.100.128.0", + "ipv4-dns1": "10.0.0.3", + "ipv4-dns2": "10.0.0.4", + "ipv6-prefix": "fc66:1000:1::/64", + "ipv6-delegated-prefix": "fc66:2000::/56", + "ipv6-dns1": "fc66::3", + "ipv6-dns2": "fc66::4", + "dhcpv6-state": "Bound", + "dhcpv6-dns1": "fc66::3", + "dhcpv6-dns2": "fc66::4", + "tx-packets": 10036, + "rx-packets": 10083, + "rx-fragmented-packets": 0, + "session-traffic": { + "total-flows": 6, + "verified-flows": 6, + "first-seq-rx-access-ipv4": 2, + "first-seq-rx-access-ipv6": 3, + "first-seq-rx-access-ipv6pd": 3, + "first-seq-rx-network-ipv4": 2, + "first-seq-rx-network-ipv6": 3, + "first-seq-rx-network-ipv6pd": 3, + "access-tx-session-packets": 3266, + "access-rx-session-packets": 3265, + "access-rx-session-packets-loss": 0, + "network-tx-session-packets": 3266, + "network-rx-session-packets": 3265, + "network-rx-session-packets-loss": 0, + "access-tx-session-packets-ipv6": 3266, + "access-rx-session-packets-ipv6": 3264, + "access-rx-session-packets-ipv6-loss": 0, + "network-tx-session-packets-ipv6": 3266, + "network-rx-session-packets-ipv6": 3264, + "network-rx-session-packets-ipv6-loss": 0, + "access-tx-session-packets-ipv6pd": 3266, + "access-rx-session-packets-ipv6pd": 3264, + "access-rx-session-packets-ipv6pd-loss": 0, + "network-tx-session-packets-ipv6pd": 3266, + "network-rx-session-packets-ipv6pd": 3264, + "network-rx-session-packets-ipv6pd-loss": 0 + } + } + } diff --git a/docs/source/access/traffic.rst b/docs/source/access/traffic.rst new file mode 100644 index 00000000..69d4651e --- /dev/null +++ b/docs/source/access/traffic.rst @@ -0,0 +1,79 @@ +.. _session-traffic: + +Session Traffic +--------------- + +The BNG Blaster is able to generate bidirectional unicast +session traffic for all addresses assigned to a session +(IPv4, IPv6 and IPv6PD). + +.. image:: ../images/bbl_session_traffic.png + :alt: Session Traffic + +This is a powerful tool to quickly verify that forwarding +is correctly setup and working. + +Configuration +~~~~~~~~~~~~~ + +The following example shows how to enable session-traffic. + +.. code-block:: json + + { + "session-traffic": { + "ipv4-pps": 1, + "ipv6-pps": 1, + "ipv6pd-pps": 1 + } + } + +.. include:: ../configuration/isis.rst + +This traffic is generated between the session and a network +interface. In case of multiple network interfaces, the preferred +network interfaces can be selected using the ``network-interface`` +option in the corresponding access configuration. + +Verification +~~~~~~~~~~~~ + +The final report includes detailed information +for session traffic. + +*Example report output for 100 sessions:* + +.. code-block:: none + + Session Traffic: + Config: + IPv4 PPS: 1 + IPv6 PPS: 1 + IPv6PD PPS: 1 + Verified Traffic Flows: 3000/3000 + Access IPv4: 500 + Access IPv6: 500 + Access IPv6PD: 500 + Network IPv4: 500 + Network IPv6: 500 + Network IPv6PD: 500 + First Sequence Number Received: + Access IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) + Access IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Access IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Network IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) + Network IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Network IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + + +The statistics starting with ``Access ...`` correspond to traffic +received on the access interface (network->access) where those +starting with ``Network ...`` correspond to traffic received on +the network interface (access->network). + +The ``First Sequence Number Received`` is used to measure the forwarding +convergence. The session traffic starts automatically as soo as the session +is established using the rate configured. All traffic flows in the BNG Blaster +start with the 64bit sequence number 1. Assuming the first sequence number +received for given flow is 5 combined with a rate of 1 PPS would mean that +it took between 4 and 5 seconds until forwarding is working. \ No newline at end of file diff --git a/docs/source/api/bgp.rst b/docs/source/api/bgp.rst new file mode 100644 index 00000000..53ddf4d7 --- /dev/null +++ b/docs/source/api/bgp.rst @@ -0,0 +1,27 @@ +.. list-table:: + :header-rows: 1 + + * - 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` diff --git a/docs/source/api/cfm.rst b/docs/source/api/cfm.rst new file mode 100644 index 00000000..2e4d75bd --- /dev/null +++ b/docs/source/api/cfm.rst @@ -0,0 +1,23 @@ +.. list-table:: + :header-rows: 1 + + * - 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` \ No newline at end of file diff --git a/docs/source/api/igmp.rst b/docs/source/api/igmp.rst new file mode 100644 index 00000000..0c779d0c --- /dev/null +++ b/docs/source/api/igmp.rst @@ -0,0 +1,19 @@ +.. list-table:: + :header-rows: 1 + + * - Attribute + - Description + - Mandatory Arguments + - Optional Arguments + * - `igmp-join` + - Join group + - `group` + - `source1`, `source2`, `source3` + * - `igmp-leave` + - Leave group + - `group` + - + * - `igmp-info` + - Display group information + - + - \ No newline at end of file diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 00000000..1e579365 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,178 @@ +.. _api: + +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. + +.. code-block:: json + + { + "command": "" + "arguments": { + "": "" + } + } + +Following an example RPC request with corresponding response. + +``$ cat command.json | jq .`` + +.. code-block:: json + + { + "command": "session-counters" + } + +``$ cat command.json | sudo nc -U run.sock | jq .`` + +.. code-block:: json + + { + "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 .`` + +.. code-block:: json + + { + "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. + + .. code-block:: json + + { + "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. + +.. code-block:: none + + $ sudo bngblaster-cli + BNG Blaster Control Socket Client + + bngblaster-cli [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 .`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "session-counters": { + "sessions": 1, + "sessions-established": 1, + "sessions-flapped": 0, + "dhcpv6-sessions-established": 1 + } + } + + +Interfaces +---------- +.. include:: interfaces.rst + +Sessions +-------- +.. include:: sessions.rst + +PPP +--- +.. include:: ppp.rst + +L2TP +---- +.. include:: l2tp.rst + +IGMP +---- +.. include:: igmp.rst + +Traffic +------- +.. include:: traffic.rst + +Streams +------- +.. include:: streams.rst + +ISIS +---- +.. include:: isis.rst + +BGP +--- +.. include:: bgp.rst + +CFM +--- +.. include:: cfm.rst + +Legal Interception (LI) +----------------------- + +This is explained detailed in the +:ref:`Legal Interception (LI)
  • ` section. + +.. include:: li.rst diff --git a/docs/source/api/interfaces.rst b/docs/source/api/interfaces.rst new file mode 100644 index 00000000..ad5a181b --- /dev/null +++ b/docs/source/api/interfaces.rst @@ -0,0 +1,11 @@ +.. list-table:: + :header-rows: 1 + + * - Attribute + - Description + - Mandatory Arguments + - Optional Arguments + * - `interfaces` + - List all interfaces with index + - + - diff --git a/docs/source/api/isis.rst b/docs/source/api/isis.rst new file mode 100644 index 00000000..27a11523 --- /dev/null +++ b/docs/source/api/isis.rst @@ -0,0 +1,27 @@ +.. list-table:: + :header-rows: 1 + + * - 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 + - + - \ No newline at end of file diff --git a/docs/source/api/l2tp.rst b/docs/source/api/l2tp.rst new file mode 100644 index 00000000..c6918344 --- /dev/null +++ b/docs/source/api/l2tp.rst @@ -0,0 +1,53 @@ +.. list-table:: + :header-rows: 1 + + * - 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. + +.. code-block:: json + + { + "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"`` diff --git a/docs/source/api/li.rst b/docs/source/api/li.rst new file mode 100644 index 00000000..665c5eb1 --- /dev/null +++ b/docs/source/api/li.rst @@ -0,0 +1,11 @@ +.. list-table:: + :header-rows: 1 + + * - Attribute + - Description + - Mandatory Arguments + - Optional Arguments + * - `li-flows` + - List all LI flows with detailed statistics + - + - diff --git a/docs/source/api/ppp.rst b/docs/source/api/ppp.rst new file mode 100644 index 00000000..c1b77030 --- /dev/null +++ b/docs/source/api/ppp.rst @@ -0,0 +1,23 @@ +.. list-table:: + :header-rows: 1 + + * - 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` diff --git a/docs/source/api/sessions.rst b/docs/source/api/sessions.rst new file mode 100644 index 00000000..eb7ffe39 --- /dev/null +++ b/docs/source/api/sessions.rst @@ -0,0 +1,39 @@ +.. list-table:: + :header-rows: 1 + + * - 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` \ No newline at end of file diff --git a/docs/source/api/streams.rst b/docs/source/api/streams.rst new file mode 100644 index 00000000..5c7b41aa --- /dev/null +++ b/docs/source/api/streams.rst @@ -0,0 +1,23 @@ +.. list-table:: + :header-rows: 1 + + * - 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` diff --git a/docs/source/api/traffic.rst b/docs/source/api/traffic.rst new file mode 100644 index 00000000..d3419a26 --- /dev/null +++ b/docs/source/api/traffic.rst @@ -0,0 +1,23 @@ +.. list-table:: + :header-rows: 1 + + * - 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 + - + - \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..a4700486 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,32 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'BNG Blaster' +copyright = '2020-2022, RtBrick, Inc.' +author = 'Christian Giese' +release = '0.0' +version = '0.0.0' + +# -- General configuration + +extensions = [ + 'sphinx_tabs.tabs' +] + +master_doc = 'index' +html_logo = 'images/rtbrick_logo.png' + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'logo_only': False, + 'display_version': False, +} + +# -- Options for EPUB output + +epub_show_urls = 'footnote' diff --git a/docs/source/configuration/access_line.rst b/docs/source/configuration/access_line.rst new file mode 100644 index 00000000..952a7a1d --- /dev/null +++ b/docs/source/configuration/access_line.rst @@ -0,0 +1,27 @@ +.. code-block:: json + + { "access-line": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `agent-circuit-id` + - Agent-Circuit-Id + - + * - `agent-remote-id` + - Agent-Remote-Id + - + * - `rate-up` + - Actual Data Rate Upstream + - + * - `rate-down` + - Actual Data Rate Downstream + - + * - `dsl-type` + - DSL-Type + - \ No newline at end of file diff --git a/docs/source/configuration/access_line_profiles.rst b/docs/source/configuration/access_line_profiles.rst new file mode 100644 index 00000000..07242c76 --- /dev/null +++ b/docs/source/configuration/access_line_profiles.rst @@ -0,0 +1,113 @@ +.. code-block:: json + + { "access-line-profiles": [] } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `access-line-profile-id` + - Mandatory access-line-profile identifier + - + * - `act-up` + - Actual Data Rate Upstream + - 0 + * - `act-down` + - Actual Data Rate Downstream + - 0 + * - `min-up` + - Minimum Data Rate Upstream + - 0 + * - `min-down` + - Minimum Data Rate Downstream + - 0 + * - `att-up` + - Attainable DataRate Upstream + - 0 + * - `att-down` + - Attainable DataRate Downstream + - 0 + * - `max-up` + - Maximum Data Rate Upstream + - 0 + * - `max-down` + - Maximum Data Rate Downstream + - 0 + * - `min-up-low` + - Min Data Rate Upstream in low power state + - 0 + * - `min-down-low` + - Min Data Rate Downstream in low power state + - 0 + * - `max-interl-delay-up` + - Max Interleaving Delay Upstream + - 0 + * - `act-interl-delay-up` + - Actual Interleaving Delay Upstream + - 0 + * - `max-interl-delay-down` + - Max Interleaving Delay Downstream + - 0 + * - `act-interl-delay-down` + - Actual Interleaving Delay Downstream + - 0 + * - `data-link-encaps` + - Data Link Encapsulation + - 0 + * - `dsl-type` + - DSL Type + - 0 + * - `pon-type` + - PON Access Type + - 0 + * - `etr-up` + - Expected Throughput (ETR) Upstream + - 0 + * - `etr-down` + - Expected Throughput (ETR) Downstream + - 0 + * - `attetr-up` + - Attainable Expected Throughput (ATTETR) Upstream + - 0 + * - `attetr-down` + - Attainable Expected Throughput (ATTETR) Downstream + - 0 + * - `gdr-up` + - Gamma Data Rate (GDR) Upstream + - 0 + * - `gdr-down` + - Gamma Data Rate (GDR) Downstream + - 0 + * - `attgdr-up` + - Attainable Gamma Data Rate (ATTGDR) Upstream + - 0 + * - `attgdr-down` + - Attainable Gamma Data Rate (ATTGDR) Downstream + - 0 + * - `ont-onu-avg-down` + - ONT/ONU Average Data Rate Downstream + - 0 + * - `ont-onu-peak-down` + - ONT/ONUPeak Data Rate Downstream + - 0 + * - `ont-onu-max-up` + - ONT/ONU Maximum Data Rate Upstream + - 0 + * - `ont-onu-ass-up` + - ONT/ONU Assured Data Rate Upstream + - 0 + * - `pon-max-up` + - PON Tree Maximum Data Rate Upstream + - 0 + * - `pon-max-down` + - PON Tree Maximum Data Rate Downstream + - 0 + +Attributes with value set to 0 will not be send. + +The values for ``rate-up``, ``rate-down`` and ``dsl-type`` defined in the +access-line or interface section have priority over those defined here. diff --git a/docs/source/configuration/bgp.rst b/docs/source/configuration/bgp.rst new file mode 100644 index 00000000..7c1ebf00 --- /dev/null +++ b/docs/source/configuration/bgp.rst @@ -0,0 +1,45 @@ +.. code-block:: json + + { "bgp": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `network-interface` + - BGP local interface (source-interface) + - first network interface + * - `local-ipv4-address` + - BGP local IPv4 address (source-address) + - network interface address + * - `local-as` + - BGP local AS + - 65000 + * - `peer-ipv4-address` + - BGP peer address + - + * - `peer-as` + - BGP peer AS + - local AS + * - `holdtime` + - BGP holdtime in seconds + - 90 + * - `id` + - BGP identifier + - 1.2.3.4 + * - `reconnect` + - BGP reconnect + - true + * - `start-traffic` + - BGP start global traffic after RAW update + - false + * - `teardown-time` + - BGP teardown time in seconds + - 5 + * - `raw-update-file` + - BGP RAW update file + - \ No newline at end of file diff --git a/docs/source/configuration/dhcp.rst b/docs/source/configuration/dhcp.rst new file mode 100644 index 00000000..f0702541 --- /dev/null +++ b/docs/source/configuration/dhcp.rst @@ -0,0 +1,36 @@ +.. code-block:: json + + { "dhcp": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `enable` + - This option allows to enable or disable DHCP + - false + * - `broadcast` + - DHCP broadcast flag + - false + * - `timeout` + - DHCP timeout in seconds + - 5 + * - `retry` + - DHCP retry + - 10 + * - `release-interval` + - DHCP release interval + - 1 + * - `release-retry` + - DHCP release retry + - 3 + * - `tos` + - IPv4 TOS for all DHCP control traffic + - 0 + * - `vlan-priority` + - VLAN PBIT for all DHCP control traffic + - 0 \ No newline at end of file diff --git a/docs/source/configuration/dhcpv6.rst b/docs/source/configuration/dhcpv6.rst new file mode 100644 index 00000000..29ac71d1 --- /dev/null +++ b/docs/source/configuration/dhcpv6.rst @@ -0,0 +1,24 @@ +.. code-block:: json + + { "dhcpv6": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `enable` + - This option allows to enable or disable DHCPv6 + - true + * - `rapid-commit` + - DHCPv6 rapid commit (2 way handshake) + - true + * - `timeout` + - DHCPv6 timeout in seconds + - 5 + * - `retry` + - DHCPv6 retry + - 10 \ No newline at end of file diff --git a/docs/source/configuration/igmp.rst b/docs/source/configuration/igmp.rst new file mode 100644 index 00000000..5252464f --- /dev/null +++ b/docs/source/configuration/igmp.rst @@ -0,0 +1,72 @@ +.. code-block:: json + + { "igmp": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `autostart` + - Automatically join after session is established + - true + * - `version` + - IGMP protocol version (1, 2 or 3) + - 3 + * - `combined-leave-join` + - Combine leave and join records within a single IGMPv3 report + - true + * - `start-delay` + - Delay between session established and initial IGMP join in seconds + - 1 + * - `group` + - Multicast group base address (e.g. 239.0.0.1) + - 0.0.0.0 (disabled) + * - `group-iter` + - Multicast group iterator + - 0.0.0.1 + * - `group-count` + - Multicast group count + - 1 + * - `source` + - Multicast source address (e.g. 1.1.1.1) + - 0.0.0.0 (ASM) + * - `zapping-interval` + - IGMP channel zapping interval in seconds + - 0 (disabled) + * - `zapping-count` + - Define the amount of channel changes before starting view duration + - 0 (disabled) + * - `view-duration` + - Define the view duration in seconds + - 0 (disabled) + * - `send-multicast-traffic` + - Generate multicast traffic + - false + * - `multicast-traffic-length` + - Multicast traffic IP length + - 76 + * - `multicast-traffic-tos` + - Multicast traffic TOS priority + - 0 + * - `network-interface` + - Multicast traffic source interface + - + +Per default join and leave requests are send using dedicated reports. +The option ``combined-leave-join`` allows the combination of leave and +join records within a single IGMPv3 report using multiple group records. +This option is applicable to IGMP version 3 only! + +If ``send-multicast-traffic`` is true, the BNG Blaster generates multicast +traffic on the network interface based on the specified group and source +attributes mentioned before. This traffic includes some special signatures +for faster processing and more detailed analysis. + +If group is set to 293.0.0.1 with group-iter of 0.0.0.2, source 1.1.1.1 +and group-count 3 the result are the following three groups (S.G) +1.1.1.1,239.0.0.1, 1.1.1.1,239.0.0.3 and 1.1.1.1,239.0.0.5. + diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst new file mode 100644 index 00000000..9cdfecc3 --- /dev/null +++ b/docs/source/configuration/index.rst @@ -0,0 +1,109 @@ +.. _configuration: + +Configuration +============= + +Interfaces +---------- + +The BNG Blaster interfaces are explained detailed in the +:ref:`interfaces section `. + +.. include:: interfaces.rst + +Network Interfaces +~~~~~~~~~~~~~~~~~~ +.. include:: interfaces_network.rst + +Access Interfaces +~~~~~~~~~~~~~~~~~ +.. include:: interfaces_access.rst + +A10NSP Interfaces +~~~~~~~~~~~~~~~~~ +.. include:: interfaces_a10nsp.rst + +Sessions +-------- +.. include:: sessions.rst + +IPoE +---- +.. include:: ipoe.rst + +PPPoE +----- +.. include:: pppoe.rst + +PPP +--- +.. include:: ppp.rst + +PPP Authentication +~~~~~~~~~~~~~~~~~~ +.. include:: ppp_authentication.rst + +PPP LCP +~~~~~~~~~~~~~~~~~~ +.. include:: ppp_lcp.rst + +PPP IPCP (IPv4) +~~~~~~~~~~~~~~~ +.. include:: ppp_ipcp.rst + +PPP IP6CP (IPv6) +~~~~~~~~~~~~~~~~ +.. include:: ppp_ip6cp.rst + +DHCP +---- +.. include:: dhcp.rst + +DHCPv6 +------ +.. include:: dhcpv6.rst + +IGMP +---- +.. include:: igmp.rst + +L2TPv2 Server (LNS) +------------------- +.. include:: lns.rst + +Traffic +------- +.. include:: traffic.rst + +Traffic-Streams +--------------- +.. include:: streams.rst + +Session-Traffic +--------------- +.. include:: session_traffic.rst + +Access-Line +----------- +.. include:: access_line.rst + +Access-Line-Profiles +-------------------- +.. include:: access_line_profiles.rst + +ISIS +---- +.. include:: isis.rst + +ISIS External +~~~~~~~~~~~~~ +.. include:: isis_external.rst + + +ISIS External Connections +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. include:: isis_external_connections.rst + +BGP +--- +.. include:: bgp.rst \ No newline at end of file diff --git a/docs/source/configuration/interfaces.rst b/docs/source/configuration/interfaces.rst new file mode 100644 index 00000000..a097529c --- /dev/null +++ b/docs/source/configuration/interfaces.rst @@ -0,0 +1,33 @@ +.. code-block:: json + + { "interfaces": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `tx-interval` + - TX ring polling interval in milliseconds + - 5.0 + * - `rx-interval` + - RX ring polling interval in milliseconds + - 5.0 + * - `qdisc-bypass` + - Bypass the kernel's qdisc layer + - true + * - `io-mode` + - IO mode + - packet_mmap_raw + * - `io-slots` + - IO slots (ring size) + - 1024 + * - `io-stream-max-ppi` + - IO traffic stream max packets per interval + - 32 + * - `capture-include-streams` + - Include traffic streams in capture + - true \ No newline at end of file diff --git a/docs/source/configuration/interfaces_a10nsp.rst b/docs/source/configuration/interfaces_a10nsp.rst new file mode 100644 index 00000000..b72ee2c7 --- /dev/null +++ b/docs/source/configuration/interfaces_a10nsp.rst @@ -0,0 +1,21 @@ +.. code-block:: json + + { "interfaces": { "a10nsp": [] } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `interface` + - A10nSP interface name (e.g. eth0, ...) + - + * - `qinq` + - Set outer VLAN ethertype to QinQ (0x88a8) + - false + * - `mac` + - Optional set gateway interface address manually + - \ No newline at end of file diff --git a/docs/source/configuration/interfaces_access.rst b/docs/source/configuration/interfaces_access.rst new file mode 100644 index 00000000..49eb5678 --- /dev/null +++ b/docs/source/configuration/interfaces_access.rst @@ -0,0 +1,138 @@ +.. code-block:: json + + { "interfaces": { "access": [] } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `interface` + - Access interface name (e.g. eth0, ...) + - + * - `network-interface` + - Select the corresponding network interface for this session + - + * - `type` + - Set access type (`pppoe` or `ipoe`) + - pppoe + * - `vlan-mode` + - Set VLAN mode `1:1` or `N:1` + - 1:1 + * - `qinq` + - Set outer VLAN ethertype to QinQ (0x88a8) + - false + * - `outer-vlan-min` + - Outer VLAN minimum value + - 0 (untagged) + * - `outer-vlan-max` + - Outer VLAN maximum value + - 0 (untagged) + * - `outer-vlan` + - Set outer-vlan-min/max equally + - + * - `inner-vlan-min` + - Inner VLAN minimum value + - 0 (untagged) + * - `inner-vlan-max` + - Inner VLAN maximum value + - 0 (untagged) + * - `inner-vlan` + - Set inner-vlan-min/max equally + - + * - `third-vlan` + - Add a fixed third VLAN (most inner VLAN) + - 0 (untagged) + * - `address` + - Static IPv4 base address (IPoE only) + - + * - `address-iter` + - Static IPv4 base address iterator (IPoE only) + - + * - `gateway` + - Static IPv4 gateway address (IPoE only) + - + * - `gateway-iter` + - Static IPv4 gateway address iterator (IPoE only) + - + * - `username` + - Overwrite the username from authentication section + - + * - `password` + - Overwrite the password from authentication section + - + * - `authentication-protocol` + - Overwrite the username from authentication section + - + * - `agent-circuit-id` + - Overwrite the agent-circuit-id from access-line section + - + * - `agent-remote-id` + - Overwrite the agent-remote-id from access-line section + - + * - `rate-up` + - Overwrite the rate-up from access-line section + - + * - `rate-down` + - Overwrite the rate-down from access-line section + - + * - `dsl-type` + - Overwrite the dsl-type from access-line section + - + * - `ipcp` + - De-/activate PPP IPCP + - + * - `ip6cp` + - De-/activate PPP IP6CP + - + * - `ipv4` + - De-/activate IPoE IPv4 + - + * - `ipv6` + - De-/activate IPoE IPv6 + - + * - `dhcp` + - De-/activate DHCP + - + * - `dhcpv6` + - De-/activate DHCPv6 + - + * - `igmp-autostart` + - Overwrite IGMP autostart + - + * - `igmp-version` + - Overwrite IGMP protocol version (1, 2 or 3) + - + * - `stream-group-id` + - Stream group identifier + - + * - `access-line-profile-id` + - Access-line-profile identifier + - + * - `cfm-cc` + - De-/activate EOAM CFM CC (IPoE only) + - false + * - `cfm-level` + - Set EOAM CFM maintenance domain level + - 0 + * - `cfm-ma-id` + - Set EOAM CFM maintenance association identifier + - 0 + * - `cfm-ma-name` + - Set EOAM CFM maintenance association short name + - + * - `i1-start` + - Iterator for usage in strings `{i1}` + - 1 + * - `i1-step` + - Iterator step per session + - 1 + * - `i2-start` + - Iterator for usage in strings `{i2}` + - 1 + * - `i2-step` + - Iterator step per session + - 1 \ No newline at end of file diff --git a/docs/source/configuration/interfaces_network.rst b/docs/source/configuration/interfaces_network.rst new file mode 100644 index 00000000..f89bc4fc --- /dev/null +++ b/docs/source/configuration/interfaces_network.rst @@ -0,0 +1,51 @@ +.. code-block:: json + + { "interfaces": { "network": [] } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `interface` + - Network interface name (e.g. eth0, ...) + - + * - `address` + - Local network interface IPv4 address + - + * - `gateway` + - Gateway network interface IPv4 address + - + * - `address-ipv6` + - Local network interface IPv6 address (implicitly /64) + - + * - `gateway-ipv6` + - Gateway network interface IPv6 address (implicitly /64) + - + * - `vlan` + - Network interface VLAN + - 0 (untagged) + * - `gateway-mac` + - Optional set gateway MAC address manually + - + * - `gateway-resolve-wait` + - Sessions will not start until gateways are resolved + - true + * - `isis-instance-id` + - Assign interface to ISIS instance + - + * - `isis-level` + - ISIS interface level + - 3 + * - `isis-p2p` + - ISIS P2P interface + - true + * - `isis-l1-metric` + - ISIS level 1 interface metric + - 10 + * - `isis-l2-metric` + - ISIS level 2 interface metric + - 10 \ No newline at end of file diff --git a/docs/source/configuration/ipoe.rst b/docs/source/configuration/ipoe.rst new file mode 100644 index 00000000..b4961823 --- /dev/null +++ b/docs/source/configuration/ipoe.rst @@ -0,0 +1,24 @@ +.. code-block:: json + + { "ipoe": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `ipv4` + - Enable/disable IPv4 + - true (enabled) + * - `arp-timeout` + - Initial ARP resolve timeout/retry interval in seconds + - 1 + * - `arp-interval` + - Periodic ARP interval in seconds (0 means disabled) + - 300 + * - `ipv6` + - Enable/disable IPv6 + - true (enabled) \ No newline at end of file diff --git a/docs/source/configuration/isis.rst b/docs/source/configuration/isis.rst new file mode 100644 index 00000000..85341a4b --- /dev/null +++ b/docs/source/configuration/isis.rst @@ -0,0 +1,90 @@ +.. code-block:: json + + { "isis": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `instance-id` + - ISIS instance identifier + - + * - `level` + - ISIS level + - 3 + * - `overload` + - ISIS overload + - false + * - `protocol-ipv4` + - Enable/disable IPv4 + - true + * - `protocol-ipv6` + - Enable/disable IPv6 + - true + * - `level1-auth-key` + - ISIS level 1 authentication key + - + * - `level1-auth-type` + - ISIS level 1 authentication type (simple or md5) + - disabled + * - `level2-auth-key` + - ISIS level 2 authentication key + - + * - `level2-auth-type` + - ISIS level 2 authentication type (simple or md5) + - disabled + * - `hello-interval` + - ISIS hello interval in seconds + - 10 + * - `hello-padding` + - ISIS hello padding + - false + * - `holding-time` + - ISIS holding time in seconds + - 30 + * - `lsp-lifetime` + - ISIS LSP lifetime in seconds + - 65535 + * - `lsp-refresh-interval` + - ISIS LSP refresh interval in seconds + - 300 + * - `lsp-retry-interval` + - ISIS LSP retry interval in seconds + - 5 + * - `lsp-tx-interval` + - ISIS LSP TX interval in ms (time between LSP send windows) + - 10 + * - `lsp-tx-window-size` + - ISIS LSP TX window size (LSP send per window) + - 1 + * - `csnp-interval` + - ISIS CSNP interval in seconds + - 30 + * - `hostname` + - ISIS hostname + - bngblaster + * - `router-id` + - ISIS router identifier + - 10.10.10.10 + * - `system-id` + - ISIS system identifier + - 0100.1001.0010 + * - `area` + - ISIS area(s) + - 49.0001/24 + * - `sr-base` + - ISIS SR base + - + * - `sr-range` + - ISIS SR range + - + * - `sr-node-sid` + - ISIS SR node SID + - + * - `teardown-time` + - ISIS teardown time in seconds + - 5 \ No newline at end of file diff --git a/docs/source/configuration/isis_external.rst b/docs/source/configuration/isis_external.rst new file mode 100644 index 00000000..33d4efd5 --- /dev/null +++ b/docs/source/configuration/isis_external.rst @@ -0,0 +1,15 @@ +.. code-block:: json + + { "isis": { "external": {} } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `mrt-file` + - ISIS MRT file + - \ No newline at end of file diff --git a/docs/source/configuration/isis_external_connections.rst b/docs/source/configuration/isis_external_connections.rst new file mode 100644 index 00000000..cd3ddea0 --- /dev/null +++ b/docs/source/configuration/isis_external_connections.rst @@ -0,0 +1,21 @@ +.. code-block:: json + + { "isis": { "external": { "connections": [] } } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `system-id` + - ISIS system identifier + - + * - `l1-metric` + - ISIS level 1 interface metric + - 10 + * - `l2-metric` + - ISIS level 2 interface metric + - 10 \ No newline at end of file diff --git a/docs/source/configuration/lns.rst b/docs/source/configuration/lns.rst new file mode 100644 index 00000000..a9c4884f --- /dev/null +++ b/docs/source/configuration/lns.rst @@ -0,0 +1,53 @@ +.. code-block:: json + + { "l2tp-server": [] } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `name` + - Mandatory L2TP LNS server hostname (AVP 7) + - + * - `address` + - Mandatory L2TP server address + - + * - `secret` + - Tunnel secret + - + * - `receive-window-size` + - Control messages receive window size + - 4 + * - `max-retry` + - Control messages max retry + - 30 + * - `congestion-mode` + - Control messages congestion mode + - default + * - `data-control-priority` + - Set the priority bit in the L2TP header for all non-IP data packets (LCP, IPCP, ...) + - false + * - `data-length` + - Set length bit for all data packets + - false + * - `data-offset` + - Set offset bit with offset zero for all data packets + - false + * - `control-tos` + - L2TP control traffic (SCCRQ, ICRQ, ...) TOS priority + - 0 + * - `data-control-tos` + - Set the L2TP tunnel TOS priority (outer IPv4 header) for all non-IP data packets (LCP, IPCP, ...) + - 0 + +The BNG Blaster supports different congestion modes for the +reliable delivery of control messages. The ``default`` mode +is described in RFC2661 appendix A (Control Channel Slow Start and +Congestion Avoidance). The mode ``slow`` uses a fixed control window +size of 1 where ``aggressive`` sticks to max permitted based on peer +received window size. + diff --git a/docs/source/configuration/ppp.rst b/docs/source/configuration/ppp.rst new file mode 100644 index 00000000..b805c60c --- /dev/null +++ b/docs/source/configuration/ppp.rst @@ -0,0 +1,15 @@ +.. code-block:: json + + { "ppp": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `mru` + - Define the maximum receive unit proposed via PPP + - 1492 \ No newline at end of file diff --git a/docs/source/configuration/ppp_authentication.rst b/docs/source/configuration/ppp_authentication.rst new file mode 100644 index 00000000..96cddd39 --- /dev/null +++ b/docs/source/configuration/ppp_authentication.rst @@ -0,0 +1,27 @@ +.. code-block:: json + + { "ppp": { "authentication": {} } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `username` + - Username + - user{session-global}@rtbrick.com + * - `password` + - Password + - test + * - `timeout` + - Authentication request timeout in seconds + - 5 + * - `retry` + - Authentication request max retry + - 30 + * - `protocol` + - This value can be set to `PAP` or `CHAP` to reject the other protocol + - allow PAP and CHAP \ No newline at end of file diff --git a/docs/source/configuration/ppp_ip6cp.rst b/docs/source/configuration/ppp_ip6cp.rst new file mode 100644 index 00000000..3e74537a --- /dev/null +++ b/docs/source/configuration/ppp_ip6cp.rst @@ -0,0 +1,21 @@ +.. code-block:: json + + { "ppp": { "ip6cp": {} } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `enable` + - This option allows to enable or disable the IP6CP protocol + - true + * - `conf-request-timeout` + - IP6CP configuration request timeout in seconds + - 5 + * - `conf-request-retry` + - IP6CP configuration request max retry + - 10 \ No newline at end of file diff --git a/docs/source/configuration/ppp_ipcp.rst b/docs/source/configuration/ppp_ipcp.rst new file mode 100644 index 00000000..3c4cda6b --- /dev/null +++ b/docs/source/configuration/ppp_ipcp.rst @@ -0,0 +1,30 @@ +.. code-block:: json + + { "ppp": { "ipcp": {} } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `enable` + - This option allows to enable or disable the IPCP protocol + - true + * - `request-ip` + - Include IP-Address with 0.0.0.0 in initial LCP configuration request + - true + * - `request-dns1` + - Request Primary DNS Server Address (option 129) + - true + * - `request-dns2` + - Request Secondary DNS Server Address (option 131) + - true + * - `conf-request-timeout` + - IPCP configuration request timeout in seconds + - 5 + * - `conf-request-retry` + - IPCP configuration request max retry + - 10 \ No newline at end of file diff --git a/docs/source/configuration/ppp_lcp.rst b/docs/source/configuration/ppp_lcp.rst new file mode 100644 index 00000000..6df2f837 --- /dev/null +++ b/docs/source/configuration/ppp_lcp.rst @@ -0,0 +1,33 @@ +.. code-block:: json + + { "ppp": { "lcp": {} } } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `conf-request-timeout` + - LCP configuration request timeout in seconds + - 5 + * - `conf-request-retry` + - LCP configuration request max retry + - 10 + * - `keepalive-interval` + - LCP echo request interval in seconds (0 means disabled) + - 30 + * - `keepalive-retry` + - PPP LCP echo request max retry + - 3 + * - `start-delay` + - PPP LCP initial request delay in milliseconds + - 0 + * - `ignore-vendor-specific` + - Ignore LCP vendor specific requests + - false + * - `connection-status-message` + - Accept LCP connection status messages + - false \ No newline at end of file diff --git a/docs/source/configuration/pppoe.rst b/docs/source/configuration/pppoe.rst new file mode 100644 index 00000000..60c50369 --- /dev/null +++ b/docs/source/configuration/pppoe.rst @@ -0,0 +1,33 @@ +.. code-block:: json + + { "pppoe": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `session-time` + - Max PPPoE session time in seconds + - 0 (infinity) + * - `reconnect` + - Automatically reconnect sessions if terminated + - false + * - `discovery-timeout` + - PPPoE discovery (PADI and PADR) timeout in seconds + - 5 + * - `discovery-retry` + - PPPoE discovery (PADI and PADR) max retry + - 10 + * - `service-name` + - PPPoE discovery service name + - + * - `host-uniq` + - PPPoE discovery host-uniq + - false + * - `vlan-priority` + - VLAN PBIT for all PPPoE/PPP control traffic + - 0 diff --git a/docs/source/configuration/session_traffic.rst b/docs/source/configuration/session_traffic.rst new file mode 100644 index 00000000..40264e2d --- /dev/null +++ b/docs/source/configuration/session_traffic.rst @@ -0,0 +1,24 @@ +.. code-block:: json + + { "session-traffic": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `autostart` + - Automatically start session traffic after session is established + - true + * - `ipv4-pps` + - Generate bidirectional IPv4 traffic between network interface and all session framed IPv4 addresses + - 0 (disabled) + * - `ipv6-pps` + - Generate bidirectional IPv6 traffic between network interface and all session framed IPv6 addresses + - 0 (disabled) + * - `ipv6pd-pps` + - Generate bidirectional Ipv6 traffic between network interface and all session delegated IPv6 addresses + - 0 (disabled) \ No newline at end of file diff --git a/docs/source/configuration/sessions.rst b/docs/source/configuration/sessions.rst new file mode 100644 index 00000000..29bf936a --- /dev/null +++ b/docs/source/configuration/sessions.rst @@ -0,0 +1,47 @@ +.. code-block:: json + + { "sessions": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `count` + - Sessions (PPPoE + IPoE) + - 1 + * - `max-outstanding` + - Max outstanding sessions + - 800 + * - `start-rate` + - Setup request rate in sessions per second + - 400 + * - `stop-rate` + - Teardown request rate in sessions per second + - 400 + * - `iterate-vlan-outer` + - Iterate on outer VLAN first + - false + * - `start-delay` + - Wait N seconds after all interface are resolved before starting sessions + - 0 + +Per default sessions are created by iteration over inner VLAN range first and +outer VLAN second. Which can be changed by ``iterate-vlan-outer`` to iterate +on outer VLAN first and inner VLAN second. + +Therefore the following configuration generates the sessions on VLAN (outer:inner) +1:3, 1:4, 2:3, 2:4 per default or alternative 1:3, 2:3, 1:4, 2:4 with +``iterate-vlan-outer`` enabled. + +.. code-block:: json + + { + "outer-vlan-min": 1, + "outer-vlan-max": 2, + "inner-vlan-min": 3, + "inner-vlan-max": 4 + } diff --git a/docs/source/configuration/streams.rst b/docs/source/configuration/streams.rst new file mode 100644 index 00000000..c5626d56 --- /dev/null +++ b/docs/source/configuration/streams.rst @@ -0,0 +1,110 @@ +.. code-block:: json + + { "streams": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `name` + - Mandatory stream name + - + * - `stream-group-id` + - Stream group identifier + - 0 (raw) + * - `type` + - Mandatory stream type (`ipv4`, `ipv6` or `ipv6pd`) + - + * - `direction` + - Mandatory stream direction (`upstream`, `downstream` or `both`) + - `both` + * - `priority` + - IPv4 TOS / IPv6 TC + - 0 + * - `vlan-priority` + - VLAN priority + - 0 + * - `length` + - Layer 3 (IP + payload) traffic length (76 - 9000) + - 128 + * - `pps` + - Stream traffic rate in packets per second + - 1 + * - `bps` + - Stream traffic rate in bits per second (layer 3) + - + * - `a10nsp-interface` + - Select the corresponding A10NSP interface for this stream + - + * - `network-interface` + - Select the corresponding network interface for this stream + - + * - `network-ipv4-address` + - Overwrite network interface IPv4 address + - + * - `network-ipv6-address` + - Overwrite network interface IPv6 address + - + * - `destination-ipv4-address` + - Overwrite the IPv4 destination address + - + * - `destination-ipv6-address` + - Overwrite the IPv6 destination address + - + * - `access-ipv4-source-address` + - Overwrite the access IPv4 source address (client) + - + * - `access-ipv6-source-address` + - Overwrite the access IPv6 source address (client) + - + * - `threaded` + - Run those streams in separate threads + - false + * - `thread-group` + - Assign this stream to thread group (1-255) + - 0 (thread per stream) + * - `max-packets` + - Send a burst of N packets and stop + - 0 (infinity) + * - `start-delay` + - Wait N seconds after session is established before start + - 0 + * - `tx-label1` + - MPLS send (TX) label (outer label) + - + * - `tx-label1-exp` + - EXP bits of first label (outer label) + - 0 + * - `tx-label1-ttl` + - TTL of first label (outer label) + - 255 + * - `tx-label2` + - MPLS send (TX) label (inner label) + - + * - `tx-label2-exp` + - EXP bits of first label (inner label) + - 0 + * - `tx-label2-ttl` + - TTL of first label (inner label) + - 255 + * - `rx-label1` + - Expected receive MPLS label (outer label) + - + * - `rx-label2` + - Expected receive MPLS label (inner label) + - + +For L2TP downstream traffic the IPv4 TOS is applied to the outer IPv4 +and inner IPv4 header. + +The ``pps`` option supports also float numbers like 0.1, or 2.5 PPS and has +priority over ``bps`` where second is only a helper to calculate the ``pps`` +based on given ``bps`` and ``length``. + +The options ``access-ipv4-source-address`` and ``access-ipv6-source-address`` +are used to test the BNG RPF functionality with traffic send from source addresses +different to those assigned to the client. diff --git a/docs/source/configuration/traffic.rst b/docs/source/configuration/traffic.rst new file mode 100644 index 00000000..81f72909 --- /dev/null +++ b/docs/source/configuration/traffic.rst @@ -0,0 +1,18 @@ +.. code-block:: json + + { "traffic": {} } + + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Attribute + - Description + - Default + * - `autostart` + - Automatically start traffic + - true + * - `stop-verified` + - Automatically stop traffic streams if verified + - false \ No newline at end of file diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 00000000..42a6c634 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,16 @@ +Frequently Asked Questions +========================== + +**Some session established on BNG are not established on BNG Blaster?** + +The BNG Blaster considers a session only as established if all configured +protocols are established. This could occur if the device under test (your BNG) +is configured for IPv4 only but the BNG Blaster is configured for IPv4 and IPv6. + +The idea here is to prevent that potential failures will be overseen. + +**DHCPv6 does not start for PPPoE sessions?** + +The BNG Blaster expects an ICMPv6 router-advertisement with other-config flag +before it starts sending DHCPv6 within a PPPoE session. + diff --git a/docs/images/bbl_arch.png b/docs/source/images/bbl_arch.png similarity index 100% rename from docs/images/bbl_arch.png rename to docs/source/images/bbl_arch.png diff --git a/docs/images/bbl_header.png b/docs/source/images/bbl_header.png similarity index 100% rename from docs/images/bbl_header.png rename to docs/source/images/bbl_header.png diff --git a/docs/images/bbl_interactive.png b/docs/source/images/bbl_interactive.png similarity index 100% rename from docs/images/bbl_interactive.png rename to docs/source/images/bbl_interactive.png diff --git a/docs/images/bbl_interfaces.png b/docs/source/images/bbl_interfaces.png similarity index 100% rename from docs/images/bbl_interfaces.png rename to docs/source/images/bbl_interfaces.png diff --git a/docs/images/bbl_isis.png b/docs/source/images/bbl_isis.png similarity index 100% rename from docs/images/bbl_isis.png rename to docs/source/images/bbl_isis.png diff --git a/docs/images/bbl_session_traffic.png b/docs/source/images/bbl_session_traffic.png similarity index 100% rename from docs/images/bbl_session_traffic.png rename to docs/source/images/bbl_session_traffic.png diff --git a/docs/images/bbl_streams.png b/docs/source/images/bbl_streams.png similarity index 100% rename from docs/images/bbl_streams.png rename to docs/source/images/bbl_streams.png diff --git a/docs/images/logo.png b/docs/source/images/logo.png similarity index 100% rename from docs/images/logo.png rename to docs/source/images/logo.png diff --git a/docs/images/pppoe-fsm.dot b/docs/source/images/pppoe-fsm.dot similarity index 100% rename from docs/images/pppoe-fsm.dot rename to docs/source/images/pppoe-fsm.dot diff --git a/docs/images/pppoe-fsm.svg b/docs/source/images/pppoe-fsm.svg similarity index 100% rename from docs/images/pppoe-fsm.svg rename to docs/source/images/pppoe-fsm.svg diff --git a/docs/source/images/quickstart1.png b/docs/source/images/quickstart1.png new file mode 100644 index 00000000..423e5b2f Binary files /dev/null and b/docs/source/images/quickstart1.png differ diff --git a/docs/source/images/quickstart2.png b/docs/source/images/quickstart2.png new file mode 100644 index 00000000..c89f0caf Binary files /dev/null and b/docs/source/images/quickstart2.png differ diff --git a/docs/images/rtbrick_logo.png b/docs/source/images/rtbrick_logo.png similarity index 100% rename from docs/images/rtbrick_logo.png rename to docs/source/images/rtbrick_logo.png diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..b7fa0e3c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,96 @@ +BNG Blaster +=========== + +The **BNG Blaster** is an open-source network tester +for access and routing protocols. It can emulate massive +PPPoE and IPoE (DHCP) subscribers including IPTV, and L2TP (LNS). +There are various routing protocols supported like ISIS and BGP. +So you can use it for end-to-end BNG and non-BNG router testing. + +You can use the included traffic generator for forwarding verification, +QoS testing or to measure convergence times. The traffic generator supports +millions of separate tracked flows. This allows you to verify every single +forwarding state of a full feed internet routing table. You can also send +traffic to every single QoS queue of your service edge router. + +The BNG Blaster is used by leading network operators, network hard- and software vendors. + +.. tabs:: + + .. tab:: Modern Software + + * Emulate massive nodes and sessions with low CPU and memory footprint + * Runs on every modern linux, virtual machines and containers + * All protocols implemented in user-space and optimized for performance + * Automation friendly API + * ... + + .. tab:: Access Protocols + + * Emulate massive PPPoE and IPoE (DHCP) clients + * Emulate L2TPv2 LNS servers with different behaviors + * Emulate A10NSP interfaces for L2BSA testing + * Included multicast and IPTV test suite + * Verify legal interception (LI) traffic + * ... + + .. tab:: Routing Protocols + + * Emulate ISIS topologies with thousands of nodes + * Support for ISIS Segment Routing + * Setup thousands of BGP sessions with millions of prefixes + * Verify MPLS labels for millions of flows + * ... + + .. tab:: Traffic Generator + + * Generate and track millions of traffic flows + * Verify your QoS configuration + * Verify all forwarding states + * Measure convergence times and loss + * ... + +A short `introduction `_ and good presentation +from `DENOG13 `_ can be found on YouTube. + +.. image:: images/bbl_interactive.png + :alt: BNG Blaster Interactive + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + install + quickstart + interfaces + access/index + routing/index + streams + reports + configuration/index + api/index + troubleshooting + reference/index + faq + +License +------- + +BNG Blaster is licensed under the BSD 3-Clause License, which means that you are free to get and use it for +commercial and non-commercial purposes as long as you fulfill its conditions. + +See the `LICENSE `_ +file for more details. + +Copyright +--------- +.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN + +Copyright |copy| 2020-2022, RtBrick, Inc. + +Contact +------- + +bngblaster@rtbrick.com \ No newline at end of file diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..d33708cc --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,161 @@ +.. _install: + +Installation +============ + +The BNG Blaster should run on any modern linux distribution +but is primary tested on Ubuntu 18.04 LTS and Ubuntu 20.04 LTS. + +Install Ubuntu +-------------- + +Install dependencies: + +.. code-block:: none + + sudo apt install -y libssl1.1 libncurses5 libjansson4 + +Download and install debian package: https://github.com/rtbrick/bngblaster/releases + +.. code-block:: none + + sudo dpkg -i + +This command installs the BNG Blaster to `/usr/sbin/bngblaster`. + +Build from Sources +------------------ + +Dependencies +^^^^^^^^^^^^ + +The BNG Blaster has dependencies to the RtBrick +`libdict fork `_ +and the following standard dependencies: + +.. code-block:: none + + # libdict + wget https://github.com/rtbrick/libdict/releases/download/v1.0.1/libdict-debian.zip + sudo dpkg -i libdict_1.0.1_amd64.deb + sudo dpkg -i libdict-dev_1.0.1_amd64.deb + + # standard dependencies + sudo apt install -y cmake \ + libcunit1-dev \ + libncurses5-dev \ + libssl-dev \ + libjansson-dev + +Build +^^^^^ + +Per default cmake (`cmake .`) will build the BNG Blaster as release +version with optimization and without debug symbols. + +.. code-block:: none + + mkdir build + cd build + cmake -DCMAKE_BUILD_TYPE=Release .. + make all + +Alternative it is also possible to build a debug +version for detailed troubleshooting using gdb. + +.. code-block:: none + + mkdir build + cd build + cmake -DCMAKE_BUILD_TYPE=Debug .. + make all + + +There are also CPack files generated which allows to easily generate a debian +package by just executing `cpack` from build directory. + +It is also recommended to provide the GIT commit details to be included in the +manually build version as shown below: + +.. code-block:: none + + cmake -DGIT_REF=`git rev-parse --abbrev-ref HEAD` -DGIT_SHA=`git rev-parse HEAD` . + +*Example:* + +.. code-block:: none + + $ bngblaster -v + GIT: + REF: dev + SHA: df453a5ee9dbf6440aefbfb9630fa0f06e326d44 + IO Modes: packet_mmap_raw (default), packet_mmap, raw + +Install +^^^^^^^ + +Then BNG Blaster can be installed using make install target. + +.. code-block:: none + + sudo make install + +This command installs the BNG Blaster to `/usr/sbin/bngblaster`. + +Build and Run Unit Tests +^^^^^^^^^^^^^^^^^^^^^^^^ + +Building and running unit tests requires CMocka to be installed: + +.. code-block:: none + + sudo apt install libcmocka-dev + +The option `BNGBLASTER_TESTS` enables to build unit tests. + +.. code-block:: none + + cmake -DCMAKE_BUILD_TYPE=Debug -DBNGBLASTER_TESTS=ON . + make all + make test + +*Example:* + +.. code-block:: none + + $ make test + Running tests... + Test project + Start 1: TestProtocols + 1/1 Test #1: TestProtocols .................... Passed 0.00 sec + + 100% tests passed, 0 tests failed out of 1 + + Total Test time (real) = 0.00 sec + +Running BNG Blaster +------------------- + +The BNG Blaster needs permissions to send raw packets and change network interface +settings. The easiest way to run the BNG Blaster is either as the root user or with +sudo: + +.. code-block:: none + + # As root + bngblaster -C config.json -I + + # As a normal user: + sudo bngblaster -C config.json -I + + +A third option is to set capabilities on the binary with in example `setcap` +as shown below: + +.. code-block:: none + + sudo setcap cap_net_raw,cap_net_admin,cap_dac_read_search+eip `which bngblaster` + + # As normal user: + bngblaster -C config.json -I + diff --git a/docs/source/interfaces.rst b/docs/source/interfaces.rst new file mode 100644 index 00000000..3a553016 --- /dev/null +++ b/docs/source/interfaces.rst @@ -0,0 +1,325 @@ +.. _interfaces: + +Interfaces +========== + +The BNG Blaster supports three types of interfaces. + +All interfaces are optional but obviously at least +one interface is required to start the BNG Blaster. + +Interface Settings +------------------ + +The following settings are applied to all interfaces. + +.. code-block:: json + + { + "interfaces": { + "tx-interval": 0.1, + "rx-interval": 0.1, + "io-slots": 2048, + } + } + + +.. include:: configuration/interfaces.rst + +The ``tx-interval`` and ``rx-interval`` should be set to at to at least ``1.0`` (1ms) +if more precise timestamps or high throughput is needed. This is recommended for IGMP +join/leave or QoS delay measurements. For higher packet rates (>1g) it might be needed to +increase the ``io-slots`` from the default value of ``1024`` to ``2048`` or more. + +The supported IO modes are listed with ``bngblaster -v`` but except +``packet_mmap_raw`` all other modes are currently considered as experimental. In +the default mode (``packet_mmap_raw``) all packets are received in a Packet MMAP +ring buffer and send directly trough RAW packet sockets. + +The interfaces used in BNG Blaster do not need IP addresses configured in the host +operating system but they need to be in up state. + +.. code-block:: none + + sudo ip link set dev up + +It is not possible to send packets larger than the interface MTU which is 1500 per default +but for PPPoE with multiple VLAN headers this might be not enough for large packets. +Therefore the interface MTU should be increased using the following commands. + +.. code-block:: none + + sudo ip link set mtu 9000 dev + + +This can be also archived via netplan using the following configuration for each BNG Blaster +interface. + +.. code-block:: yaml + + network: + version: 2 + renderer: networkd + ethernets: + eth1: + dhcp4: no + dhcp6: no + link-local: [] + mtu: 9000 + eth2: + dhcp4: no + dhcp6: no + link-local: [] + mtu: 9000 + + +.. note:: The number of interfaces is currently limited to 32! + + +Network Interfaces +------------------ + +.. _network-interface: + +The network interfaces are used for traffic and routing protocols. + +Those interfaces can communicate with the configured gateway only. +Meaning that all traffic sent from the network interface will be sent +to the learned MAC address of the configured gateway. + +The network interface behaves like a router accepting all traffic +sent to its own MAC address. This allows to send and receive traffic +for prefixes advertised via routing protocols or configured statically +on the connected device under test. + +The BNG Blaster will also respond to all ICMP echo requests sent to its +own MAC address. + +.. include:: configuration/interfaces_network.rst + +The BNG Blaster supports multiple network interfaces +as shown in the example below. + +.. code-block:: json + + { + "interfaces": { + "tx-interval": 1, + "rx-interval": 1, + "io-slots": 4096, + "network": [ + { + "interface": "eth2", + "address": "10.0.0.1", + "gateway": "10.0.0.2", + "address-ipv6": "fc66:1337:7331::1", + "gateway-ipv6": "fc66:1337:7331::2" + }, + { + "interface": "eth3", + "address": "10.0.1.1", + "gateway": "10.0.1.2", + "address-ipv6": "fc66:1337:7331:1::1", + "gateway-ipv6": "fc66:1337:7331:1::2" + } + ], + } + } + +Using multiple network interfaces requires to select which network interface +to be used otherwise one of the interface is selected automatically. Therefore +the configuration option ``network-interface`` is supported in different sections. + +Access Interfaces +----------------- + +.. _access-interface: + +The access interface are used to emulate PPPoE and IPoE clients. + +.. include:: configuration/interfaces_access.rst + +For all modes it is possible to configure between zero and three VLAN +tags on the access interface as shown below. + +.. code-block:: none + + [ethernet][outer-vlan][inner-vlan][third-vlan][pppoe]... + + +Untagged +~~~~~~~~ +With untagged only one session is possible. + +.. code-block:: json + + { + "access": { + "interface": "eth1", + "outer-vlan-min": 0, + "outer-vlan-max": 0, + "inner-vlan-min": 0, + "inner-vlan-max": 0 + } + } + +Single Tagged +~~~~~~~~~~~~~ +.. code-block:: json + + { + "access": { + "interface": "eth1", + "outer-vlan-min": 1, + "outer-vlan-max": 4049, + "inner-vlan-min": 0, + "inner-vlan-max": 0 + } + } + + +Double Tagged +~~~~~~~~~~~~~ +.. code-block:: json + + { + "access": { + "interface": "eth1", + "outer-vlan-min": 1, + "outer-vlan-max": 4049, + "inner-vlan-min": 7, + "inner-vlan-max": 7 + } + } + +Triple Tagged +~~~~~~~~~~~~~ +.. code-block:: json + + { + "access": { + "interface": "eth1", + "outer-vlan-min": 10, + "outer-vlan-max": 20, + "inner-vlan-min": 128, + "inner-vlan-max": 4000, + "third-vlan": 7 + } + } + +The BNG Blaster supports also multiple access interfaces +or VLAN ranges as shown in the example below. + +.. code-block:: json + + { + "access": [ + { + "interface": "eth1", + "type": "pppoe", + "username": "pta@rtbrick.com", + "outer-vlan-min": 1000, + "outer-vlan-max": 1999, + "inner-vlan-min": 7, + "inner-vlan-max": 7 + }, + { + "interface": "eth1", + "type": "pppoe", + "username": "l2tp@rtbrick.com", + "outer-vlan-min": 2000, + "outer-vlan-max": 2999, + "inner-vlan-min": 7, + "inner-vlan-max": 7 + }, + { + "interface": "eth3", + "type": "pppoe", + "username": "test@rtbrick.com", + "outer-vlan-min": 128, + "outer-vlan-max": 4000, + "inner-vlan-min": 7, + "inner-vlan-max": 7 + }, + { + "interface": "eth4", + "type": "ipoe", + "outer-vlan-min": 8, + "outer-vlan-max": 9, + "address": "200.0.0.1", + "address-iter": "0.0.0.4", + "gateway": "200.0.0.2", + "gateway-iter": "0.0.0.4" + } + ] + } + + +The configuration attributes for username, agent-remote-id and agent-circuit-id +support also some variable substitution. The variable ``{session-global}`` will +be replaced with a number starting from 1 and incremented for every new session. +where as the variable ``{session}`` is incremented per interface section. + +In VLAN mode ``N:1`` only one VLAN combination is supported per access interface section. +This means that only VLAN min or max is considered as VLAN identifier. + +.. code-block:: json + + { + "access": [ + { + "interface": "eth1", + "type": "pppoe", + "vlan-mode": "N:1", + "username": "test@rtbrick.com", + "outer-vlan-min": 7 + }, + { + "interface": "eth2", + "type": "pppoe", + "vlan-mode": "N:1", + "username": "test@rtbrick.com", + "outer-vlan-min": 2000, + "inner-vlan-min": 7, + }, + ] + } + +A10NSP Interfaces +----------------- + +.. _a10nsp-interface: + +The A10NSP interface emulates an layer two provider interface. The term A10 +refers to the end-to-end ADSL network reference model from TR-025. + +The A10NSP interface is required for :ref:`L2BSA ` tests. + +.. include:: configuration/interfaces_a10nsp.rst + +The BNG Blaster supports multiple A10NSP interfaces +as shown in the example below. + +.. code-block:: json + + { + "interfaces": { + "tx-interval": 1, + "rx-interval": 1, + "a10nsp": [ + { + "interface": "eth4", + "qinq": true, + "mac": "02:00:00:ff:ff:01" + }, + { + "interface": "eth5", + "qinq": false, + "mac": "02:00:00:ff:ff:02" + } + ], + } + } + +You can define multiple interfaces with the same MAC +address to emulate some static link aggregation (without LACP). diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 00000000..eccce091 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,353 @@ +Quickstart Guide +================ + +In this guide, we’ll walk you through the BNG Blaster basics. All the +examples here work without having network devices to be tested. + +First you need to :ref:`install ` the BNG Blaster on your machine. + +In the next step, you create a virtual ethernet interface pair that can be +used by the BNG Blaster to send and received traffic. + +.. code-block:: none + + sudo ip link add veth1.1 type veth peer name veth1.2 + sudo ip link set veth1.1 up + sudo ip link set veth1.2 up + +PPPoE +----- + +Let's start with a simple PPPoE setup where BNG Blaster emulates the +client and server. On the first interface we use an :ref:`A10NSP interface ` +which includes a lightweight PPPoE server. The other interface is +configured as PPPoE client. + +The configured :ref:`session traffic ` generates +bidirectional traffic between client and server. There is also +one more bound :ref:`traffic stream ` configured. + +**pppoe.json:** + +.. code-block:: json + + { + "interfaces": { + "a10nsp": [ + { + "__comment__": "PPPoE Server", + "interface": "veth1.1" + } + ], + "access": [ + { + "__comment__": "PPPoE", + "interface": "veth1.2", + "type": "pppoe", + "outer-vlan-min": 1, + "outer-vlan-max": 4000, + "inner-vlan": 7, + "stream-group-id": 1 + } + ] + }, + "pppoe": { + "reconnect": true + }, + "dhcpv6": { + "enable": false + }, + "session-traffic": { + "ipv4-pps": 1 + }, + "streams": [ + { + "stream-group-id": 1, + "name": "S1", + "type": "ipv4", + "direction": "both", + "priority": 128, + "length": 256, + "pps": 1, + "a10nsp-interface": "veth1.1" + } + ] + } + +Now you can start the BNG Blaster with this configuration. + +.. code-block:: none + + $ sudo bngblaster -C pppoe.json + Mar 30 14:27:59.303904 Resolve network interfaces + Mar 30 14:27:59.303952 All network interfaces resolved + Mar 30 14:27:59.396765 ALL SESSIONS ESTABLISHED + +After pressing ``ctrl+c`` the test should be stopped and a detailed +report printed. + +Let's advance the test by enabling some features explained below. + +.. code-block:: none + + $ sudo bngblaster -C pppoe.json -c 1 -L test.log -l ip -J report.json -j sessions -j streams -P test.pcap -S run.sock -I + +* ``-C test.json`` loads the configuration file +* ``-c 1`` defines how many sessions to be emulated, you can increase the number to see what happens... +* ``-L test.log`` creates an optional logging file +* ``-l ip`` enables the IP address logging +* ``-J report.json`` generates a final JSON report at the end +* ``-j sessions`` include detailed results for every session in the JSON report +* ``-j streams`` include detailed results for every stream in the JSON report +* ``-P test.pcap`` generates a PCAP file +* ``-S run.sock`` opens the JSON RPC API socket +* ``-I`` start interactive courses user interface + +.. image:: images/quickstart1.png + :alt: BNG Blaster Interactive + +Now let's try to press ``F1`` to navigate through the different views. All supported +keyboard inputs are listed in the top left corner. After pressing ``F9`` the test +should be stopped. + +If the test is still running, you can open a second terminal. Then go to the same +directory from where you started the BNG Blaster and enter the following command. + +.. code-block:: none + + $ sudo bngblaster-cli run.sock session-info session-id 1 | jq . + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "session-info": { + "type": "pppoe", + "session-id": 1, + "session-state": "Established", + "interface": "veth1.2", + "outer-vlan": 1, + "inner-vlan": 7, + "mac": "02:00:00:00:00:01", + "username": "user1@rtbrick.com", + "reply-message": "BNG-Blaster-A10NSP", + "lcp-state": "Opened", + "ipcp-state": "Opened", + "ip6cp-state": "Opened", + "ipv4-address": "10.10.10.10", + "ipv4-dns1": "10.12.12.10", + "ipv4-dns2": "10.13.13.10", + "dhcpv6-state": "Init", + "tx-packets": 87, + "rx-packets": 80, + "rx-fragmented-packets": 0, + "session-traffic": { + "total-flows": 2, + "verified-flows": 1, + "first-seq-rx-access-ipv4": 1, + "first-seq-rx-access-ipv6": 0, + "first-seq-rx-access-ipv6pd": 0, + "first-seq-rx-network-ipv4": 1, + "first-seq-rx-network-ipv6": 0, + "first-seq-rx-network-ipv6pd": 0, + "access-tx-session-packets": 34, + "access-rx-session-packets": 34, + "access-rx-session-packets-loss": 0, + "network-tx-session-packets": 34, + "network-rx-session-packets": 34, + "network-rx-session-packets-loss": 0, + "access-tx-session-packets-ipv6": 0, + "access-rx-session-packets-ipv6": 0, + "access-rx-session-packets-ipv6-loss": 0, + "network-tx-session-packets-ipv6": 0, + "network-rx-session-packets-ipv6": 0, + "network-rx-session-packets-ipv6-loss": 0, + "access-tx-session-packets-ipv6pd": 0, + "access-rx-session-packets-ipv6pd": 0, + "access-rx-session-packets-ipv6pd-loss": 0, + "network-tx-session-packets-ipv6pd": 0, + "network-rx-session-packets-ipv6pd": 0, + "network-rx-session-packets-ipv6pd-loss": 0 + }, + "a10nsp": { + "interface": "veth1.1", + "s-vlan": 1, + "qinq-send": false, + "qinq-received": false, + "tx-packets": 46, + "rx-packets": 87 + } + } + } + +You can also try other :ref:`commands ` to get familiar with the API. + +After the test has stopped, you can also check the final JSON report (``jq . report.json``), +log, and PCAP files. + +ISIS +---- + +In the following example, we create two :ref:`ISIS ` nodes (R1 and R2) with an emulated +ISIS topology attached to R1 (`test.mrt``). + +**isis.json:** + +.. code-block:: json + + { + "interfaces": { + "network": [ + { + "interface": "veth1.1", + "address": "10.0.0.1/24", + "gateway": "10.0.0.2", + "address-ipv6": "fc66:1337:7331::1/64", + "gateway-ipv6": "fc66:1337:7331::2", + "isis-instance-id": 1, + "isis-level": 1 + }, + { + "interface": "veth1.2", + "address": "10.0.0.2/24", + "gateway": "10.0.0.1", + "address-ipv6": "fc66:1337:7331::2/64", + "gateway-ipv6": "fc66:1337:7331::1", + "isis-instance-id": 2, + "isis-level": 1 + } + ] + + }, + "isis": [ + { + "instance-id": 1, + "area": [ + "49.0001/24", + "49.0002/24" + ], + "system-id": "1921.6800.1001", + "router-id": "192.168.1.1", + "hostname": "R1", + "sr-base": 1000, + "sr-range": 100, + "sr-node-sid": 1, + "level1-auth-key": "secret123", + "level1-auth-type": "md5", + "external": { + "mrt-file": "test.mrt", + "connections": [ + { + "system-id": "1921.6800.0000.00", + "l1-metric": 1000, + "l2-metric": 2000 + } + ] + } + }, + { + "instance-id": 2, + "area": [ + "49.0001/24", + "49.0002/24" + ], + "system-id": "1921.6800.1002", + "router-id": "192.168.1.2", + "hostname": "R2", + "sr-base": 1000, + "sr-range": 100, + "sr-node-sid": 2, + "level1-auth-key": "secret123", + "level1-auth-type": "md5" + } + ], + "streams": [ + { + "name": "RAW1", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "destination-ipv4-address": "192.168.1.2", + "length": 256, + "pps": 1, + "network-interface": "veth1.1" + } + ] + } + +Now use the included tool ``lspgen`` to generate the attached ISIS topology. + +.. code-block:: none + + $ lspgen -a 49.0001/24 -K secret123 -T md5 -C 1921.6800.1001 -m test.mrt + Mar 30 14:54:19.647569 Add context for instance default, protocol isis, topology unicast + Mar 30 14:54:19.647630 Add connector to 0x192168001001 + Mar 30 14:54:19.647633 LSP generation parameters + Mar 30 14:54:19.647639 Area 49.0001/24 + Mar 30 14:54:19.647642 Level 1, sequence 0x1, lsp-lifetime 65535 + Mar 30 14:54:19.647645 Authentication-key secret123, Authentication-type md5 + Mar 30 14:54:19.647648 IPv4 Node Base Prefix 192.168.0.0/32 + Mar 30 14:54:19.647651 IPv4 Link Base Prefix 172.16.0.0/31 + Mar 30 14:54:19.647654 IPv4 External Base Prefix 10.0.0.0/28 + Mar 30 14:54:19.647657 IPv6 Node Base Prefix fc00::c0a8:0/128 + Mar 30 14:54:19.647660 IPv6 Link Base Prefix fc00::ac10:0/127 + Mar 30 14:54:19.647669 IPv6 External Base Prefix fc00::a00:0/124 + Mar 30 14:54:19.647672 SRGB base 10000, range 2000 + Mar 30 14:54:19.647678 Generating a graph of 10 nodes and 20 links + Mar 30 14:54:19.647813 Root node 1921.6800.0000.00 + +Finally, you can start the BNG Blaster. + +.. code-block:: none + + $ sudo bngblaster -C veth1-isis.json -l isis -P test.pcap -S run.sock + Mar 30 14:56:11.981279 Init IS-IS instance 1 + Mar 30 14:56:11.981314 Load ISIS MRT file test.mrt + Mar 30 14:56:11.981335 Init IS-IS instance 2 + Mar 30 14:56:12.031917 Add network interface veth1.1 to IS-IS instance 1 + Mar 30 14:56:12.087877 Add network interface veth1.2 to IS-IS instance 2 + Mar 30 14:56:12.087971 opened pcap-file test.pcap + Mar 30 14:56:12.088013 Opened control socket run.sock + Mar 30 14:56:13.088035 Resolve network interfaces + Mar 30 14:56:13.088050 All network interfaces resolved + Mar 30 14:56:22.093906 ISIS L1 adjacency UP on interface veth1.2 + Mar 30 14:56:22.093964 ISIS L1 adjacency UP on interface veth1.1 + +If the test is still running, you can open a second terminal, go to the same directory +from where you started the BNG Blaster and enter the following command. + +.. code-block:: none + + $ sudo bngblaster-cli run.sock isis-adjacencies + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "isis-adjacencies": [ + { + "interface": "veth1.1", + "type": "P2P", + "level": "L1", + "instance-id": 1, + "adjacency-state": "Up", + "peer": { + "system-id": "1921.6800.1002" + } + }, + { + "interface": "veth1.2", + "type": "P2P", + "level": "L1", + "instance-id": 2, + "adjacency-state": "Up", + "peer": { + "system-id": "1921.6800.1001" + } + } + ] + } + +You can also try other :ref:`commands ` to get familiar with the API. \ No newline at end of file diff --git a/docs/source/reference/architecture.rst b/docs/source/reference/architecture.rst new file mode 100644 index 00000000..26b87ce3 --- /dev/null +++ b/docs/source/reference/architecture.rst @@ -0,0 +1,52 @@ +Architecture +------------ + +The BNG Blaster has been completely built from scratch in **C**. This includes user-space implementations +of the entire protocol stack. Its core is based on a very simple event loop that serves timers and +signals. The timers have been built using a lightweight constant time (*O(1)*) library. The timer library +was built to start, restart and delete the protocol session FSM timers quickly and at scale. + +The BNG Blaster expects a Linux kernel network interface which is up, but not configured with any IP addresses +or VLAN as it expects to receive and transmit RAW ethernet packets. + +The BNG Blaster does I/O using high-speed polling timers with a mix of Linux +`RAW Packet Sockets `_ and +`Packet MMAP `_. + +The second one is a so-called PACKET_RX_RING/PACKET_TX_RING abstraction where a user-space program gets a fast +lane into reading and writing to kernel interfaces using a shared ring buffer. The shared ring buffer is a +memory-mapped “window” shared between kernel and userspace. This low overhead abstraction allows to transmit +and receive traffic without doing expensive system calls. Sending and transmitting traffic via Packet MMAP is +as easy as copying a packet into a buffer and setting a flag. + +.. image:: ../images/bbl_arch.png + :alt: BNG Blaster Architecture + +The BNG Blaster supports many configurable I/O modes listed with ``bngblaster -v`` but except for the default +mode ``packet_mmap_raw`` all other modes are currently considered experimental. In the default mode, all +packets are received in a Packet MMAP ring buffer and sent through RAW packet sockets. This combination +was the most efficient in our benchmark tests. + +BNG Blaster's primary design goal is to simulate thousands of subscriber CPE’s with a small hardware resource +footprint. Simple to use and easy to integrate into our robot test automation infrastructure. This allows for +simulation of massive PPPoE or IPoE (DHCP) subscribers including IPTV, traffic verification, and convergence +testing from a single medium scale virtual machine or to run from a laptop. + +The BNG Blaster provides three types of interfaces. The first interface is called the access interface which +emulates the PPPoE or IPoE sessions. The second interface-type is called network interface. This is used for +emulating the core-facing side of the internet with optional routing protocols. The last type is called a10nsp +interface which emulates an layer two provider interface. The term A10 refers to the end-to-end ADSL network +reference model from TR-025. + +.. image:: ../images/bbl_interfaces.png + :alt: BNG Blaster Interfaces + +This allows for verification of IP reachability by sending bidirectional traffic between all sessions +on the access interface and the network interface. The network interface is also used to inject downstream +multicast test traffic for IPTV tests. It is also possible to send RAW traffic streams between network +interfaces without any access interface defined for non-BNG testing. + +One popular example for non-BNG tests with the BNG Blaster is the verification of a BGP full-table by injecting +around 1M prefixes and setting up traffic streams for all prefixes with at least 1 PPS (1M PPS). +The BNG Blaster is able to verify and analyze every single flow with detailed per-flow statistics +(receive rate, loss, latency, …). \ No newline at end of file diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst new file mode 100644 index 00000000..ae08285e --- /dev/null +++ b/docs/source/reference/index.rst @@ -0,0 +1,8 @@ +Reference +========= + +.. toctree:: + :maxdepth: 1 + + architecture.rst + traffic.rst diff --git a/docs/source/reference/traffic.rst b/docs/source/reference/traffic.rst new file mode 100644 index 00000000..bbad0fa6 --- /dev/null +++ b/docs/source/reference/traffic.rst @@ -0,0 +1,139 @@ +BNG Blaster Traffic +------------------- + +.. _bbl_header: + +Blaster Header and Fast Decode Signature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The 48 Byte fixed size BNG Blaster Header is added to all data packets +for traffic validation and fast decoding. The header is expected on the +last 48 bytes of the packet. + +The type is set to 1 for all unicast session traffic and 2 for +IPv4 multicast traffic. + +Unicast Session Traffic +^^^^^^^^^^^^^^^^^^^^^^^ + +The 64 bit session key is used for all traffic from access (upstream) +and to access (downstream) interfaces to identify the corresponding +session which has send or should receive the packet. + +.. code-block:: none + + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BNG Blaster Magic Sequence | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Sub-Type | Direction | TX TOS | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Session Identifier | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Session Access Interface Index | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Session Outer VLAN | Session Inner VLAN | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Flow Identifier | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Flow Sequence Number | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Nanosecond Send Timestamp | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +.. image:: ../images/bbl_header.png + :alt: BNG Blaster Header + +Multicast Traffic +^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BNG Blaster Magic Sequence | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Sub-Type | Direction | TX TOS | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Group | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Flow Identifier | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Flow Sequence Number | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Nanosecond Send Timestamp | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +.. note:: + All attributes except IP addresses in the Blaster Header are + stored in host byte order for faster processing + (LE or BE depending on test system). + +BNG Blaster Magic Sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The 64 bit magic sequence is the word ``RtBrick!`` decoded as ASCII: + +.. code-block:: none + + 0x5274427269636b21 + +The magic number allows to check for it on a given offset and process +only blaster header instead of decoding the whole packet for faster +packet processing. + +Flow Identifier +^^^^^^^^^^^^^^^ + +The 64 bit flow identifier is a global unique number which identifies +the flow. + +Flow Sequence Number +^^^^^^^^^^^^^^^^^^^^ + +The 64 bit flow sequence number is sequential number starting with 1 +and incremented per packet primary used to identity packet loss. + +This number 0 means that sequencing is disabled. + +Nanosecond Send Timestamps +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The 64 bit nanoseconds send timestamp is used for optional latency and +jitter calculations. + +.. code-block:: none + + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Seconds | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Nano Seconds | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +The timestamp 0 means that timestamps are disabled. + +Wireshark Plugin +~~~~~~~~~~~~~~~~ +**Wireshark BNG Blaster Header Dissector** + +Download the LUA dissector script +`bbl_header.lua `_ +and start wireshark as shown below from the directory where the script is placed. + +.. code-block:: none + + $ wireshark -X lua_script:bbl_header.lua + diff --git a/docs/source/reports.rst b/docs/source/reports.rst new file mode 100644 index 00000000..7e9b72e6 --- /dev/null +++ b/docs/source/reports.rst @@ -0,0 +1,265 @@ +Reports +======= + +The BNG Blaster is able to generate detailed result reports +at the end of of the test execution. + +Standard Output Reports +----------------------- + +.. code-block:: none + + ____ __ ____ _ __ ,/ + / __ \ / /_ / __ ) _____ (_)_____ / /__ ,'/ + / /_/ // __// __ |/ ___// // ___// //_/ ,' / + / _, _// /_ / /_/ // / / // /__ / ,< ,' /_____, + /_/ |_| \__//_____//_/ /_/ \___//_/|_| .'____ ,' + ____ _ _ ______ ____ _ _ / ,' + / __ ) / | / // ____/ / __ ) / /____ _ _____ / /_ ___ ____ / ,' + / __ |/ |/ // / __ / __ |/ // __ `// ___// __// _ \ / ___/ /,' + / /_/ // /| // /_/ / / /_/ // // /_/ /(__ )/ /_ / __// / / + /_____//_/ |_/ \____/ /_____//_/ \__,_//____/ \__/ \___//_/ + + Report: + + Sessions PPPoE: 500 IPoE: 0 + Sessions established: 500/500 + DHCPv6 sessions established: 500 + Setup Time: 396 ms + Setup Rate: 1262.63 CPS (MIN: 1262.63 AVG: 1262.63 MAX: 1262.63) + Flapped: 0 + + Network Interface ( eth2 ): + TX: 25503 packets + RX: 24254 packets + TX Session: 8500 packets + RX Session: 8248 packets (0 loss) + TX Session IPv6: 8500 packets + RX Session IPv6: 8000 packets (0 loss) + TX Session IPv6PD: 8500 packets + RX Session IPv6PD: 8000 packets (0 loss) + TX Multicast: 0 packets + RX Drop Unknown: 1 packets + TX Encode Error: 0 + RX Decode Error: 0 packets + TX Send Failed: 0 + TX No Buffer: 0 + TX Poll Kernel: 0 + RX Poll Kernel: 3932 + + Access Interface ( eth1 ): + TX: 33250 packets + RX: 34047 packets + TX Session: 8500 packets + RX Session: 8248 packets (0 loss, 0 wrong session) + TX Session IPv6: 8500 packets + RX Session IPv6: 8000 packets (0 loss, 0 wrong session) + TX Session IPv6PD: 8500 packets + RX Session IPv6PD: 8000 packets (0 loss, 0 wrong session) + RX Multicast: 0 packets (0 loss) + RX Drop Unknown: 1 packets + TX Encode Error: 33250 packets + RX Decode Error: 0 packets + TX Send Failed: 0 + TX No Buffer: 0 + TX Poll Kernel: 0 + RX Poll Kernel: 3932 + + Access Interface Protocol Packet Stats: + ARP TX: 0 RX: 0 + PADI TX: 500 RX: 0 + PADO TX: 0 RX: 500 + PADR TX: 500 RX: 0 + PADS TX: 0 RX: 500 + PADT TX: 1 RX: 499 + LCP TX: 2249 RX: 2249 + PAP TX: 250 RX: 250 + CHAP TX: 250 RX: 500 + IPCP TX: 1500 RX: 1500 + IP6CP TX: 1500 RX: 1500 + IGMP TX: 0 RX: 1298 + ICMP TX: 0 RX: 0 + ICMPv6 TX: 500 RX: 500 + DHCPv6 TX: 500 RX: 500 + + Access Interface Protocol Timeout Stats: + LCP Echo Request: 0 + LCP Request: 0 + IPCP Request: 0 + IP6CP Request: 0 + PAP: 0 + CHAP: 0 + ICMPv6 RS: 0 + DHCPv6 Request: 0 + + Session Traffic: + Config: + IPv4 PPS: 1 + IPv6 PPS: 1 + IPv6PD PPS: 1 + Verified Traffic Flows: 3000/3000 + Access IPv4: 500 + Access IPv6: 500 + Access IPv6PD: 500 + Network IPv4: 500 + Network IPv6: 500 + Network IPv6PD: 500 + First Sequence Number Received: + Access IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) + Access IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Access IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Network IPv4 MIN: 1 ( 1.000s) MAX: 2 ( 2.000s) + Network IPv6 MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + Network IPv6PD MIN: 2 ( 2.000s) MAX: 2 ( 2.000s) + + +JSON Reports +------------ + +A detailed JSON report is generated if enabled using the optional +argument ``-J `` as shown in the example below. + +.. code-block:: json + + { + "report": { + "sessions": 500, + "sessions-pppoe": 500, + "sessions-ipoe": 0, + "sessions-established": 500, + "sessions-flapped": 0, + "setup-time-ms": 396, + "setup-rate-cps": 1263, + "setup-rate-cps-min": 1263, + "setup-rate-cps-avg": 1263, + "setup-rate-cps-max": 1263, + "dhcpv6-sessions-established": 500, + "network-interfaces": [ + { + "name": "eth2", + "tx-packets": 25503, + "rx-packets": 24254, + "tx-session-packets": 8500, + "rx-session-packets": 8248, + "rx-session-packets-loss": 0, + "tx-session-packets-avg-pps-max": 500, + "rx-session-packets-avg-pps-max": 500, + "tx-session-packets-ipv6": 8500, + "rx-session-packets-ipv6": 8000, + "rx-session-packets-ipv6-loss": 0, + "tx-session-packets-avg-pps-max-ipv6": 500, + "rx-session-packets-avg-pps-max-ipv6": 500, + "tx-session-packets-ipv6pd": 8500, + "rx-session-packets-ipv6pd": 8000, + "rx-session-packets-ipv6pd-loss": 0, + "tx-session-packets-avg-pps-max-ipv6pd": 500, + "rx-session-packets-avg-pps-max-ipv6pd": 500, + "tx-multicast-packets": 0 + } + ], + "access-interfaces": [ + { + "name": "eth1", + "tx-packets": 33250, + "rx-packets": 34047, + "tx-session-packets": 8500, + "rx-session-packets": 8248, + "rx-session-packets-loss": 0, + "rx-session-packets-wrong-session": 0, + "tx-session-packets-avg-pps-max": 500, + "rx-session-packets-avg-pps-max": 500, + "tx-session-packets-ipv6": 8500, + "rx-session-packets-ipv6": 8000, + "rx-session-packets-ipv6-loss": 0, + "rx-session-packets-ipv6-wrong-session": 0, + "tx-session-packets-avg-pps-max-ipv6": 500, + "rx-session-packets-avg-pps-max-ipv6": 500, + "tx-session-packets-ipv6pd": 8500, + "rx-session-packets-ipv6pd": 8000, + "rx-session-packets-ipv6pd-loss": 0, + "rx-session-packets-ipv6pd-wrong-session": 0, + "tx-session-packets-avg-pps-max-ipv6pd": 500, + "rx-session-packets-avg-pps-max-ipv6pd": 500, + "rx-multicast-packets": 0, + "rx-multicast-packets-loss": 0, + "protocol-stats": { + "arp-tx": 0, + "arp-rx": 0, + "padi-tx": 500, + "pado-rx": 500, + "padr-tx": 500, + "pads-rx": 500, + "padt-tx": 1, + "padt-rx": 499, + "lcp-tx": 2249, + "lcp-rx": 2249, + "pap-tx": 250, + "pap-rx": 250, + "chap-tx": 250, + "chap-rx": 500, + "ipcp-tx": 1500, + "ipcp-rx": 1500, + "ip6cp-tx": 1500, + "ip6cp-rx": 1500, + "igmp-tx": 0, + "igmp-rx": 1298, + "icmp-tx": 0, + "icmp-rx": 0, + "icmpv6-tx": 500, + "icmpv6-rx": 500, + "dhcpv6-tx": 500, + "dhcpv6-rx": 500, + "lcp-echo-timeout": 0, + "lcp-request-timeout": 0, + "ipcp-request-timeout": 0, + "ip6cp-request-timeout": 0, + "pap-timeout": 0, + "chap-timeout": 0, + "icmpv6-rs-timeout": 0, + "dhcpv6-timeout": 0 + } + ], + "session-traffic": { + "config-ipv4-pps": 1, + "config-ipv6-pps": 1, + "config-ipv6pd-pps": 1, + "total-flows": 3000, + "verified-flows": 3000, + "verified-flows-access-ipv4": 500, + "verified-flows-access-ipv6": 500, + "verified-flows-access-ipv6pd": 500, + "verified-flows-network-ipv4": 500, + "verified-flows-network-ipv6": 500, + "verified-flows-network-ipv6pd": 500, + "first-seq-rx-access-ipv4-min": 1, + "first-seq-rx-access-ipv4-max": 2, + "first-seq-rx-access-ipv6-min": 2, + "first-seq-rx-access-ipv6-max": 2, + "first-seq-rx-access-ipv6pd-min": 2, + "first-seq-rx-access-ipv6pd-max": 2, + "first-seq-rx-network-ipv4-min": 1, + "first-seq-rx-network-ipv4-max": 2, + "first-seq-rx-network-ipv6-min": 2, + "first-seq-rx-network-ipv6-max": 2, + "first-seq-rx-network-ipv6pd-min": 2, + "first-seq-rx-network-ipv6pd-max": 2 + } + } + } + +The optional argument ``-j sessions`` allows to include per session statistics +in the report file. Similar with ``-j streams`` which allows to include per stream +statistics. Both options could be also combined. + +Those extensive JSON reports could be easily verified with simple python scripts to +extract the desired results. + +.. code-block:: python + + #!/usr/bin/env python3 + import json + + # Open JSON report ... + with open('report.json') as f: + data = json.load(f) + # Analyze data ... \ No newline at end of file diff --git a/docs/source/routing/bgp.rst b/docs/source/routing/bgp.rst new file mode 100644 index 00000000..49f09b17 --- /dev/null +++ b/docs/source/routing/bgp.rst @@ -0,0 +1,184 @@ +.. _bgp: + +BGP +--- + +The Border Gateway Protocol (BGP) is a standardized exterior gateway protocol +designed to exchange routing and reachability information among autonomous systems +(AS) on the internet. BGP is classified as a path-vector routing protocol, and it +makes routing decisions based on paths, network policies, or rule-sets configured +by a network operator. + +Configuration +~~~~~~~~~~~~~ + +Following an example BGP configuration with one session. + +.. code-block:: json + + { + "interfaces": { + "network": [ + { + "interface": "eth1", + "address": "10.0.1.2/24", + "gateway": "10.0.1.1" + } + ] + }, + "bgp": [ + { + "local-ipv4-address": "10.0.1.2", + "peer-ipv4-address": "10.0.1.1", + "raw-update-file": "test.bgp", + "local-as": 65001, + "peer-as": 65001 + } + ] + } + +.. include:: ../configuration/bgp.rst + + +BGP Sessions +~~~~~~~~~~~~ + +Every BGP session is opened with the capabilities for the following +address families: + ++ IPv4 unicast ++ IPv4 labelled unicast ++ IPv6 unicast ++ IPv6 labelled unicast + +Limitations +~~~~~~~~~~~ + +BGP authentication is currently not supported but already +planned as enhancement in one of the next releases. + +RAW Update Files +~~~~~~~~~~~~~~~~ + +The BNG Blaster is able to inject BGP messages from a pre-compiled +RAW update file into the defined sessions. A RAW update file is not +more than a pre-compiled binary stream of BGP messages, typically +but not limited to update messages. + +.. code-block:: none + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + + + | | + + + + | Marker | + + + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | Type | ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++++ + . + . + . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + + + | | + + + + | Marker | + + + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | Type | ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++++ + +Those files can be created using the included BGP RAW update generator +script ``bgpupdate`` or manually using libraries like scapy or converters +from PCAP or MRT files. + +The configured ``raw-update-file`` under the BGP session is loaded +during Blaster startup phase and send as soon as the session is +established. + +The ``bgp-raw-update`` command allows to send further updates during +the session lifetime. + +``$ sudo bngblaster-cli run.sock bgp-raw-update file update1.bgp`` + +This allows in example to load a full table after session has +started and manually trigger a series of changes using incremental +updates files. + +All BGP RAW update files are loaded once and can than be used by +multiple sessions. Meaning if two or more sessions reference the +same file identified by file name, this file is loaded once into +memory and used by multiple sessions. + +Therefore for incremental updates, it may makes sense to pre-load +via ``bgp-raw-update-files`` configuration. + +.. code-block:: json + + { + "bgp": [ + { + "local-ipv4-address": "10.0.1.2", + "peer-ipv4-address": "10.0.1.1", + "raw-update-file": "start.bgp", + "local-as": 65001, + "peer-as": 65001 + } + ], + "bgp-raw-update-files": [ + "update1.bgp", + "update2.bgp" + ] + } + +Incremental updates not listed here will be loaded dynamically as soon +as referenced by first session. + +BGP RAW Update Generator +~~~~~~~~~~~~~~~~~~~~~~~~ + +The BGP RAW update generator is a simple tool to generate BGP RAW update +streams for use with the BNG Blaster. + +.. code-block:: none + + $ bgpupdate --help + usage: bgpupdate [-h] [-a ASN] -n ADDRESS [-N N] -p PREFIX [-P N] [-m LABEL] + [-M N] [-l LOCAL_PREF] [-f FILE] [-w] [--end-of-rib] + [--append] [--pcap FILE] [--log-level {warning,info,debug}] + + optional arguments: + -h, --help show this help message and exit + -a ASN, --asn ASN autonomous system number + -n ADDRESS, --next-hop-base ADDRESS + next-hop base address (IPv4 or IPv6) + -N N, --next-hop-num N + next-hop count + -p PREFIX, --prefix-base PREFIX + prefix base network (IPv4 or IPv6) + -P N, --prefix-num N prefix count + -m LABEL, --label-base LABEL + label base + -M N, --label-num N label count + -l LOCAL_PREF, --local-pref LOCAL_PREF + local preference + -f FILE, --file FILE output file + -w, --withdraw withdraw prefixes + --end-of-rib add end-of-rib message + --append append to file if exist + --pcap FILE write BGP updates to PCAP file + --log-level {warning,info,debug} + logging Level + + +The python BGP RAW update generator is a python script which uses +scapy to build BGP messages. Therefore this tool can be easily +modified, extend or used as blueprint for your own tools to generate +valid BGP update streams. diff --git a/docs/source/routing/index.rst b/docs/source/routing/index.rst new file mode 100644 index 00000000..bfc7e839 --- /dev/null +++ b/docs/source/routing/index.rst @@ -0,0 +1,13 @@ +Routing Protocols +================= + +There are various routing protocols supported like ISIS and BGP. +So you can use the BNG Blaster for end-to-end BNG and non-BNG +router testing. + +.. toctree:: + :maxdepth: 1 + + isis.rst + bgp.rst + mpls.rst diff --git a/docs/source/routing/isis.rst b/docs/source/routing/isis.rst new file mode 100644 index 00000000..0ce11ac9 --- /dev/null +++ b/docs/source/routing/isis.rst @@ -0,0 +1,359 @@ +.. _isis: + +ISIS +---- + +Intermediate System to Intermediate System (ISIS, also written IS-IS) +is a routing protocol designed to move information efficiently within +a network. + +The ISIS protocol is defined in ISO/IEC 10589:2002 as an international +standard within the Open Systems Interconnection (OSI) reference design. +The Internet Engineering Task Force (IETF) republished ISIS in RFC 1142, +but that RFC was later marked as historic by RFC 7142 because it republished +a draft rather than a final version of the ISO standard, causing confusion. + +ISIS has been called the de facto standard for large service provider +network backbones. + +The BNG Blaster is able to emulate multiple ISIS instances. An ISIS instance +is a virtual ISIS node with one or more network interfaces attached. Such a +node behaves like a "real router" including database synchronization and +flooding. Every instance generates a ``self`` originated LSP describing the +node itself. + +Configuration +~~~~~~~~~~~~~ + +Following an example ISIS configuration with one instance +attached to two network interfaces. + +.. code-block:: json + + { + "interfaces": { + "network": [ + { + "interface": "eth1", + "address": "10.0.1.2/24", + "gateway": "10.0.1.1", + "address-ipv6": "fc66:1337:7331:1::2/64", + "gateway-ipv6": "fc66:1337:7331:1::1", + "isis-instance-id": 1, + "isis-level": 1, + "isis-l1-metric": 100, + }, + { + "interface": "eth2", + "address": "10.0.2.2/24", + "gateway": "10.0.2.1", + "address-ipv6": "fc66:1337:7331:2::2/64", + "gateway-ipv6": "fc66:1337:7331:2::1", + "isis-instance-id": 1 + } + ] + }, + "isis": [ + { + "instance-id": 1, + "system-id": "0100.1001.0010", + "router-id": "10.10.10.10", + "hostname": "R1", + "area": [ + "49.0001/24", + "49.0002/24" + ], + "hello-padding": true, + "lsp-lifetime": 65535, + "level1-auth-key": "secret", + "level1-auth-type": "md5", + "sr-base": 2000, + "sr-range": 3600 + } + ] + } + +.. include:: ../configuration/isis.rst + +The support for multiple instances allows different use cases. One example might +be to create two instances connected to the device or network under test. Now +inject a LSP on one instance and check if learned over the tested network on +the other instance. + +Every ISIS instance can be also connected to an emulated link state graph loaded +by MRT files as shown in the example below. + +.. image:: ../images/bbl_isis.png + :alt: ISIS + +.. code-block:: json + + { + "isis": [ + { + "instance-id": 1, + "system-id": "0100.1001.0011", + "router-id": "10.10.10.11", + "hostname": "B1", + "external": { + "mrt-file": "test.mrt", + "connections": [ + { + "system-id": "0000.0000.0001", + "l1-metric": 1000, + "l2-metric": 2000 + } + ] + } + }, + { + "instance-id": 1, + "system-id": "0100.1001.0011", + "router-id": "10.10.10.12", + "hostname": "B2" + } + ] + } + +.. include:: ../configuration/isis_external.rst + +The The node ``N1`` in this example also needs to advertise the +reachability to the node ``B1``. + +.. include:: ../configuration/isis_external_connections.rst + + +Adjacencies +~~~~~~~~~~~ + +The BNG Blaster supports P2P adjacencies with 3-way-handshake only. + +``$ sudo bngblaster-cli run.sock isis-adjacencies`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "isis-adjacencies": [ + { + "interface": "eth1", + "type": "P2P", + "level": "L1", + "instance-id": 2, + "adjacency-state": "Up", + "peer": { + "system-id": "0100.1001.0022" + } + }, + { + "interface": "eth2", + "type": "P2P", + "level": "L1", + "instance-id": 1, + "adjacency-state": "Up", + "peer": { + "system-id": "0100.1001.0021" + } + } + ] + } + +Database +~~~~~~~~ + +The BNG Blaster distinguishes between three different source types of +LSP entries in the ISIS database. + +The type ``self`` is used for the self originated LSP describing the own +BNG Blaster ISIS instance. LSP entries of type ``adjacency`` are learned +via ISIS adjacencies. The type ``external`` is used for those LSP entries +learned via MRT files or injected via ``isis-lsp-update`` command. + +``$ sudo bngblaster-cli run.sock isis-database instance 1 level 1`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "isis-database": [ + { + "id": "0000.0000.0001.00-00", + "seq": 1, + "lifetime": 65535, + "lifetime-remaining": 65529, + "source-type": "external" + }, + { + "id": "0100.1001.0011.00-00", + "seq": 2, + "lifetime": 65535, + "lifetime-remaining": 65507, + "source-type": "self" + }, + { + "id": "0100.1001.0021.00-00", + "seq": 2, + "lifetime": 65524, + "lifetime-remaining": 65506, + "source-type": "adjacency", + "source-system-id": "0100.1001.0021" + }, + { + "id": "0100.1001.0022.00-00", + "seq": 2, + "lifetime": 65524, + "lifetime-remaining": 65506, + "source-type": "adjacency", + "source-system-id": "0100.1001.0021" + } + ] + } + +The BNG Blaster automatically purges all LSP's of type +``self`` and ``external`` during teardown. This is done by +generating LSP's with a newer sequence numbers and lifetime +of 30 seconds only. This lifetime is enough to flood the purge +LSP over te whole network under test. + +Flooding +~~~~~~~~ + +The BNG Blaster floods LSP's received to all other active +adjacencies of the ISIS instance except to those with peer +system-id equal to the source system-id of the LSP. + +Limitations +~~~~~~~~~~~ + +Currently only ISIS P2P links are supported. There is also +no support for route leaking between levels. + +MRT Files +~~~~~~~~~ + +The BNG Blaster is able to load LSP's from a MRT file as defined in +[RFC6396](https://datatracker.ietf.org/doc/html/rfc6396). + +.. code-block:: none + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Timestamp | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Subtype | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Message... (variable) + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +The message field contains the complete ISIS LSP PDU including +the ISIS common header starting with ``0x83``. + +Those files can be loaded at startup via configuration option +``"isis": { "external": { "mrt-file": "" } }`` or alternative +via ``isis-load-mrt`` command. + +``$ sudo bngblaster-cli run.sock isis-load-mrt file test.mrt instance 1`` + +LSP Update Command +~~~~~~~~~~~~~~~~~~ + +It is also possible to inject external LSP's using the ``isis-lsp-update`` +command. + +The command expects a list of hex encoded PDU's including +the ISIS common header starting with ``0x83``, + +``$ cat command.json | jq .`` + +.. code-block:: json + + { + "command": "isis-lsp-update", + "arguments": { + "instance": 1, + "pdu": [ + "831b0100120100000021ffff010203040506000000000003c0d103010403490001", + "831b0100120100000021ffff010203040506000100000003bad603010403490001" + ] + } + } + +LSPGEN +~~~~~~ + +The BNG Blaster includes a tool called ```lspgen`` which is able to generate +link state packets and topologies for export as MRT and PCAP files or directly +injected via BNG Blaster LSP update command. + +LSP Update via Scapy +~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to generate LSP's via Scapy +and inject them using the ``isis-lsp-update`` command. + +.. code-block:: python + + import sys + import socket + import os + import json + + from scapy.contrib.isis import * + + def error(*args, **kwargs): + """print error and exit""" + print(*args, file=sys.stderr, **kwargs) + sys.exit(1) + + + def execute_command(socket_path, request): + if os.path.exists(socket_path): + client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + client.connect(socket_path) + client.send(json.dumps(request).encode('utf-8')) + data = "" + while True: + junk = client.recv(1024) + if junk: + data += junk.decode('utf-8') + else: + break + print(json.dumps(json.loads(data), indent=4)) + except Exception as e: + error(e) + finally: + client.close() + else: + error("socket %s not found" % socket_path) + + + def main(): + """main function""" + socket_path = sys.argv[1] + + command = { + "command": "isis-lsp-update", + "arguments": { + "instance": 1, + "pdu": [] + } + } + + tlvs = ISIS_AreaTlv(areas=ISIS_AreaEntry(areaid='49.0001')) + pdu = ISIS_CommonHdr()/ISIS_L1_LSP(lifetime=65535, lspid='0102.0304.0506.00-00', seqnum=3, tlvs=tlvs) + command["arguments"]["pdu"].append(pdu.build().hex()) + + pdu = ISIS_CommonHdr()/ISIS_L1_LSP(lifetime=65535, lspid='0102.0304.0506.00-01', seqnum=3, tlvs=tlvs) + command["arguments"]["pdu"].append(pdu.build().hex()) + + execute_command(socket_path, command) + + + if __name__ == "__main__": + main() diff --git a/docs/source/routing/mpls.rst b/docs/source/routing/mpls.rst new file mode 100644 index 00000000..6e2c9a7d --- /dev/null +++ b/docs/source/routing/mpls.rst @@ -0,0 +1,3 @@ +MPLS +---- + diff --git a/docs/source/streams.rst b/docs/source/streams.rst new file mode 100644 index 00000000..b4f5c1b7 --- /dev/null +++ b/docs/source/streams.rst @@ -0,0 +1,350 @@ +.. _streams: + +Traffic Streams +=============== + +Traffic streams allow doing various forwarding verification +and QoS tests using BNG Blaster. + +.. image:: images/bbl_streams.png + :alt: Interactive Streams + +Traffic streams are be divided in bounded and raw streams. +The first one is bound to an access configuration and derives +addresses dynamically from the sessions. + +A raw stream is supported on :ref:`network interfaces ` only. + +Configuration +~~~~~~~~~~~~~ + +Following a simple PPPoE example with streams. + +.. code-block:: json + + { + "interfaces": { + "network": { + "interface": "eth2", + "address": "10.0.0.1/24", + "gateway": "10.0.0.2", + "address-ipv6": "fc66:1337:7331::1/64", + "gateway-ipv6": "fc66:1337:7331::2" + }, + "access": [ + { + "interface": "eth1", + "outer-vlan-min": 1001, + "outer-vlan-max": 2000, + "inner-vlan-min": 7, + "inner-vlan-max": 7, + "type": "pppoe", + "stream-group-id": 1 + }, + { + "interface": "eth1", + "outer-vlan-min": 2001, + "outer-vlan-max": 4000, + "inner-vlan": 7, + "type": "pppoe", + "stream-group-id": 2 + } + ] + }, + "streams": [ + { + "name": "BestEffort", + "stream-group-id": 1, + "type": "ipv4", + "direction": "both", + "pps": 1000 + }, + { + "name": "Voice", + "stream-group-id": 1, + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "vlan-priority": 2, + "network-ipv4-address": "10.0.0.10", + "pps": 100 + }, + { + "name": "BestEffort", + "stream-group-id": 2, + "type": "ipv4", + "direction": "both", + "pps": 1 + } + ] + } + +.. include:: configuration/streams.rst + +Stream Configuration File +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The command line argument ``-T `` allows to include +streams defined from a separate file. The format is equal to +streams defined in the actual configuration file. Such stream +configuration files could be generated by scripts and +easily merged with the base configuration. + +.. code-block:: json + + { + "streams": [] + } + +Stream Commands +~~~~~~~~~~~~~~~ + +The ``session-streams`` command returns detailed stream statistics per session. + +``$ sudo bngblaster-cli run.sock session-streams session-id 1`` + +.. code-block:: json + + { + "status": "ok", + "code": 200, + "session-streams": { + "session-id": 1, + "rx-packets": 59670, + "tx-packets": 54610, + "rx-accounting-packets": 59655, + "tx-accounting-packets": 54594, + "rx-pps": 1100, + "tx-pps": 1000, + "rx-bps-l2": 9028800, + "tx-bps-l2": 8240000, + "rx-mbps-l2": 9.0288, + "tx-mbps-l2": 8.24, + "streams": [ + { + "name": "BestEffort", + "direction": "upstream", + "flow-id": 1, + "rx-first-seq": 362, + "rx-last-seq": 54593, + "rx-tos-tc": 0, + "rx-outer-vlan-pbit": 0, + "rx-inner-vlan-pbit": 0, + "rx-len": 1014, + "tx-len": 1030, + "rx-packets": 54232, + "tx-packets": 54594, + "rx-loss": 0, + "rx-delay-nsec-min": 37650, + "rx-delay-nsec-max": 98595049, + "rx-pps": 1000, + "tx-pps": 1000, + "tx-bps-l2": 8240000, + "rx-bps-l2": 8112000, + "rx-bps-l3": 8000000, + "tx-mbps-l2": 8.24, + "rx-mbps-l2": 8.112, + "rx-mbps-l3": 8.0 + }, + { + "name": "BestEffort", + "direction": "downstream", + "flow-id": 2, + "rx-first-seq": 362, + "rx-last-seq": 54593, + "rx-tos-tc": 0, + "rx-outer-vlan-pbit": 0, + "rx-inner-vlan-pbit": 0, + "rx-len": 1026, + "tx-len": 1014, + "rx-packets": 54232, + "tx-packets": 54594, + "rx-loss": 0, + "rx-delay-nsec-min": 43550, + "rx-delay-nsec-max": 98903960, + "rx-pps": 1000, + "tx-pps": 1000, + "tx-bps-l2": 8112000, + "rx-bps-l2": 8208000, + "rx-bps-l3": 8000000, + "tx-mbps-l2": 8.112, + "rx-mbps-l2": 8.208, + "rx-mbps-l3": 8.0 + }, + { + "name": "Voice", + "direction": "downstream", + "flow-id": 3, + "rx-first-seq": 37, + "rx-last-seq": 5458, + "rx-tos-tc": 128, + "rx-outer-vlan-pbit": 0, + "rx-inner-vlan-pbit": 0, + "rx-len": 1026, + "tx-len": 1014, + "rx-packets": 5422, + "tx-packets": 5458, + "rx-loss": 0, + "rx-delay-nsec-min": 41700, + "rx-delay-nsec-max": 96548542, + "rx-pps": 100, + "tx-pps": 100, + "tx-bps-l2": 811200, + "rx-bps-l2": 820800, + "rx-bps-l3": 800000, + "tx-mbps-l2": 0.8112, + "rx-mbps-l2": 0.8208, + "rx-mbps-l3": 0.8 + } + ] + } + } + +The ``rx-outer-vlan-pbit`` might be wrong depending on network interface driver and +optional VLAN offloading. + +The measured ``rx-delay-nsec-min/max`` shows the minimum and maximum calculated delay +in nanosecond. The delay is calculated by subtracting the send and receive timestamp. +The send timestamp is stored in the BBL header (see section Traffic). This calculated +result depends also on the actual test environment, configured rx-interval and host IO +delay. + +Traffic streams will start as soon as the session is established using the rate as configured +starting with sequence number 1 for each flow. The attribute ``rx-first-seq`` stores the first +sequence number received. Assuming the first sequence number received for given flow is 1000 +combined with a rate of 1000 PPS would mean that it took around 1 second until forwarding is +working. After first packet is received for a given flow, for every further packet it checks +if there is a gap between last and new sequence number which is than reported as loss. + +The ``rx/tx-accounting-packets`` are all packets which should be counted in the session volume +accounting of the BNG, meaning session rx/tx packets excluding control traffic. + +Each flow can be queried separately using jsonpath expression with name and direction or flow-id. + +.. code-block:: none + + $ sudo bngblaster-cli run.sock session-streams session-id 1 | jq '."session-streams".streams[] | select(.name == "BE" and .direction == "downstream" )' + +.. code-block:: json + + { + "name": "BE", + "direction": "downstream", + "flow-id": 2, + "rx-first-seq": 33, + "rx-last-seq": 27040, + "rx-tos-tc": 213, + "rx-outer-vlan-pbit": 0, + "rx-inner-vlan-pbit": 0, + "rx-len": 126, + "tx-len": 114, + "rx-packets": 27008, + "tx-packets": 27040, + "rx-loss": 0, + "rx-delay-nsec-min": 50450, + "rx-delay-nsec-max": 10561572, + "rx-pps": 99, + "tx-pps": 99, + "tx-bps-l2": 90288, + "rx-bps-l2": 99792, + "rx-bps-l3": 79200, + "tx-mbps-l2": 0.090288, + "rx-mbps-l2": 0.099792, + "rx-mbps-l3": 0.0792 + } + +RAW Streams +~~~~~~~~~~~ + +Streams with default ``stream-group-id`` set to zero are considered as raw streams not +bound to any session which is supported in downstream only. For those streams the +destination address must be explicitly set. + +RAW streams can be used for traffic between two or network interfaces but also to send traffic +from network to access interfaces. + +.. code-block:: json + + { + "streams": [ + { + "name": "RAW", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "network-ipv4-address": "10.0.0.20", + "destination-ipv4-address": "1.1.1.1", + "length": 256, + "pps": 1 + } + ] + } + + +If ``destination-ipv4-address`` is set to a multicast IP address (224.0.0.0 - 239.255.255.255), +the BNG Blaster will set the the destination MAC address to the corresponding +multicast MAC address automatically. For unicast traffic the network gateway MAC address is used. + +Threaded Streams +~~~~~~~~~~~~~~~~ + +With threading enabled, those streams will be started per default in a dedicated thread per flow. +This means one thread per session and stream direction. A threaded, bidirectional stream assigned +to 10 sessions will therefore run in 20 threads. It is also possible to assign multiple +steams to a single thread using thread groups. + +In most environments we see between 200.000 and 300.000 PPS single threaded is working. Depending +on actual setup this can be also much more. With threaded streams we are also able to scale up to +10 million PPS depending on actual configuration and setup. This allows to start 1 million flows +with 1 PPS per flow over 4 threads in example to verify all prefixes of a BGP full table. + +The BNG Blaster is currently tested for up to 1 million flows which is not a hard limitation but +everything above should be considered as experimental. + +.. code-block:: json + + { + "streams": [ + { + "name": "RAW1", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "destination-ipv4-address": "10.0.0.1", + "length": 256, + "pps": 100000, + "network-interface": "eth1", + "threaded": true, + "thread-group": 1 + }, + { + "name": "RAW2", + "type": "ipv4", + "direction": "downstream", + "priority": 128, + "destination-ipv4-address": "10.0.0.1", + "length": 256, + "pps": 100000, + "network-interface": "etg1", + "threaded": true, + "thread-group": 2 + } + ] + } + +Start/Stop Session Stream Traffic +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Session stream traffic can be started/stopped dynamically +using the commands ``stream-traffic-enabled`` and ``stream-traffic-disabled``. + +``$ sudo bngblaster-cli run.sock stream-traffic-disabled session-id 1`` + +Those commands start/stop the traffic for all sessions if invoked without +session identifier. + +``$ sudo bngblaster-cli run.sock stream-traffic-disabled`` + +Alternatively all session and stream traffic (including RAW streams) +can be started or stopped globally using the ``traffic-start`` and +``traffic-stop`` commands. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 00000000..2979ad80 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,48 @@ +Troubleshooting +=============== + +Logging +------- + +The BNG Blaster is able to log events to the standard output +or logging window of the interactive courses interface. Those +events could be also logged to files using the argument +``-L ``. + +Per default only events classified as `info` or `error` are logged. +The following list shows all supported logging options. + +* ``debug``: debug events +* ``error``: error events +* ``igmp``: igmp events with join and leave time +* ``io``: interface input/output events +* ``pppoe``: pppoe events +* ``info``: informational events (enabled per default) +* ``pcap``: PCAP related events +* ``timer``: timer events +* ``timer-detail``: detailed timer events +* ``ip``: log learned IP addresses +* ``loss``: log traffic loss with sequence number +* ``l2tp``: log L2TP (LNS) events +* ``dhcp``: log DHCP events +* ``isis``: log ISIS events +* ``bgp``: log BGP events +* ``tcp``: log TCP events + +.. code-block:: none + + $ sudo bngblaster -C test.json -L test.log -l ip -l isis -l bgp + + +PCAP +---- + +You can start the BNG Blaster with the argument ``-P `` +to capture all traffic send and received by the BNG Blaster +into a single PCAP file. This file includes all traffic from all +interfaces in use with proper meta header to filter by interface +names. + +This helps to verify if traffic is received or how it has received. +Some network interfaces drop the most outer VLAN which can be easily +verified using the capture file. \ No newline at end of file diff --git a/docs/streams.md b/docs/streams.md deleted file mode 100644 index 1fb1c992..00000000 --- a/docs/streams.md +++ /dev/null @@ -1,368 +0,0 @@ -# Traffic Streams - -Traffic streams allow to do various forwarding verification -and QoS tests using BNG Blaster. - -![BBL Interactive Streams](images/bbl_streams.png "BNG Blaster") - -## Configuration - -Following a simple example using streams as described in the -[configuration section](config). - -```json -{ - "interfaces": { - "tx-interval": 0.1, - "rx-interval": 0.1, - "io-slots": 2048, - "network": { - "interface": "eth2", - "address": "10.0.0.1", - "gateway": "10.0.0.2", - "address-ipv6": "fc66:1337:7331::1", - "gateway-ipv6": "fc66:1337:7331::2" - }, - "access": [ - { - "interface": "eth1", - "outer-vlan-min": 1000, - "outer-vlan-max": 1000, - "inner-vlan-min": 7, - "inner-vlan-max": 7, - "stream-group-id": 1 - }, - { - "interface": "eth1", - "outer-vlan-min": 1001, - "outer-vlan-max": 4000, - "inner-vlan-min": 7, - "inner-vlan-max": 7, - "stream-group-id": 2 - } - ] - }, - "sessions": { - "count": 100 - }, - "pppoe": { - "host-uniq": true, - "vlan-priority": 6 - }, - "ppp": { - "mru": 1492, - "authentication": { - "username": "user{session-global}@rtbrick.com", - "password": "test", - "timeout": 5, - "retry": 30 - }, - "ipcp": { - "enable": true - }, - "ip6cp": { - "enable": true - } - }, - "dhcpv6": { - "enable": true, - "rapid-commit": true - }, - "access-line": { - "agent-remote-id": "DEU.RTBRICK.{session-global}", - "agent-circuit-id": "0.0.0.0/0.0.0.0 eth 0:{session-global}", - "rate-up": 1024, - "rate-down": 16384, - "dsl-type": 5 - }, - "streams": [ - { - "name": "BestEffort", - "stream-group-id": 1, - "type": "ipv4", - "direction": "both", - "length": 1000, - "pps": 1000 - }, - { - "name": "Voice", - "stream-group-id": 1, - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "vlan-priority": 2, - "network-ipv4-address": "10.0.0.10", - "length": 1000, - "pps": 100 - }, - { - "name": "BestEffort", - "stream-group-id": 2, - "type": "ipv4", - "direction": "both", - "length": 1000, - "pps": 1 - } - ] -} -``` - -## Stream Configuration File - -The command line argument `-T ` allows to include -streams defined from a separate file. The format is equal to -streams defined in the actual configuration file. Such stream -configuration files could be generated by scripts and -easily merged with the base configuration. - -```json -{ - "streams": [] -} -``` - -## Check Session Stream Information - -The `session-streams` command returns detailed stream statistics per session. - -`$ sudo bngblaster-cli run.sock session-streams session-id 1` - -```json -{ - "status": "ok", - "code": 200, - "session-streams": { - "session-id": 1, - "rx-packets": 59670, - "tx-packets": 54610, - "rx-accounting-packets": 59655, - "tx-accounting-packets": 54594, - "rx-pps": 1100, - "tx-pps": 1000, - "rx-bps-l2": 9028800, - "tx-bps-l2": 8240000, - "rx-mbps-l2": 9.0288, - "tx-mbps-l2": 8.24, - "streams": [ - { - "name": "BestEffort", - "direction": "upstream", - "flow-id": 1, - "rx-first-seq": 362, - "rx-last-seq": 54593, - "rx-tos-tc": 0, - "rx-outer-vlan-pbit": 0, - "rx-inner-vlan-pbit": 0, - "rx-len": 1014, - "tx-len": 1030, - "rx-packets": 54232, - "tx-packets": 54594, - "rx-loss": 0, - "rx-delay-nsec-min": 37650, - "rx-delay-nsec-max": 98595049, - "rx-pps": 1000, - "tx-pps": 1000, - "tx-bps-l2": 8240000, - "rx-bps-l2": 8112000, - "rx-bps-l3": 8000000, - "tx-mbps-l2": 8.24, - "rx-mbps-l2": 8.112, - "rx-mbps-l3": 8.0 - }, - { - "name": "BestEffort", - "direction": "downstream", - "flow-id": 2, - "rx-first-seq": 362, - "rx-last-seq": 54593, - "rx-tos-tc": 0, - "rx-outer-vlan-pbit": 0, - "rx-inner-vlan-pbit": 0, - "rx-len": 1026, - "tx-len": 1014, - "rx-packets": 54232, - "tx-packets": 54594, - "rx-loss": 0, - "rx-delay-nsec-min": 43550, - "rx-delay-nsec-max": 98903960, - "rx-pps": 1000, - "tx-pps": 1000, - "tx-bps-l2": 8112000, - "rx-bps-l2": 8208000, - "rx-bps-l3": 8000000, - "tx-mbps-l2": 8.112, - "rx-mbps-l2": 8.208, - "rx-mbps-l3": 8.0 - }, - { - "name": "Voice", - "direction": "downstream", - "flow-id": 3, - "rx-first-seq": 37, - "rx-last-seq": 5458, - "rx-tos-tc": 128, - "rx-outer-vlan-pbit": 0, - "rx-inner-vlan-pbit": 0, - "rx-len": 1026, - "tx-len": 1014, - "rx-packets": 5422, - "tx-packets": 5458, - "rx-loss": 0, - "rx-delay-nsec-min": 41700, - "rx-delay-nsec-max": 96548542, - "rx-pps": 100, - "tx-pps": 100, - "tx-bps-l2": 811200, - "rx-bps-l2": 820800, - "rx-bps-l3": 800000, - "tx-mbps-l2": 0.8112, - "rx-mbps-l2": 0.8208, - "rx-mbps-l3": 0.8 - } - ] - } -} -``` - -The `rx-outer-vlan-pbit` might be wrong depending on network interface driver and -optional VLAN offloading. - -The measured `rx-delay-nsec-min/max` shows the minimum and maximum calculated delay -in nanosecond. The delay is calculated by subtracting the send and receive timestamp. -The send timestamp is stored in the BBL header (see section Traffic). This calculated -result depends also on the actual test environment, configured rx-interval and host IO -delay. - -Traffic streams will start as soon as the session is established using the rate as configured -starting with sequence number 1 for each flow. The attribute `rx-first-seq` stores the first -sequence number received. Assuming the first sequence number received for given flow is 1000 -combined with a rate of 1000 PPS would mean that it took around 1 second until forwarding is -working. After first packet is received for a given flow, for every further packet it checks -if there is a gap between last and new sequence number which is than reported as loss. - -The `rx/tx-accounting-packets` are all packets which should be counted in the session volume -accounting of the BNG, meaning session rx/tx packets excluding control traffic. - -Each flow can be queried separately using jsonpath expression with name and direction or flow-id. - -`$ sudo bngblaster-cli run.sock session-streams session-id 1 | jq '."session-streams".streams[] | select(.name == "BE" and .direction == "downstream" )'` - -```json -{ - "name": "BE", - "direction": "downstream", - "flow-id": 2, - "rx-first-seq": 33, - "rx-last-seq": 27040, - "rx-tos-tc": 213, - "rx-outer-vlan-pbit": 0, - "rx-inner-vlan-pbit": 0, - "rx-len": 126, - "tx-len": 114, - "rx-packets": 27008, - "tx-packets": 27040, - "rx-loss": 0, - "rx-delay-nsec-min": 50450, - "rx-delay-nsec-max": 10561572, - "rx-pps": 99, - "tx-pps": 99, - "tx-bps-l2": 90288, - "rx-bps-l2": 99792, - "rx-bps-l3": 79200, - "tx-mbps-l2": 0.090288, - "rx-mbps-l2": 0.099792, - "rx-mbps-l3": 0.0792 -} -``` - -## RAW Streams - -Streams with default `stream-group-id` set to zero are considered as raw streams not -bound to any session which is supported in downstream only. For those streams the -destination address must be explicitly set. - -RAW streams can be used for traffic between two or network interfaces but also to send traffic -from network to access interfaces. - -```json -{ - "streams": [ - { - "name": "RAW", - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "network-ipv4-address": "10.0.0.20", - "destination-ipv4-address": "1.1.1.1", - "length": 256, - "pps": 1 - } - ] -} -``` - -If `destination-ipv4-address` is set to a multicast IP address (224.0.0.0 - 239.255.255.255), -the BNG Blaster will set the the destination MAC address to the corresponding -multicast MAC address automatically. For unicast traffic the network gateway MAC address is used. - -## Threaded Streams - -With threading enabled, those streams will be started per default in a dedicated thread per flow. -This means one thread per session and stream direction. A threaded, bidirectional stream assigned -to 10 sessions will therefore run in 20 threads. It is also possible to assign multiple -steams to a single thread using thread groups. - -In most environments we see between 200.000 and 300.000 PPS single threaded is working. Depending -on actual setup this can be also much more. With threaded streams we are also able to scale up to -10 million PPS depending on actual configuration and setup. This allows to start 1 million flows -with 1 PPS per flow over 4 threads in example to verify all prefixes of a BGP full table. - -The BNG Blaster is currently tested for up to 1 million flows which is not a hard limitation but -everything above should be considered as experimental. - -```json -{ - "streams": [ - { - "name": "RAW1", - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "destination-ipv4-address": "10.0.0.1", - "length": 256, - "pps": 100000, - "network-interface": "eth1", - "threaded": true, - "thread-group": 1 - }, - { - "name": "RAW2", - "type": "ipv4", - "direction": "downstream", - "priority": 128, - "destination-ipv4-address": "10.0.0.1", - "length": 256, - "pps": 100000, - "network-interface": "etg1", - "threaded": true, - "thread-group": 2 - } - ] -} -``` - -## Start/Stop Session Stream Traffic - -Session stream traffic can be started/stopped dynamically -using the commands `stream-traffic-enabled` and `stream-traffic-disabled`. - -`$ sudo bngblaster-cli run.sock stream-traffic-disabled session-id 1` - -Those commands start/stop the traffic for all sessions if invoked without -session identifier. - -`$ sudo bngblaster-cli run.sock stream-traffic-disabled` - -Alternatively all session and stream traffic (including RAW streams) -can be started or stopped globally using the `traffic-start` and -`traffic-stop` commands. diff --git a/docs/traffic.md b/docs/traffic.md deleted file mode 100644 index cd47a3b7..00000000 --- a/docs/traffic.md +++ /dev/null @@ -1,122 +0,0 @@ -# Traffic - -The BNG Blaster is able to emulate bidirectional unicast -session traffic for all addresses assigned to a session -(IPv4, IPv6 and IPv6PD). - -![BNG Blaster Session Traffic](images/bbl_session_traffic.png) - -There is also support to generate IPv4 multicast traffic. - -## Blaster Header and Fast Decode Signature - -The 48 Byte fixed size BNG Blaster Header is added to all data packets -for traffic validation and fast decoding. The header is expected on the -last 48 bytes of the packet. - -The type is set to 1 for all unicast session traffic and 2 for -IPv4 multicast traffic. - -### Unicast Session Traffic - -The 64 bit session key is used for all traffic from access (upstream) -and to access (downstream) interfaces to identify the corresponding -session which has send or should receive the packet. - -```text - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BNG Blaster Magic Sequence | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Type | Sub-Type | Direction | TX TOS | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Session Identifier | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Session Access Interface Index | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Session Outer VLAN | Session Inner VLAN | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Flow Identifier | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Flow Sequence Number | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Nanosecond Send Timestamp | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - -![BNG Blaster Header](images/bbl_header.png) - -### Multicast Traffic - -```text - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BNG Blaster Magic Sequence | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Type | Sub-Type | Direction | TX TOS | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Reserved | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Group | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Flow Identifier | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Flow Sequence Number | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Nanosecond Send Timestamp | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - -NOTE: All attributes except IP addresses in the Blaster Header are -stored in host byte order for faster processing -(LE or BE depending on test system). - -### BNG Blaster Magic Sequence - -The 64 bit magic sequence is the word `RtBrick!` decoded as ASCII: - -```text -0x5274427269636b21 -``` - -The magic number allows to check for it on a given offset and process -only blaster header instead of decoding the whole packet for faster -packet processing. - -### Flow Identifier - -The 64 bit flow identifier is a global unique number which identifies -the flow. - -### Flow Sequence Number - -The 64 bit flow sequence number is sequential number starting with 1 -and incremented per packet primary used to identity packet loss. - -This number 0 means that sequencing is disabled. - -### Nanosecond Send Timestamps - -The 64 bit nanoseconds send timestamp is used for optional latency and -jitter calculations. - -```text - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Seconds | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Nano Seconds | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - -The timestamp 0 means that timestamps are disabled.