`MIRror`

Manage port mirroring

MIRror

Shortest form: mir.

Port mirroring: the old global mirror settings, and mirror destinations (the mechanism SONiC’s mirror sessions use).

Forms:

mirror SHow
mirror DEST <create | destroy | add | delete | show> [Key=<value> …]
mirror [Mode=<Off|L2|L3>] [Port=<port>] [IngressBitMap=<pbmp>] [EgressBitMap=<pbmp>]

DEST must be written out in full. The words after it (create, show, …) must also be written out in full, but case does not matter.

The last form sets the global mirror-to port, the mirror mode and the ports whose received (IngressBitMap) or sent (EgressBitMap) traffic is mirrored. It reads the current settings, applies your options on top, and writes everything back. Mode=Off turns mirroring off.

Warning

mirror with no arguments is not a show command. It prints nothing and rewrites the current mirror settings on every port. Use mirror show to look.

The built-in help differs from what the shell accepts:

PreserveForMat=<Off|On> is in the help but is not accepted: the command fails.
The “Fabric Device Options” (BitMap=) are for old fabric chips and do nothing on Trident 3.
The help lists the dest keys in lower case. The shell’s names are Id, Mode, Tunnel, SrcPort, DestPort, SrcIP, DestIP, SrcIP6, DestIP6, SrcMAC, DestMAC, VLAN, tpid, Version, TTL, TOS, FlowLable and NoVLAN, so NoVLAN must be written out in full. Tunnel=OFF is also accepted.

mirror show and mirror dest show are safe; SONiC’s generate_dump runs both (scripts/generate_dump (show techsupport collector)). Every other form changes the mirror hardware behind SONiC’s back and can break its mirror sessions. EdgeNOS: How Cumulus/switchd programs an ACL in the BCM56846 FP (+ raw fp show / FP_TCAM captures) uses mirror show on a Cumulus Trident II switch.

Unvalidated — Old global form: mirror traffic received on xe1 to xe2

drivshell> mirror Mode=L2 Port=xe2 IngressBitMap=xe1

mirror show

Show each port’s mirror destinations for ingress, egress and, where supported, true egress mirroring, in the same format as dmirror (xe1: Mirror ingress to local port xe2). Prints No mirror ports configured if no port mirrors, as on a SONiC switch without mirror sessions. Safe.

Hardware-validated

drivshell> mirror show
No mirror ports configured

mirror dest show

List the mirror destinations. Each starts Mirror Dest <n>: Mirror ID: <id>;, followed by the tunnel type and its parameters (L2, IPv4/IPv6 GRE, sFlow) and the destination port or trunk. Prints No mirror destinations currently defined if there are none. Safe.

A SONiC switch has a mirror destination to cpu0 even without any mirror session configured (Mirror Dest 1: Mirror ID: 0; local port cpu0). It belongs to the SAI; do not destroy it.

Hardware-validated

drivshell> mirror dest show
Mirror Dest  1: Mirror ID:  0; local port cpu0

mirror dest create DestPort=<port> [Id=<id>] [Tunnel=<OFF|L2|GRE>] [SrcMAC=<mac>] [DestMAC=<mac>] [VLAN=<vid>] [tpid=<tpid>] [SrcIP=<addr>] [DestIP=<addr>] [SrcIP6=<addr6>] [DestIP6=<addr6>] [Version=<4|6>] [TTL=<n>] [TOS=<n>] [FlowLable=<n>] [NoVLAN=<bool>]

Create a mirror destination: a port or trunk, optionally reached through an L2 or IP GRE (ERSPAN-style) tunnel. Prints Mirror Id = 0x<id>. A non-zero Id creates the destination with that ID. Changes the hardware behind SONiC’s back.

Unvalidated

drivshell> mirror dest create DestPort=xe2

mirror dest add SrcPort=<port> Id=<id> Mode=<OFF|Ingress|Egress|EgressTrue|IngressEgress>

Start mirroring a source port to a mirror destination. Changes the hardware behind SONiC’s back.

Unvalidated

drivshell> mirror dest add SrcPort=xe1 Id=0x8000001 Mode=Ingress

mirror dest delete SrcPort=<port> Id=<id> Mode=<OFF|Ingress|Egress|EgressTrue|IngressEgress>

Stop mirroring a source port to a mirror destination. Changes the hardware behind SONiC’s back.

Unvalidated

drivshell> mirror dest delete SrcPort=xe1 Id=0x8000001 Mode=Ingress

mirror dest destroy Id=<id>

Delete a mirror destination. Without Id it prints mirror destination id is missing. Deleting a destination that a SONiC mirror session uses breaks that session.

Unvalidated

drivshell> mirror dest destroy Id=0x8000001

Built-in help

mirror [options...]
    show                 - display current mirror configuration
Switch Device Options:
    Mode=<Off|L2|L3>     - set the mirroring mode
    Port=<p>             - set the mirror-to destination port
    IngressBitMap=<pbmp> - ports with ingress mirroring enabled
    EgressBitMap=<pbmp>  - ports with egress mirroring enabled
    PreserveForMat=<Off|On> - preserve format
Fabric Device Options: (5670/5675)
    Port=<p>             - which port to set the bitmap
    BitMap=<pbmp>        - destination bitmap for mirroring
Advanced Options: (subcmd dest) to use mirror destination features
    create          (cmd) - creates a new mirror destination
    destroy         (cmd) - destroys mirror destination
    add             (cmd) - add created mirror destination to a port
    delete          (cmd) - delete mirror destination from a port
    show            (cmd) - display currently defined mirror destinations
    id=<id>         (arg) - mirror destination id
    destport=<p>    (arg) - mirror destination gport
    srcport=<p>     (arg) - source mirror port/gport
    mode=<OFF|Ingress|Egress|EgressTrue|IngressEgress> (arg) - mirroring mode
    tunnel=<L2|GRE> (arg) - mirroring tunnel
    srcIP=<IPv4>    (arg) - source IPv4 address for IP GRE tunneling
    destIP=<IPv4>   (arg) - destination IPv4 address for IP GRE tunneling
    srcIP6=<IPv6>   (arg) - source IPv6 address for IP GRE tunneling
    destIP6=<IPv6>  (arg) - destination IPv6 address for IP GRE tunneling
    srcMAC=<MAC>    (arg) - source MAC address for L2/IP GRE tunneling
    destMAC=<MAC>   (arg) - destination MAC address for L2/IP GRE tunneling
    vlan=<VLAN-ID>  (arg) - VLAN ID for L2/IP GRE tunneling
    tpid=<TPID>     (arg) - TPID for L2/IP GRE tunneling
    version=<IP-Version> (arg) - Version field for IP GRE tunneling
    ttl=<TTL>       (arg) - TTL field for IP GRE tunneling
    tos=<TOD>       (arg) - TOS field for IP GRE tunneling
    FlowLable=<FlowLable> (arg) - IPv6 header flow label field for IP GRE tunneling
    NoVlan=<T|F>    (arg) - Strip VLAN tag from mirrored packet