Traffic Mirroring Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Release

PDF

SPAN to file

Updated: February 5, 2026

Overview

This section explains the SPAN to file feature, which mirrors network traffic to files in PCAP format for offline analysis. It covers configuration options for buffer sizes and types, and provides a comprehensive history of feature support across various software releases and hardware platforms.

SPAN to file is a traffic monitoring feature that

  • captures traffic from a SPAN session and writes it directly to a file for later analysis

  • extends the existing SPAN feature by mirroring network packets to a file instead of an interface

  • helps in the analysis of the packets at a later stage, and

  • saves the file in the PCAP file format, which is compatible with tools like tcpdump and Wireshark.

The monitor-session <name> [ethernet|ipv4|ipv6|mpls-ipv4|mpls-ipv6] command creates a monitor-session with the specified name and traffic class, serving as a chain point from the SPAN feature.

The destination file [size <kbytes>] [buffer-type linear] command adds a file destination option to the session configuration.

destination file has these configuration options:

  • Buffer size: Sets the maximum file size for captured packets.

  • Buffer types:

    • Circular: This is the default buffer type. Once the buffer is full, it overwrites from the beginning.

    • Linear: Once the buffer is full, no further packets are logged. Only the linear buffer type must be explicitly configured.

Altering any parameters, such as buffer size or type, recreates the session and clears any packet buffers.

All configuration options available for other SPAN types should also be supported by SPAN to file. These include options such as applying ACLs and capturing only the first X bytes of each packet.

Starting with Cisco IOS XR Release 7.5.3, truncation is supported per global session rather than per interface. These options are implemented by the router when punting the packet.

Table 1. Feature History Table

Feature name

Release information

Feature description
SPAN-to-File with unique capture Release 25.2.1

Introduced in this release on: Fixed Systems (8200 [ASIC: Q200, P100], 8700 [ASIC: P100, K100], 8010 [ASIC: A100]); Centralized Systems (8600 [ASIC: Q200]); Modular Systems (8800 [LC ASIC: Q100, Q200, P100])

This feature enhances the SPAN-to-File functionality by allowing you to capture only a single, unique packet for each punt reason or interface. This prevents interesting packets from being overshadowed by repeated packets in the analysed flow, ensuring that diverse and relevant packets are retained for analysis.

The feature introduces these changes:

CLI:

The unique-punt and unique-port keywords are introduced in the drops command.

Always-On SPAN-to-File with periodic write

 Release 24.4.1

Introduced in this release on: Fixed Systems(8200, 8700); Centralized Systems (8600); Modular Systems (8800 [LC ASIC: Q100, Q200, P100]).

The routers can now provide reliable, always-available packet capture for post-event analysis, eliminating the need for prior configuration or user interaction.

The enhanced SPAN-to-File feature provides continuous packet capture and debugging capability with always-on functionality that starts automatically upon destination configuration. It prevents data loss during node reloads by periodically writing packet buffer contents to disk, without stopping the capture. A default SPAN-to-File session for forwarding and buffer drops is always active and can be disabled if not needed. The feature also supports packet truncation and sampling in software for software-mirrored packets, independent of NPU capabilities.

The feature introduces these changes:

CLI:

YANG data models:

  • New Xpaths for Cisco-IOS-XR-um-monitor-session-cfg.yang

  • New Xpaths for Cisco-IOS-XR-Ethernet-SPAN-cfg.yang

  • New Xpaths for Cisco-IOS-XR-Ethernet-SPAN-act.yang

(see GitHub, YANG Data Models Navigator)

SPAN-to-file in Tx direction

 Release 25.1.1

Introduced in this release on: Fixed Systems (8700 [ASIC: K100], 8010 [ASIC: A100])

This feature is now supported on:

  • 8712-MOD-M

  • 8011-4G24Y4H-I
SPAN-to-file in Tx direction Release 24.4.1

Introduced in this release on: Fixed Systems(8200, 8700)(select variants only*); Modular Systems (8800 [LC ASIC: P100])(select variants only*).

This feature now allows to capture packets in the Tx direction on the following hardware.

*This feature is now supported on:

  • 8212-48FH-M

  • 8711-32FH-M

  • 8712-MOD-M

  • 88-LC1-12TH24FH-E

  • 88-LC1-52Y8H-EM

  • 88-LC1-36EH

SPAN-to-file support in Tx and Rx direction

 Release 7.5.3

With this feature, the ability to capture the packet in Tx direction along with the ability to store the capture on the file is supported.

You can now capture the packet in the Tx direction and store the capture on the file. Earlier, you could only capture or mirror the traffic in the Rx direction. You now have the flexibility to choose Tx, Rx, or both directions.

You can now capture and analyze the outgoing (Tx) packets.

Partial packet capture ability for SPAN-to-file (Rx)

 Release 25.1.1

Introduced in this release on: Fixed Systems ( 8010 [ASIC: A100])

This feature is now supported on:

  • 8011-4G24Y4H-I
Partial packet capture ability for SPAN-to-file (Rx) Release 24.4.1

Introduced in this release on: Fixed Systems(8200, 8700)(select variants only*); Modular Systems (8800 [LC ASIC: P100])(select variants only*).

This feature now allows you to perform partial packet capture in the Rx direction on the following hardware.

*This feature is now supported on:

  • 8212-48FH-M

  • 8711-32FH-M

  • 8712-MOD-M

  • 88-LC1-12TH24FH-E

  • 88-LC1-52Y8H-EM

  • 88-LC1-36EH

Partial packet capture ability for SPAN-to-file (Rx)

 Release 7.5.3

With this feature, you can perform partial packet capture in the Rx direction.

Earlier, the ability for entire packet capture was available in the Tx direction only, now you can choose entire or partial packet capture in the Rx direction also.

Here, partial packet capture is also known as truncation.
SPAN-to-file PCAPng file format Release 24.4.1

Introduced in this release on: Fixed Systems(8200, 8700)(select variants only*); Modular Systems (8800 [LC ASIC: P100])(select variants only*).

This PCAPng File Format feature that contains different blocks used to rebuild the captured packets into recognizable data is now supported on the following hardware.

*This feature is now supported on:

  • 8212-48FH-M

  • 8711-32FH-M

  • 88-LC1-12TH24FH-E

  • 88-LC1-52Y8H-EM

  • 88-LC1-36EH

SPAN-to-file PCAPng file format

Release 7.3.1

PCAPng is the next generation of packet capture format that contains a dump of data packets captured over a network and stored in a standard format.

The PCAPng file contains different types of information blocks, such as the section header, interface description, enhanced packet, simple packet, name resolution, and interface statistics. These blocks can be used to rebuild the captured packets into recognizable data.

The PCAPng file format:

  • Provides the capability to enhance and extend the existing capabilities of data storage over time

  • Allows you to merge or append data to an existing file.

  • Enables to read data independently from network, hardware, and operating system of the machine that made the capture.


This table details the support for packet capture for various releases:

Before Release 7.5.3

After Release 7.5.3

There was no functionality that you could enable to capture the payload of packets coming from your customers for security reasons.

The capture of all the outgoing packets from the router is supported.

Configuration guidelines for SPAN to file

These guidelines apply to SPAN to file:

  • A maximum of 100 source ports are supported across the system. Individual platforms may support lower numbers.

  • All the SPAN sessions are configured under the Ethernet class.

  • At any given time, the system supports four SPAN to file sessions.

  • When you attach multiple interfaces to a monitor session, the minimum buffer size is 1KB. The maximum buffer size is 1000KB, and default buffer size is 2KB.

Restrictions for SPAN to file

These restrictions apply to SPAN to file:

  • Only incoming packet mirroring on the source interface is supported. Outgoing mirrored packets cannot be saved to a file. Starting with Cisco IOS XR Software Release 7.5.3, there are no restrictions.

  • You can apply SPAN ACLs only in ingress direction. Hence, ACLs for SPAN to file can only be applied in ingress direction.

  • ACL on MPLS traffic is not supported.

  • MPLS over GRE traffic is supported, however, GRE interfaces cannot be configured as source interfaces.

  • Packet truncation applies for SPAN to file and ERSPAN interfaces only. If you change the destination to local SPAN, then an ios_msg is displayed as a warning. The entire packet is mirrored after this message is displayed.

    ios_msg example: 
    The Partial Packet Capture feature is not supported by Local SPAN. The entire
Packet will be mirrored.

  • For outgoing (Tx) SPAN to file, security ACL is not supported.

  • For outgoing (Tx) SPAN to file, only transit traffic is mirrored.

  • Self-originating traffic cannot be mirrored.

Capabilities of SPAN to file

These are the supported capabilities of SPAN to file:

Traffic types and interface support

  • Mirror outgoing traffic and punt it to the CPU across all NPU versions.

  • Mirror outgoing IPv4, IPv6, and MPLS traffic to file.

  • Mirror outgoing traffic across all types of L3 interfaces, including physical, subinterfaces, bundle, and bundle sub-interfaces.

  • Mirror outgoing traffic across L2 or BVI interfaces.

Direction and mirroring control

Enable SPAN to File truncation configuration for both RX and TX directions. You can specify the both keyword to enable RX and TX mirroring on a single source interface.

Truncation configuration

  • Configure a different truncation size on each monitor session.

  • Configure SPAN to file mirroring packet truncation size from 1 to 10,000 bytes. Values outside this range are rejected with an error.

  • Change the truncation size when packet collection has stopped; removing or re-adding the monitor session is not required.

  • Change the truncation size during packet collection without stopping the monitor session.

  • Mirror the entire packet by default if no truncation size is configured. If the packet size is smaller than the truncation size, the entire packet is mirrored.

How SPAN to file works

Summary

SPAN to file works by capturing traffic from a SPAN session and saving the data to a file for later analysis.

Workflow

These stages describe how SPAN to file works when you configure a single file as a destination for a SPAN session:

  • The system creates a buffer on each node, where the network packets are logged.

  • The system creates buffer for all packets on the node regardless of which interface they are from. That is, multiple interfaces can provide packets to the same buffer.

  • The system deletes the buffer when the session configuration is removed.

  • Each node writes a file on the active RP, which contains the node ID of the node on which the buffer was located.

These stages describe how SPAN to file works when you attach multiple interfaces to a monitor session:

  • Multiple interfaces are attached to a session.

  • The system sends the packets to the interfaces on the same node.

  • The packets are saved to the same file. Bundle interfaces can be attached to a session with a file destination, which is similar to attaching individual interfaces.

Action commands for SPAN to file

Action commands for SPAN to file are capabilities that:

  • allow you to start and stop network packet collection

  • write the contents of a packet buffer to disk without stopping the packet capture for all the sessions with active packet collection

  • run on sessions where the destination is a file, and

  • autocomplete names of the globally configured SPAN to file sessions.

This table details the action commands for SPAN to file:

Table 1. Action commands for SPAN to file

Action

Command

Description

Start

monitor-session <name> packet-collection start

Use this command to start writing packets for the specified session to the configured buffer. This command has no effect for sessions configured as always-on.

Stop

monitor-session <name> packet-collection stop [ discard-data | write directory <dir> filename <filename> ]

Use this command to stop writing packets to the configured buffer. If you specify the discard-data option, the system clears the buffer. If you specify the write option, the system writes the buffer to disk before clearing it.

When writing the buffer to disk, save the file in .pcap format at the following location: /<directory>/<node_id>/<filename>. If you include a .pcap extension when specifying the filename, the system will remove it to prevent the extension from being added twice.

This command returns an error for sessions configured as always-on.

Write

monitor-session <name> packet-collection write [directory <dir>] [filename <filename>]

Use this command to write the contents of a packet buffer to disk without stopping the packet capture. The write command is available only for sessions with active packet collection. You can start the packet collection explicitly with the action command or through always-on collection.

You may specify the full directory path and file name where the buffer needs to be written. If you specify the directory, it must already exist. If the directory or file name are not specified, the following default values are used:

Directory: /misc/scratch/SPAN/<node>/

Filename: <session_name>_<node>_<timestamp>.pcap

Configure SPAN to file

Use these steps to configure SPAN to file:

Procedure

1.

Create a monitor session.

Example:

interface GigabitEthernet 0/0/0/0
monitor-session mon1 [ethernet|ipv4|ipv6|mpls-ipv4|mpls-ipv6]
2.

Configure a mon1 monitor session.

Example:

monitor-session mon1 ethernet
destination file size 230000
!

In this example, omitting the buffer-type option results in default circular buffer.
3.

Configure a mon2 monitor session.

Example:

monitor-session mon2 ethernet
destination file size 1000 buffer-type linear
!
4.

Attach monitor session to a physical or bundle interface.

Example:

Router#show run interface Bundle-Ether 1
Fri Apr 24 12:12:59.348 EDT
interface Bundle-Ether1
monitor-session ms7 ethernet|ipv4|ipv6|mpls-ipv4|mpls-ipv6]
[direction {rx-only|tx-only|both[SW(1] }] [port-level]
acl [<acl_name>]!
5.

Verify the packet collection status.

Example:

Router#show monitor-session status
Monitor-session mon1
Destination File - Packet collecting
=============================================
Source Interface Dir. Status
--------------------- ---- ------------------
Hu0/9/0/2 Rx Operational
Monitor-session mon2
Destination File - Packet collecting
=========================================
Source Interface Dir Status
--------------------- ---- --------------
BE2.1. Rx Operational

If packet collection is not active, this line is displayed:

Monitor-session mon2
Destination File - Not collecting

Configure SPAN to file for truncation

Follow these steps to configure SPAN to file for truncation.

Procedure

1.

Create a SPAN to file monitor session for mirroring the packets with truncation enabled. Use the mirror first command in monitor session configuration.

Example:

monitor-session <name> [ethernet]
destination file [size <kbytes>] [buffer-type linear|circular]
mirror first <number>
2.

Attach the interfaces to the monitor session.

Example:

interface <>
  monitor-session session-name ethernet direction rx-only|tx-only|both | acl [acl_name]
3.

Verify the configuration.

Example:

Router#show monitor-session status
                   Monitor-session mon1
                   Destination File - Packet collecting
                   =============================================
                   Source Interface      Dir   Status
                   --------------------- ----  ------------------
                   Hu0/9/0/2             Rx    Operational
                   Monitor-session mon2
                   Destination File - Packet collecting
                   =========================================
                   Source Interface      Dir   Status
                   --------------------- ----  --------------
                   BE1                  Tx    Operational
                   Monitor-session mon3
                   Destination File - Packet collecting
                   =========================================
                   Source Interface      Dir   Status
                   --------------------- ----  --------------
                   BE2.1                 Both    Operational

Configure SPAN to file for direction

Follow these steps to configure SPAN to file for truncation.

Procedure

1.

Create a SPAN to file monitor session.

Example:

monitor-session mon2 ethernet
 destination file
!
2.

Attach the interfaces to the monitor session.

Example:

interface <>
  monitor-session session-name ethernet direction rx-only|tx-only|
acl [acl_name]
3.

Verify the configuration.

Example:

Router#show monitor-session status
                   Monitor-session mon1
                   Destination File - Packet collecting
                   =============================================
                   Source Interface      Dir   Status
                   --------------------- ----  ------------------
                   Hu0/9/0/2             Rx    Operational
                   Monitor-session mon2
                   Destination File - Packet collecting
                   =========================================
                   Source Interface      Dir   Status
                   --------------------- ----  --------------
                   BE1                  Tx    Operational
                   Monitor-session mon3
                   Destination File - Packet collecting
                   =========================================
                   Source Interface      Dir   Status
                   --------------------- ----  --------------
                   BE2.1                 Both    Operational