Merge branch 'dev' into main

CMakeLists.txt

@@ -30,6 +30,9 @@ find_library(libdict NAMES libdict.a REQUIRED)
 
 target_link_libraries(bngblaster curses crypto jansson ${libdict} m)
 
+SET(PLATFORM_SPECIFIC_LIBS "-lpthread")
+SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -pthread")
+
 # add experimental netmap support
 if(BNGBLASTER_NETMAP)
     add_definitions(-DBNGBLASTER_NETMAP)

docs/README.md

@@ -8,4 +8,5 @@
 - [Control Socket](ctrl.md)
 - [Multicast](multicast.md)
 - [L2TPv2](l2tp.md)
-- [Legal Interception](li.md)
+- [Legal Interception](li.md)
+- [Traffic Streams](streams.md)

docs/config.md

@@ -90,20 +90,54 @@ Following an example configuration file which is explained in detail below.
 
 ## Interfaces
 
-This section describes all attributes of the `interfaces` hierarchy. 
+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
-`rx-interval` | RX ring polling interval in milliseconds | 5
+`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
+`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
 
-WARNING: Try to disable `qdisc-bypass` if BNG Blaster is not sending traffic!
-This issue was frequently seen on Ubuntu 20.04. 
+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` all other modes are currently considered as experimental. 
+`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 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.
+
+```
+sudo ip link set dev <interface> 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.
+
+```
+sudo ip link set mtu 9000 dev <interface>
+```
 
 ### Network Interface
 
@@ -118,7 +152,6 @@ Attribute | Description | Default
 `gateway-ipv6` | Gateway network interface IPv6 address (implicitly /64)
 `vlan` | Network interface VLAN | 0 (untagged)
 
-
 ### Access Interfaces
 
 `"interfaces": { "access": { ... } }`
@@ -151,11 +184,11 @@ Attribute | Description | Default
 `ipv6` | Optionally enable/disable IPoE IPv4 per access configuration
 `dhcp` | Optionally enable/disable DHCP per access configuration
 `dhcpv6` | Optionally enable/disable DHCPv6 per access configuration
-
+`stream-group-id` | Optional stream group identifier
 
 **WARNING**: DHCP (IPv4) is currently not supported!
 
-But for all modes it is possible to configure between zero and three VLAN
+For all modes it is possible to configure between zero and three VLAN
 tags on the access interface as shown below.
 
 ```
@@ -420,12 +453,12 @@ Attribute | Description | Default
 
 This section describes all attributes of the `dhcp` hierarchy. 
 
-**WARNING**: DHCP (IPv4) is currently not supported!
-
 Attribute | Description | Default 
 --------- | ----------- | -------
 `enable` | This option allows to enable or disable DHCP | true
 
+**WARNING**: DHCP (IPv4) is currently not supported!
+
 ## DHCPv6
 
 This section describes all attributes of the `dhcpv6` hierarchy. 
@@ -529,4 +562,34 @@ 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. 
+received window size. 
+
+## Traffic Streams
+
+This section describes all attributes of the `streams` hierarchy. 
+
+Attribute | Description | Default 
+--------- | ----------- | -------
+`name` | Mandatory stream name |   
+`stream-group-id` | Mandatory stream group identifier | 
+`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 - 1500) | 128
+`pps` | Stream traffic rate in packets per second | 1
+`bps` | Stream traffic rate in bits per second (layer 3) | 
+`network-ipv4-address` | Overwrite network interface IPv4 address | 
+`network-ipv6-address` | Overwrite network interface IPv6 address | 
+`threaded` | Run those streams in separate threads | false
+
+For L2TP downstream traffic the IPv4 TOS is applied to the outer IPv4 and inner IPv4 header.
+
+The `pps` option has priority over `bps` where second is only a helper to calculate the `pps` 
+based on given `bps` and `length`. 
+
+With threading enabled, those streams will be started 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. 
+
+**WARNING**: The threading support is experimental and should be used with caution! 

docs/ctrl.md

@@ -125,6 +125,8 @@ Attribute | Description
 `session-traffic` | Display session traffic statistics | |
 `session-traffic-enabled` | Enable session traffic for all sessions
 `session-traffic-disabled` | Disable session traffic for all sessions
+`stream-traffic-enabled` | Enable stream traffic for all sessions | |
+`stream-traffic-disabled` | Disable stream traffic for all sessions | |
 `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
@@ -160,6 +162,9 @@ Attribute | Description | Mandatory Arguments | Optional Arguments
 `ip6cp-close` |Close IP6CP | |
 `session-traffic-enabled` | Enable session traffic | |
 `session-traffic-disabled` | Disable session traffic | |
+`session-streams` | Session traffic stream information | | 
+`stream-traffic-enabled` | Enable session stream traffic | |
+`stream-traffic-disabled` | Disable session stream traffic | |
 `igmp-join` | Join group | `group` | `source1`, `source2`, `source3`
 `igmp-leave` | Leave group | `group` |
 `igmp-info` | IGMP information | |

docs/index.md

@@ -9,6 +9,7 @@
 - [Multicast](multicast)
 - [L2TPv2](l2tp)
 - [Legal Interception](li)
+- [Traffic Streams](streams)
 
 A short introduction can be found on [YouTube](https://youtu.be/EHJ70p0_Sw0 "BNG Blaster").
 

docs/intro.md

@@ -9,13 +9,14 @@ targeted for max scaling with small resource footprint, simple to use and easy t
 our test automation infrastructure. 
 
 The BNG Blaster is able to simulate more than hundred thousand PPPoE subscribers including IPTV, 
-L2TPv2, traffic verification and convergence testing capabilities.
+L2TPv2, QoS, forwarding verification and convergence testing capabilities.
 
 * *High Scaling:* > 100K sessions
 * *Low CPU and Memory Footprint:* < 100MB 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
 
 ```
@@ -68,13 +69,17 @@ protocol session FSM timers quickly and at scale.
 BNG Blaster expects a Linux kernel interface which is up, but not configured with any IP addresses or VLAN as it expects to 
 receive and transmit raw ethernet packets.
 
-BNG Blaster does I/O using high-speed polling timers using the so-called PACKET_RX_RING/PACKET_TX_RING abstraction where a 
-userspace 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. 
+BNG Blaster does I/O using high-speed polling timers with a mix of raw sockets and so-called PACKET_RX_RING/PACKET_TX_RING 
+abstraction where a userspace 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. 
 
 ![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 sockets. 
+
 Sending and transmitting traffic is as easy as just by copying a packet into a buffer and setting a flag. This is super 
 efficient and hence we have measured the I/O performance of roughly 1M pps per single CPU thread, which is more than enough for 
 our purposes here.

docs/multicast.md

@@ -27,8 +27,8 @@ delay in milliseconds.
 ```json
 {
     "interfaces": {
-        "tx-interval": 1,
-        "rx-interval": 10,
+        "tx-interval": 1.0,
+        "rx-interval": 1.0,
         "network": {
             "interface": "eth2",
             "address": "100.0.0.10",
@@ -45,6 +45,9 @@ delay in milliseconds.
 }
 ```
 
+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. 
+
 ## Manual Join/Leave Testing
 
 It is possible to join and leave multicast groups manually using the <<Control Socket>> as