Built-in Traffic Generator on Cisco 8000 Series Routers

What Is the Built-in Traffic Generator?

The Cisco 8000 series routers running IOS XR include a built-in packet generator that allows operators to generate traffic directly from the router itself — no external traffic generator hardware or software required.

This diagnostic tool lets you:

• Inject crafted packets into the router’s data plane for troubleshooting and network diagnostics.
• Create packets up to 4K bytes (A100/K100 NPUs based systems)
• Run multiple traffic generator sessions simultaneously, each identified by a unique session name.
• Number of simultenous sessions and max throughput per session depends on packet size/pps/interface speed
• Inject packets in the ingress, egress, or both directions at the same time.
• Define packet contents either inline on the command line or from a pcap file.

The packet definitions use a Scapy-like syntax, giving you full control over Layer 3/4 headers including IPv4/IPv6 addresses, TTL, DSCP/TOS, and payload.

---

When to Use the Built-in Traffic Generator

The built-in traffic generator is ideal in scenarios where you need to quickly validate or troubleshoot network behavior without relying on external test equipment:

Scenario	How the Traffic Generator Helps
Link or interface validation	Verify that a newly provisioned link is forwarding traffic correctly end-to-end.
Routing verification	Confirm that packets destined for a specific prefix follow the expected path.
QoS and DSCP testing	Inject packets with specific DSCP/TOS values to validate classification, queuing, and scheduling policies.
Troubleshooting packet drops	Generate a controlled stream of traffic and observe counters to isolate where drops occur.
Lab and staging environments	Simulate traffic during pre-deployment testing of a service without dedicated traffic generators

---

When NOT to Use the Built-in Traffic Generator

While the built-in packet generator is a valuable tool for debugging and troubleshooting, it is important to set the right expectations. It is not a replacement for a third-party traffic generator. Keep the following limitations in mind:

• Not for stress testing or benchmarking — The built-in generator shares ASIC resources with production forwarding. It should not be used to stress-test a service, a line card, or the system as a whole. Results under synthetic internal load do not reflect real-world forwarding capacity.
• Not a throughput validation tool — Standards-based service validation tests such as ITU-T Y.1564 (Ethernet service activation) require precise, calibrated, bidirectional traffic streams with strict measurement of throughput, latency, jitter, and frame loss. The built-in generator does not meet those requirements and should never be substituted for a certified test instrument.
• Not for production traffic simulation — The generator produces simple, uniform packet streams. It cannot replicate realistic traffic mixes (varying packet sizes, application protocols, burst patterns) that a dedicated traffic generator or network emulator can produce.
• Not for long-running load tests — Running high-rate generator sessions for extended periods consumes forwarding resources and may impact production traffic on the same ASIC pipeline. Use it for short, targeted diagnostic sessions.

Bottom line: Use the built-in traffic generator for on-box diagnostics and troubleshooting. For anything that requires accurate performance measurement, service-level compliance, or sustained load, use a proper external traffic generator.

---

How It Works

The built-in traffic generator is implemented within the NPU Host (NPUH) block of the Silicon One ASIC. It leverages the NPUH to inject user-defined packets directly into the forwarding pipeline — either at ingress or egress — without requiring any external device.

Because the NPUH block is shared with other ASIC applications (such as BFD, PFC, CFM etc), and the traffic generator must share internal resources like packet data memory. Each traffic generator session allocates memory in fixed 16-byte chunks, and packet data blocks cannot be partially allocated. This means that the actual resource consumption per session depends on the packet size, the configured stream rate, and the number of concurrent sessions.

As a result, the maximum number of flows and achievable bandwidth are governed by the interplay of packet size, per-stream rate, port speed, and the internal resources available to the generator at any given time. Higher stream rates consume more resources, leaving room for fewer simultaneous flows. The generator supports a maximum bandwidth of up to 50 Gbps and a maximum packet size of 4K bytes. For maximum flow counts we support up to 256 flows on 8712 (K100) and 160 flows on 8011(A100) (at low PPS per-flow).

---

How to Use the Built-in Traffic Generator

The workflow follows four steps: Create a session, Start it, Verify the status, and Stop/Delete when done.

Step 1: Create a Traffic Generator Session

Use the diagnostic packet-generator create command to define a session. You specify:

• Session name — a unique identifier (e.g., t6)
• Rate — packets per second
• Duration — infinite or a fixed duration
• Packet definition — Using scapy library for packet construction
• Direction — ingress or egress
• Interface — the interface where packets are injected
• Location — the RP/LC node

Basic IPv4 example:

diagnostic packet-generator create t6 rate 10000 duration infinite packet IP(src="20.4.1.10",dst="20.5.1.10",ttl=64)/UDP()/Raw(load="a"*100) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0

This creates a session named t6 that sends 10,000 IPv4/UDP packets per second with a 100-byte payload through TwentyFiveGigE0/0/0/4 in the ingress direction.

Step 2: Start the Session

diagnostic packet-generator start t6 location all

Step 3: Verify the Session

show diagnostic packet-generator status t6 location 0/RP0/CPU0

When the session is healthy, look for these indicators:

Field	Expected Value
Run_State	running
Applied rate	Matches/Close to your configured rate
Duration	infinite (or configured value)
Packets / Bytes counters	Incrementing over time

To check all active sessions at once:

show diagnostic packet-generator status all location 0/RP0/CPU0

In case of Ingress injection and packet getting dropped due to forwarding mismatch/no route etc. The packet/byte counters will not increment.

Step 4: Stop and Clean Up

! Stop a running session
diagnostic packet-generator stop t6 location all
! Delete the session entirely
diagnostic packet-generator delete t6 location all

---

Default MAC Addresses and Forwarding Requirements

Default Source and Destination MAC Addresses

The built-in traffic generator automatically assigns default MAC addresses to injected packets based on the injection direction:

Direction	Source MAC	Destination MAC
Ingress	00:00:00:00:00:01 (generic host MAC)	Interface MAC of the ingress port
Egress	Must be defined	Must be Defined

For ingress-injected sessions, the packet is crafted as if it arrived from an external host — the destination MAC is set to the router’s own interface MAC so the packet is accepted and forwarded through the normal pipeline.

For egress-injected sessions, the packet is placed directly into the egress path, and for proper functioning of generated traffic the Ether header must be defined.

Note: If your test scenario requires specific MAC addresses (e.g., to match an ACL or policy), you can override the defaults by including an Ether header in the packet definition:

packet Ether(src="aa:bb:cc:dd:ee:01",dst="aa:bb:cc:dd:ee:02")/IP(...)/UDP()/Raw(...)

Automatic VLAN Tagging for Sub-interfaces

When traffic is injected on a L3 sub-interface as the ingress interface, the packet generator automatically adds the required VLAN header (802.1Q tag) to the packet based on the sub-interface’s VLAN configuration. You do not need to manually include a Dot1Q layer in the packet definition — the generator handles it for you.

Note: Sub-interface as the egress interface is not supported as egress injected traffic is always placed on the wire. To Match such scenario, always use defined Ethernet Header with VLAN Tag.

Forwarding Table Requirement

Ingress Inject Traffic on L3 interface:
For the generated traffic to be forwarded correctly, the router’s forwarding table (FIB) must have a valid entry for the destination address in the packet. If there is no matching route for the packet’s destination IP, the packet will be dropped.

Before starting a traffic generator session, verify that the destination prefix is reachable:

show route <destination-ip>
show cef <destination-ip>

This applies to both IPv4 and IPv6 packets. Without a corresponding FIB entry, the generated packets may not egress or get forwarded as expected — regardless of the configured rate or session state.

Ingress Inject Traffic on L2 interface:
For ingress TGEN in a layer2 setup, auto fill of the the ethernet header is not supported, which is for L3 only. User needs to specify the Ether header and associated VLAN headers to inject traffic towards an Layer 2 interface.

Example

 Ether(src="1:2:3:1:2:3",dst="1:2:3:a:b:c")/Dot1Q(vlan=2)/IP(src="10.1.1.1",dst="20.1.1.1",ttl=64,tos=184)/UDP()

Example Scenarios

Example 1: Basic IPv4 Traffic Between Two Routers

Topology:

Create and start a packet stream from R2 to simulate traffic from R1 toward R3:

! Create the session
diagnostic packet-generator create t6 duration 600 rate 1000 packet IP(src="20.4.1.10",dst="20.5.1.10",ttl=64)/UDP()/Raw(load="a"*200) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0
! Start the session
diagnostic packet-generator start t6 location all
! Verify packets are flowing
show diagnostic packet-generator status t6 location 0/RP0/CPU0

Confirm that Run_State shows running and packet/byte counters are incrementing as shown below:

RP/0/RP0/CPU0:N1#show diagnostic packet-generator status t6 location 0/RP0/CPU0
Thu May 14 13:35:40.463 IST
0/RP0/CPU0:
Name Run_State Type Capture Set_Rate(pps) Applied_Rate(pps) Duration(sec) TC Phy_Interface NPU Slice IFG Packets Bytes 
================================================================================================================================================================
T6 Running Ingress False 1000 998 600 0 TF0/0/0/4 0 0 0 12562 3529922 
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Packet Details: 
###[ Ethernet]### 
 dst = f4:33:92:91:57:15
 src = 00:00:00:00:00:01
 type = IPv4
###[ IP]### 
 version = 4
 ihl = 5
 tos = 0x0
 len = 228
 id = 1
 flags = 
 frag = 0
 ttl = 64
 proto = udp
 chksum = 0x4fec
 src = 20.4.1.10
 dst = 20.5.1.10
 \options \
!! Output truncated for brevity

Example 2: IPv4 Packet with DSCP Marking

To test QoS policies, inject packets with a specific DSCP value. The DSCP value is encoded in the tos field of the IP header. For example, DSCP EF (46) maps to TOS value 184 (46 << 2 = 184).

diagnostic packet-generator create t8 duration 600 rate 1000 packet IP(src="20.4.1.10",dst="20.5.1.10",tos=184,ttl=64)/UDP()/Raw(load="a"*200) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0

---

Example 3: IPv6 Packet with Traffic Class (DSCP)

For IPv6, the DSCP is carried in the Traffic Class (tc) field. The same EF (46) DSCP maps to tc=184.

diagnostic packet-generator create t1 rate 10000 duration infinte packet IPv6(src="2001:db8:1::2",dst="2001:db8:2::2",tc=184,hlim=16)/UDP()/Raw(load="f"*900) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0

---

Example 4: Running Multiple Sessions Simultaneously

You can run multiple sessions at the same time, each with different parameters. In this example, two IPv4 streams are created with different IP Precedence values (4 and 5):

! Session 1: IPv4 with Precedence 4 (TOS=128) for 10 minutes
diagnostic packet-generator create t1 rate 10000 duration 600 packet IP(src="20.4.1.10",dst="20.5.1.10",tos=128,ttl=64)/UDP()/Raw(load="f"*900) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0
! Session 2: IPv4 with Precedence 5 (TOS=160) for 15 minutes
diagnostic packet-generator create t2 rate 10000 duration 900 packet IP(src="20.4.1.10",dst="20.5.1.10",tos=160,ttl=64)/UDP()/Raw(load="f"*900) ingress interface TwentyFiveGigE0/0/0/4 location 0/RP0/CPU0
! Start both
diagnostic packet-generator start t1 location all
diagnostic packet-generator start t2 location all
! you can Also use 
diagnostic packet-generator start all location all
! Verify all sessions
show diagnostic packet-generator status all location 0/RP0/CPU0

RP/0/RP0/CPU0:N1#show diagnostic packet-generator status all location all 
Thu May 14 13:57:29.497 IST
0/RP0/CPU0:
Name Run_State Type Capture Set_Rate(pps) Applied_Rate(pps) Duration(sec) TC Phy_Interface NPU Slice IFG Packets Bytes 
================================================================================================================================================================
T1 Running Ingress False 10000 10000 600 0 TF0/0/0/4 0 0 0 352815 346111515 
T2 Running Ingress False 10000 10000 900 0 TF0/0/0/4 0 0 0 352804 346100724 
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Total packet generators: 2

---

Quick Reference: Session Management Commands

Action	Command
Create a session	diagnostic packet-generator create <name> rate <pps> duration <seconds|infinite> packet <definition> ingress|egress interface <intf> location <node>
Start a session	diagnostic packet-generator start <name> location all
Verify a session	show diagnostic packet-generator status <name|all> location <node>
Stop a session	diagnostic packet-generator stop <name> location <node>|all
Delete a session	diagnostic packet-generator delete <name> location <node>|all

---

Key Constraints and Limits

• Maximum rate: depends on the port speed but low-rate flows are recommended. More pps takes more memory resources.
• Maximum Bandwidth: Depends on the port speed, stream rate and internal memory resources. Maximum BW tested is 50G with 8 simultaneous sessions.
• Maximum packet size: 4K bytes
• Maximum number of flows: Depends on pps, packet size and internal memory resources. On 8712, with low pps and consistent packet size, we have tested upto 256 flows. On 8011, we have tested upto 160 flows.
• Packet syntax: Scapy-style — IP(), IPv6(), UDP(), TCP(), Raw()
• No capture capability support

Below table captures some scale we characterized in our lab with packet headers including auto generated headers not exceeding 62 bytes and payload filled with the same byte:

---

Additional Resources

• Cisco 8000 Traffic Generator Command Reference — official IOS XR command reference for diagnostic packet-generator.