1 .TH BRIDGE 8 "1 August 2012" "iproute2" "Linux"
3 bridge \- show / manipulate bridge addresses and devices
10 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
16 .BR link " | " fdb " | " mdb " | " vlan " | " monitor " }"
21 \fB\-V\fR[\fIersion\fR] |
22 \fB\-s\fR[\fItatistics\fR] |
23 \fB\-n\fR[\fIetns\fR] name |
24 \fB\-b\fR[\fIatch\fR] filename |
25 \fB\-c\fR[\folor\fR] |
26 \fB\-p\fR[\fIretty\fR] |
27 \fB\-j\fR[\fIson\fR] |
28 \fB\-o\fR[\fIneline\fr] }
40 .BR guard " { " on " | " off " } ] [ "
41 .BR hairpin " { " on " | " off " } ] [ "
42 .BR fastleave " { " on " | " off " } ] [ "
43 .BR root_block " { " on " | " off " } ] [ "
44 .BR learning " { " on " | " off " } ] [ "
45 .BR learning_sync " { " on " | " off " } ] [ "
46 .BR flood " { " on " | " off " } ] [ "
47 .BR hwmode " { " vepa " | " veb " } ] [ "
48 .BR mcast_flood " { " on " | " off " } ] [ "
49 .BR mcast_to_unicast " { " on " | " off " } ] [ "
50 .BR neigh_suppress " { " on " | " off " } ] [ "
51 .BR vlan_tunnel " { " on " | " off " } ] [ "
52 .BR isolated " { " on " | " off " } ] [ "
55 .BR nobackup_port " ] [ "
56 .BR self " ] [ " master " ]"
59 .BR "bridge link" " [ " show " ] [ "
64 .BR "bridge fdb" " { " add " | " append " | " del " | " replace " } "
68 .BR local " | " static " | " dynamic " } [ "
69 .BR self " ] [ " master " ] [ " router " ] [ " use " ] [ " extern_learn " ] [ " sticky " ] [ "
84 .BR "bridge fdb" " [ [ " show " ] [ "
97 .BR "bridge fdb get" " ["
109 .BR self " ] [ " master " ] [ " dynamic " ]"
112 .BR "bridge mdb" " { " add " | " del " } "
121 .BR permanent " | " temp " ] [ "
126 .BR "bridge mdb show " [ "
131 .BR "bridge vlan" " { " add " | " del " } "
137 .IR TUNNEL_ID " ] [ "
138 .BR pvid " ] [ " untagged " ] [ "
139 .BR self " ] [ " master " ] "
142 .BR "bridge vlan" " [ " show " | " tunnelshow " ] [ "
147 .BR "bridge monitor" " [ " all " | " neigh " | " link " | " mdb " ]"
152 .BR "\-V" , " -Version"
153 print the version of the
158 .BR "\-s" , " \-stats", " \-statistics"
159 output more information. If this option
160 is given multiple times, the amount of information increases.
161 As a rule, the information is statistics or some time values.
164 .BR "\-d" , " \-details"
165 print detailed information about MDB router ports.
168 .BR "\-n" , " \-net" , " \-netns " <NETNS>
171 to the specified network namespace
173 Actually it just simplifies executing of:
178 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
184 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
188 .BR "\-b", " \-batch " <FILENAME>
189 Read commands from provided file or standard input and invoke them.
190 First failure will cause termination of bridge command.
194 Don't terminate bridge command on errors in batch mode.
195 If there were any errors during execution of the commands, the application
196 return code will be non zero.
199 .BR \-c [ color ][ = { always | auto | never }
200 Configure color output. If parameter is omitted or
202 color output is enabled regardless of stdout state. If parameter is
204 stdout is checked to be a terminal before enabling color output. If parameter is
206 color output is disabled. If specified multiple times, the last one takes
207 precedence. This flag is ignored if
213 Output results in JavaScript Object Notation (JSON).
216 .BR "\-p", " \-pretty"
217 When combined with -j generate a pretty JSON output.
220 .BR "\-o", " \-oneline"
221 output each record on a single line, replacing line feeds
224 character. This is convenient when you want to count records
232 .SH BRIDGE - COMMAND SYNTAX
243 - Forwarding Database entry.
247 - Multicast group database entry.
256 Specifies the action to perform on the object.
257 The set of possible actions depends on the object type.
258 As a rule, it is possible to
259 .BR "add" , " delete"
264 ) objects, but some objects do not allow all of these operations
265 or have some additional commands. The
267 command is available for all objects. It prints
268 out a list of available commands and argument syntax conventions.
270 If no command is given, some default command is assumed.
273 or, if the objects of this class cannot be listed,
276 .SH bridge link - bridge port
279 objects correspond to the port devices of the bridge.
282 The corresponding commands set and display port status and bridge specific
285 .SS bridge link set - set bridge specific attributes on a port
289 interface name of the bridge port
293 the STP path cost of the specified port.
296 .BI priority " PRIO "
297 the STP port priority. The priority value is an unsigned 8-bit quantity
298 (number between 0 and 255). This metric is used in the designated port an
299 droot port selection algorithms.
303 the operation state of the port. Except state 0 (disable STP or BPDU filter feature),
304 this is primarily used by user space STP/RSTP
305 implementation. One may enter port state name (case insensitive), or one of the
306 numbers below. Negative inputs are ignored, and unrecognized names return an
312 state. Make this port completely inactive for STP. This is also called
313 BPDU filter and could be used to disable STP on an untrusted port, like
314 a leaf virtual devices.
320 state. Only valid if STP is enabled on the bridge. In this
321 state the port listens for STP BPDUs and drops all other traffic frames.
327 state. Only valid if STP is enabled on the bridge. In this
328 state the port will accept traffic only for the purpose of updating MAC
335 state. Port is fully active.
341 state. Only valid if STP is enabled on the bridge. This state
342 is used during the STP election process. In this state, port will only process
347 .BR "guard on " or " guard off "
348 Controls whether STP BPDUs will be processed by the bridge port. By default,
349 the flag is turned off allowed BPDU processing. Turning this flag on will
351 the bridge port if a STP BPDU packet is received.
353 If running Spanning Tree on bridge, hostile devices on the network
354 may send BPDU on a port and cause network failure. Setting
356 will detect and stop this by disabling the port.
357 The port will be restarted if link is brought down, or
358 removed and reattached. For example if guard is enable on
361 .B ip link set dev eth0 down; ip link set dev eth0 up
364 .BR "hairpin on " or " hairpin off "
365 Controls whether traffic may be send back out of the port on which it was
366 received. This option is also called reflective relay mode, and is used to support
367 basic VEPA (Virtual Ethernet Port Aggregator) capabilities.
368 By default, this flag is turned off and the bridge will not forward
369 traffic back out of the receiving port.
372 .BR "fastleave on " or " fastleave off "
373 This flag allows the bridge to immediately stop multicast traffic on a port
374 that receives IGMP Leave message. It is only used with IGMP snooping is
375 enabled on the bridge. By default the flag is off.
378 .BR "root_block on " or " root_block off "
379 Controls whether a given port is allowed to become root port or not. Only used
380 when STP is enabled on the bridge. By default the flag is off.
382 This feature is also called root port guard.
383 If BPDU is received from a leaf (edge) port, it should not
384 be elected as root port. This could be used if using STP on a bridge and the downstream bridges are not fully
385 trusted; this prevents a hostile guest from rerouting traffic.
388 .BR "learning on " or " learning off "
389 Controls whether a given port will learn MAC addresses from received traffic or
390 not. If learning if off, the bridge will end up flooding any traffic for which
391 it has no FDB entry. By default this flag is on.
394 .BR "learning_sync on " or " learning_sync off "
395 Controls whether a given port will sync MAC addresses learned on device port to
399 .BR "flood on " or " flood off "
400 Controls whether a given port will flood unicast traffic for which there is no FDB entry. By default this flag is on.
404 Some network interface cards support HW bridge functionality and they may be
405 configured in different modes. Currently support modes are:
408 - Data sent between HW ports is sent on the wire to the external
412 - bridging happens in hardware.
415 .BR "mcast_flood on " or " mcast_flood off "
416 Controls whether a given port will flood multicast traffic for which
417 there is no MDB entry. By default this flag is on.
420 .BR "mcast_to_unicast on " or " mcast_to_unicast off "
421 Controls whether a given port will replicate packets using unicast
422 instead of multicast. By default this flag is off.
424 This is done by copying the packet per host and
425 changing the multicast destination MAC to a unicast one accordingly.
428 works on top of the multicast snooping feature of
429 the bridge. Which means unicast copies are only delivered to hosts which
430 are interested in it and signalized this via IGMP/MLD reports
433 This feature is intended for interface types which have a more reliable
434 and/or efficient way to deliver unicast packets than broadcast ones
437 However, it should only be enabled on interfaces where no IGMPv2/MLDv1
438 report suppression takes place. IGMP/MLD report suppression issue is usually
439 overcome by the network daemon (supplicant) enabling AP isolation and
440 by that separating all STAs.
442 Delivery of STA-to-STA IP multicast is made possible again by
443 enabling and utilizing the bridge hairpin mode, which considers the
444 incoming port as a potential outgoing port, too (see
447 Hairpin mode is performed after multicast snooping, therefore leading to
448 only deliver reports to STAs running a multicast router.
451 .BR "neigh_suppress on " or " neigh_suppress off "
452 Controls whether neigh discovery (arp and nd) proxy and suppression is
453 enabled on the port. By default this flag is off.
456 .BR "vlan_tunnel on " or " vlan_tunnel off "
457 Controls whether vlan to tunnel mapping is enabled on the port. By
458 default this flag is off.
461 .BR "isolated on " or " isolated off "
462 Controls whether a given port will be isolated, which means it will be
463 able to communicate with non-isolated ports only. By default this
467 .BI backup_port " DEVICE"
468 If the port loses carrier all traffic will be redirected to the
469 configured backup port
473 Removes the currently configured backup port
477 link setting is configured on specified physical device
481 link setting is configured on the software bridge (default)
484 .BR "\-t" , " \-timestamp"
485 display current time when using monitor option.
487 .SS bridge link show - list ports configuration for all bridges.
489 This command displays port configuration and flags for all bridges.
491 To display port configuration and flags for a specific bridge, use the
492 "ip link show master <bridge_device>" command.
494 .SH bridge fdb - forwarding database management
497 objects contain known Ethernet addresses on a link.
500 The corresponding commands display fdb entries, add new entries,
504 .SS bridge fdb add - add a new fdb entry
506 This command creates a new fdb entry.
510 the Ethernet MAC address.
514 the interface to which this address is associated.
517 - is a local permanent fdb entry
521 - this is a synonym for "local"
525 - is a static (no arp) fdb entry
529 - is a dynamic reachable age-able fdb entry
533 - the address is associated with the port drivers fdb. Usually hardware.
537 - the address is associated with master devices fdb. Usually software (default).
541 - the destination address is associated with a router.
542 Valid if the referenced device is a VXLAN type device and has
543 route short circuit enabled.
547 - the address is in use. User space can use this option to
548 indicate to the kernel that the fdb entry is in use.
552 - this entry was learned externally. This option can be used to
553 indicate to the kernel that an entry was hardware or user-space
554 controller learnt dynamic entry. Kernel will not age such an entry.
558 - this entry will not change its port due to learning.
562 The next command line parameters apply only
563 when the specified device
568 the IP address of the destination
569 VXLAN tunnel endpoint where the Ethernet MAC ADDRESS resides.
573 the src VNI Network Identifier (or VXLAN Segment ID)
574 this entry belongs to. Used only when the vxlan device is in
575 external or collect metadata mode. If omitted the value specified at
576 vxlan device creation will be used.
580 the VXLAN VNI Network Identifier (or VXLAN Segment ID)
581 to use to connect to the remote VXLAN tunnel endpoint.
582 If omitted the value specified at vxlan device creation
587 the UDP destination PORT number to use to connect to the
588 remote VXLAN tunnel endpoint.
589 If omitted the default value is used.
593 device name of the outgoing interface for the
594 VXLAN device driver to reach the
595 remote VXLAN tunnel endpoint.
599 ecmp nexthop group for the VXLAN device driver
600 to reach remote VXLAN tunnel endpoints.
602 .SS bridge fdb append - append a forwarding database entry
603 This command adds a new fdb entry with an already known
605 Valid only for multicast link layer addresses.
606 The command adds support for broadcast and multicast
607 Ethernet MAC addresses.
608 The Ethernet MAC address is added multiple times into
609 the forwarding database and the vxlan device driver
610 sends a copy of the data packet to each entry found.
613 The arguments are the same as with
614 .BR "bridge fdb add" .
616 .SS bridge fdb delete - delete a forwarding database entry
617 This command removes an existing fdb entry.
620 The arguments are the same as with
621 .BR "bridge fdb add" .
623 .SS bridge fdb replace - replace a forwarding database entry
624 If no matching entry is found, a new one will be created instead.
627 The arguments are the same as with
628 .BR "bridge fdb add" .
630 .SS bridge fdb show - list forwarding entries.
632 This command displays the current forwarding table.
637 option, the command becomes verbose. It prints out the last updated
638 and last used time for each entry.
640 .SS bridge fdb get - get bridge forwarding entry.
642 lookup a bridge forwarding table entry.
646 the Ethernet MAC address.
650 the interface to which this address is associated.
654 the bridge port to which this address is associated. same as dev above.
658 the bridge to which this address is associated.
662 - the address is associated with the port drivers fdb. Usually hardware.
666 - the address is associated with master devices fdb. Usually software (default).
669 .SH bridge mdb - multicast group database management
672 objects contain known IP or L2 multicast group addresses on a link.
675 The corresponding commands display mdb entries, add new entries,
678 .SS bridge mdb add - add a new multicast group database entry
680 This command creates a new mdb entry.
684 the interface where this group address is associated.
688 the port whose link is known to have members of this multicast group.
692 the multicast group address (IPv4, IPv6 or L2 multicast) whose members reside
693 on the link connected to the port.
696 - the mdb entry is permanent. Optional for IPv4 and IPv6, mandatory for L2.
700 - the mdb entry is temporary (default)
705 optional source IP address of a sender for this multicast group. If IGMPv3 for IPv4, or
706 MLDv2 for IPv6 respectively, are enabled it will be included in the lookup when
707 forwarding multicast traffic.
711 the VLAN ID which is known to have members of this multicast group.
714 .SS bridge mdb delete - delete a multicast group database entry
715 This command removes an existing mdb entry.
718 The arguments are the same as with
719 .BR "bridge mdb add" .
721 .SS bridge mdb show - list multicast group database entries
723 This command displays the current multicast group membership table. The table
724 is populated by IGMP and MLD snooping in the bridge driver automatically. It
729 commands manually too.
733 the interface only whose entries should be listed. Default is to list all
739 option, the command becomes verbose. It prints out the ports known to have
745 option, the command displays timer values for mdb and router port entries.
747 .SH bridge vlan - VLAN filter list
750 objects contain known VLAN IDs for a link.
753 The corresponding commands display vlan filter entries, add new entries,
756 .SS bridge vlan add - add a new vlan filter entry
758 This command creates a new vlan filter entry.
762 the interface with which this vlan is associated.
766 the VLAN ID that identifies the vlan.
769 .BI tunnel_info " TUNNEL_ID"
770 the TUNNEL ID that maps to this vlan. The tunnel id is set in
771 dst_metadata for every packet that belongs to this vlan (applicable to
772 bridge ports with vlan_tunnel flag set).
776 the vlan specified is to be considered a PVID at ingress.
777 Any untagged frames will be assigned to this VLAN.
781 the vlan specified is to be treated as untagged on egress.
785 the vlan is configured on the specified physical device. Required if the
786 device is the bridge device.
790 the vlan is configured on the software bridge (default).
792 .SS bridge vlan delete - delete a vlan filter entry
793 This command removes an existing vlan filter entry.
796 The arguments are the same as with
797 .BR "bridge vlan add".
799 .BR "pvid " and " untagged"
802 .SS bridge vlan show - list vlan configuration.
804 This command displays the current VLAN filter table.
809 option, the command displays per-vlan traffic statistics.
811 .SS bridge vlan tunnelshow - list vlan tunnel mapping.
813 This command displays the current vlan tunnel info mapping.
815 .SH bridge monitor - state monitoring
819 utility can monitor the state of devices and addresses
820 continuously. This option has a slightly different format.
823 command is the first in the command line and then the object list follows:
825 .BR "bridge monitor" " [ " all " |"
829 is the list of object types that we want to monitor.
831 .BR link ", " fdb ", and " mdb "."
836 opens RTNETLINK, listens on it and dumps state changes in the format
837 described in previous sections.
840 If a file name is given, it does not listen on RTNETLINK,
841 but opens the file containing RTNETLINK messages saved in binary format
845 This command uses facilities added in Linux 3.0.
847 Although the forwarding table is maintained on a per-bridge device basis
848 the bridge device is not part of the syntax. This is a limitation of the
849 underlying netlink neighbour message protocol. When displaying the
850 forwarding table, entries for all bridges are displayed.
851 Add/delete/modify commands determine the underlying bridge device
852 based on the bridge to which the corresponding ethernet device is attached.
858 .RB "Please direct bugreports and patches to: " <netdev@vger.kernel.org>
861 Original Manpage by Stephen Hemminger