1BRIDGE(8)                            Linux                           BRIDGE(8)
2
3
4

NAME

6       bridge - show / manipulate bridge addresses and devices
7

SYNOPSIS

9       bridge [ OPTIONS ] OBJECT { COMMAND | help }
10
11
12       OBJECT := { link | fdb | mdb | vlan | monitor }
13
14
15       OPTIONS := { -V[ersion] | -s[tatistics] | -n[etns] name | -b[atch]
16               filename | -c[olor] | -p[retty] | -j[son] | -o[neline] }
17
18       bridge link set dev DEV [ cost COST ] [ priority PRIO ] [ state STATE ]
19               [ guard { on | off } ] [ hairpin { on | off } ] [ fastleave {
20               on | off } ] [ root_block { on | off } ] [ learning { on | off
21               } ] [ learning_sync { on | off } ] [ flood { on | off } ] [ hw‐
22               mode { vepa | veb } ] [ mcast_flood { on | off } ] [
23               mcast_to_unicast { on | off } ] [ neigh_suppress { on | off } ]
24               [ vlan_tunnel { on | off } ] [ isolated { on | off } ] [
25               backup_port DEVICE ] [ nobackup_port ] [ self ] [ master ]
26
27       bridge link [ show ] [ dev DEV ]
28
29       bridge fdb { add | append | del | replace } LLADDR dev DEV { local |
30               static | dynamic } [ self ] [ master ] [ router ] [ use ] [ ex‐
31               tern_learn ] [ sticky ] [ src_vni VNI ] { [ dst IPADDR ] [ vni
32               VNI ] [ port PORT ] [ via DEVICE ] | nhid NHID }
33
34       bridge fdb [ [ show ] [ br BRDEV ] [ brport DEV ] [ vlan VID ] [ state
35               STATE ] [ dynamic ] ]
36
37       bridge fdb get [ to ] LLADDR [ br BRDEV ] { brport | dev } DEV [ vlan
38               VID ] [ vni VNI ] [ self ] [ master ] [ dynamic ]
39
40       bridge mdb { add | del } dev DEV port PORT grp GROUP [ src SOURCE ] [
41               permanent | temp ] [ vid VID ]
42
43       bridge mdb show [ dev DEV ]
44
45       bridge vlan { add | del } dev DEV vid VID [ tunnel_info TUNNEL_ID ] [
46               pvid ] [ untagged ] [ self ] [ master ]
47
48       bridge vlan set dev DEV vid VID [ state STP_STATE ]
49
50       bridge vlan [ show | tunnelshow ] [ dev DEV ]
51
52       bridge monitor [ all | neigh | link | mdb | vlan ]
53
54

OPTIONS

56       -V, -Version
57              print the version of the bridge utility and exit.
58
59
60       -s, -stats, -statistics
61              output more information. If this option is given multiple times,
62              the amount of information increases.  As a rule, the information
63              is statistics or some time values.
64
65
66       -d, -details
67              print detailed information about bridge vlan filter entries or
68              MDB router ports.
69
70
71       -n, -net, -netns <NETNS>
72              switches bridge to the specified network namespace NETNS.  Actu‐
73              ally it just simplifies executing of:
74
75              ip netns exec NETNS bridge [ OPTIONS ] OBJECT { COMMAND | help }
76
77              to
78
79              bridge -n[etns] NETNS [ OPTIONS ] OBJECT { COMMAND | help }
80
81
82       -b, -batch <FILENAME>
83              Read commands from provided file or standard input and invoke
84              them.  First failure will cause termination of bridge command.
85
86
87       -force Don't terminate bridge command on errors in batch mode.  If
88              there were any errors during execution of the commands, the ap‐
89              plication return code will be non zero.
90
91
92       -c[color][={always|auto|never}
93              Configure color output. If parameter is omitted or always, color
94              output is enabled regardless of stdout state. If parameter is
95              auto, stdout is checked to be a terminal before enabling color
96              output. If parameter is never, color output is disabled. If
97              specified multiple times, the last one takes precedence. This
98              flag is ignored if -json is also given.
99
100
101       -j, -json
102              Output results in JavaScript Object Notation (JSON).
103
104
105       -p, -pretty
106              When combined with -j generate a pretty JSON output.
107
108
109       -o, -oneline
110              output each record on a single line, replacing line feeds with
111              the '\' character. This is convenient when you want to count
112              records with wc(1) or to grep(1) the output.
113
114
115

BRIDGE - COMMAND SYNTAX

117   OBJECT
118       link   - Bridge port.
119
120
121       fdb    - Forwarding Database entry.
122
123
124       mdb    - Multicast group database entry.
125
126
127       vlan   - VLAN filter list.
128
129
130   COMMAND
131       Specifies the action to perform on the object.  The set of possible ac‐
132       tions depends on the object type.  As a rule, it is possible to add,
133       delete and show (or list ) objects, but some objects do not allow all
134       of these operations or have some additional commands. The help command
135       is available for all objects. It prints out a list of available com‐
136       mands and argument syntax conventions.
137
138       If no command is given, some default command is assumed.  Usually it is
139       list or, if the objects of this class cannot be listed, help.
140
141
143       link objects correspond to the port devices of the bridge.
144
145
146       The corresponding commands set and display port status and bridge spe‐
147       cific attributes.
148
149
150   bridge link set - set bridge specific attributes on a port
151       dev NAME
152              interface name of the bridge port
153
154
155       cost COST
156              the STP path cost of the specified port.
157
158
159       priority PRIO
160              the STP port priority. The priority value is an unsigned 8-bit
161              quantity (number between 0 and 255). This metric is used in the
162              designated port an droot port selection algorithms.
163
164
165       state STATE
166              the operation state of the port. Except state 0 (disable STP or
167              BPDU filter feature), this is primarily used by user space
168              STP/RSTP implementation. One may enter port state name (case in‐
169              sensitive), or one of the numbers below. Negative inputs are ig‐
170              nored, and unrecognized names return an error.
171
172              0 - port is in STP DISABLED state. Make this port completely in‐
173              active for STP. This is also called BPDU filter and could be
174              used to disable STP on an untrusted port, like a leaf virtual
175              devices.
176
177
178              1 - port is in STP LISTENING state. Only valid if STP is enabled
179              on the bridge. In this state the port listens for STP BPDUs and
180              drops all other traffic frames.
181
182
183              2 - port is in STP LEARNING state. Only valid if STP is enabled
184              on the bridge. In this state the port will accept traffic only
185              for the purpose of updating MAC address tables.
186
187
188              3 - port is in STP FORWARDING state. Port is fully active.
189
190
191              4 - port is in STP BLOCKING state. Only valid if STP is enabled
192              on the bridge. This state is used during the STP election
193              process. In this state, port will only process STP BPDUs.
194
195
196
197       guard on or guard off
198              Controls whether STP BPDUs will be processed by the bridge port.
199              By default, the flag is turned off allowed BPDU processing.
200              Turning this flag on will disables the bridge port if a STP BPDU
201              packet is received.
202
203              If running Spanning Tree on bridge, hostile devices on the net‐
204              work may send BPDU on a port and cause network failure. Setting
205              guard on will detect and stop this by disabling the port.  The
206              port will be restarted if link is brought down, or removed and
207              reattached.  For example if guard is enable on eth0:
208
209              ip link set dev eth0 down; ip link set dev eth0 up
210
211
212       hairpin on or hairpin off
213              Controls whether traffic may be send back out of the port on
214              which it was received. This option is also called reflective re‐
215              lay mode, and is used to support basic VEPA (Virtual Ethernet
216              Port Aggregator) capabilities.  By default, this flag is turned
217              off and the bridge will not forward traffic back out of the re‐
218              ceiving port.
219
220
221       fastleave on or fastleave off
222              This flag allows the bridge to immediately stop multicast traf‐
223              fic on a port that receives IGMP Leave message. It is only used
224              with IGMP snooping is enabled on the bridge. By default the flag
225              is off.
226
227
228       root_block on or root_block off
229              Controls whether a given port is allowed to become root port or
230              not. Only used when STP is enabled on the bridge. By default the
231              flag is off.
232
233              This feature is also called root port guard.  If BPDU is re‐
234              ceived from a leaf (edge) port, it should not be elected as root
235              port. This could be used if using STP on a bridge and the down‐
236              stream bridges are not fully trusted; this prevents a hostile
237              guest from rerouting traffic.
238
239
240       learning on or learning off
241              Controls whether a given port will learn MAC addresses from re‐
242              ceived traffic or not. If learning if off, the bridge will end
243              up flooding any traffic for which it has no FDB entry. By de‐
244              fault this flag is on.
245
246
247       learning_sync on or learning_sync off
248              Controls whether a given port will sync MAC addresses learned on
249              device port to bridge FDB.
250
251
252       flood on or flood off
253              Controls whether unicast traffic for which there is no FDB entry
254              will be flooded towards this given port. By default this flag is
255              on.
256
257
258       hwmode Some network interface cards support HW bridge functionality and
259              they may be configured in different modes. Currently support
260              modes are:
261
262              vepa - Data sent between HW ports is sent on the wire to the ex‐
263              ternal switch.
264
265              veb - bridging happens in hardware.
266
267
268       mcast_flood on or mcast_flood off
269              Controls whether multicast traffic for which there is no MDB en‐
270              try will be flooded towards this given port. By default this
271              flag is on.
272
273
274       mcast_to_unicast on or mcast_to_unicast off
275              Controls whether a given port will replicate packets using uni‐
276              cast instead of multicast. By default this flag is off.
277
278              This is done by copying the packet per host and changing the
279              multicast destination MAC to a unicast one accordingly.
280
281              mcast_to_unicast works on top of the multicast snooping feature
282              of the bridge. Which means unicast copies are only delivered to
283              hosts which are interested in it and signalized this via
284              IGMP/MLD reports previously.
285
286              This feature is intended for interface types which have a more
287              reliable and/or efficient way to deliver unicast packets than
288              broadcast ones (e.g. WiFi).
289
290              However, it should only be enabled on interfaces where no
291              IGMPv2/MLDv1 report suppression takes place. IGMP/MLD report
292              suppression issue is usually overcome by the network daemon
293              (supplicant) enabling AP isolation and by that separating all
294              STAs.
295
296              Delivery of STA-to-STA IP multicast is made possible again by
297              enabling and utilizing the bridge hairpin mode, which considers
298              the incoming port as a potential outgoing port, too (see hairpin
299              option).  Hairpin mode is performed after multicast snooping,
300              therefore leading to only deliver reports to STAs running a mul‐
301              ticast router.
302
303
304       neigh_suppress on or neigh_suppress off
305              Controls whether neigh discovery (arp and nd) proxy and suppres‐
306              sion is enabled on the port. By default this flag is off.
307
308
309       vlan_tunnel on or vlan_tunnel off
310              Controls whether vlan to tunnel mapping is enabled on the port.
311              By default this flag is off.
312
313
314       isolated on or isolated off
315              Controls whether a given port will be isolated, which means it
316              will be able to communicate with non-isolated ports only.  By
317              default this flag is off.
318
319
320       backup_port DEVICE
321              If the port loses carrier all traffic will be redirected to the
322              configured backup port
323
324
325       nobackup_port
326              Removes the currently configured backup port
327
328
329       self   link setting is configured on specified physical device
330
331
332       master link setting is configured on the software bridge (default)
333
334
335       -t, -timestamp
336              display current time when using monitor option.
337
338
339   bridge link show - list ports configuration for all bridges.
340       This command displays port configuration and flags for all bridges.
341
342       To display port configuration and flags for a specific bridge, use the
343       "ip link show master <bridge_device>" command.
344
345

bridge fdb - forwarding database management

347       fdb objects contain known Ethernet addresses on a link.
348
349
350       The corresponding commands display fdb entries, add new entries, append
351       entries, and delete old ones.
352
353
354   bridge fdb add - add a new fdb entry
355       This command creates a new fdb entry.
356
357
358       LLADDR the Ethernet MAC address.
359
360
361       dev DEV
362              the interface to which this address is associated.
363
364              local - is a local permanent fdb entry, which means that the
365              bridge will not forward frames with this destination MAC address
366              and VLAN ID, but terminate them locally. This flag is default
367              unless "static" or "dynamic" are explicitly specified.
368
369
370              permanent - this is a synonym for "local"
371
372
373              static - is a static (no arp) fdb entry
374
375
376              dynamic - is a dynamic reachable age-able fdb entry
377
378
379              self - the operation is fulfilled directly by the driver for the
380              specified network device. If the network device belongs to a
381              master like a bridge, then the bridge is bypassed and not noti‐
382              fied of this operation (and if the device does notify the
383              bridge, it is driver-specific behavior and not mandated by this
384              flag, check the driver for more details). The "bridge fdb add"
385              command can also be used on the bridge device itself, and in
386              this case, the added fdb entries will be locally terminated (not
387              forwarded). In the latter case, the "self" flag is mandatory.
388              The flag is set by default if "master" is not specified.
389
390
391              master - if the specified network device is a port that belongs
392              to a master device such as a bridge, the operation is fulfilled
393              by the master device's driver, which may in turn notify the port
394              driver too of the address. If the specified device is a master
395              itself, such as a bridge, this flag is invalid.
396
397
398              router - the destination address is associated with a router.
399              Valid if the referenced device is a VXLAN type device and has
400              route short circuit enabled.
401
402
403              use - the address is in use. User space can use this option to
404              indicate to the kernel that the fdb entry is in use.
405
406
407              extern_learn - this entry was learned externally. This option
408              can be used to indicate to the kernel that an entry was hardware
409              or user-space controller learnt dynamic entry. Kernel will not
410              age such an entry.
411
412
413              sticky - this entry will not change its port due to learning.
414
415
416      The next command line parameters apply only when the specified device
417      DEV is of type VXLAN.
418
419       dst IPADDR
420              the IP address of the destination VXLAN tunnel endpoint where
421              the Ethernet MAC ADDRESS resides.
422
423
424       src_vni VNI
425              the src VNI Network Identifier (or VXLAN Segment ID) this entry
426              belongs to. Used only when the vxlan device is in external or
427              collect metadata mode. If omitted the value specified at vxlan
428              device creation will be used.
429
430
431       vni VNI
432              the VXLAN VNI Network Identifier (or VXLAN Segment ID) to use to
433              connect to the remote VXLAN tunnel endpoint.  If omitted the
434              value specified at vxlan device creation will be used.
435
436
437       port PORT
438              the UDP destination PORT number to use to connect to the remote
439              VXLAN tunnel endpoint.  If omitted the default value is used.
440
441
442       via DEVICE
443              device name of the outgoing interface for the VXLAN device
444              driver to reach the remote VXLAN tunnel endpoint.
445
446
447       nhid NHID
448              ecmp nexthop group for the VXLAN device driver to reach remote
449              VXLAN tunnel endpoints.
450
451
452   bridge fdb append - append a forwarding database entry
453       This command adds a new fdb entry with an already known LLADDR.  Valid
454       only for multicast link layer addresses.  The command adds support for
455       broadcast and multicast Ethernet MAC addresses.  The Ethernet MAC ad‐
456       dress is added multiple times into the forwarding database and the
457       vxlan device driver sends a copy of the data packet to each entry
458       found.
459
460
461       The arguments are the same as with bridge fdb add.
462
463
464   bridge fdb delete - delete a forwarding database entry
465       This command removes an existing fdb entry.
466
467
468       The arguments are the same as with bridge fdb add.
469
470
471   bridge fdb replace - replace a forwarding database entry
472       If no matching entry is found, a new one will be created instead.
473
474
475       The arguments are the same as with bridge fdb add.
476
477
478   bridge fdb show - list forwarding entries.
479       This command displays the current forwarding table.
480
481
482       With the -statistics option, the command becomes verbose. It prints out
483       the last updated and last used time for each entry.
484
485
486   bridge fdb get - get bridge forwarding entry.
487       lookup a bridge forwarding table entry.
488
489
490       LLADDR the Ethernet MAC address.
491
492
493       dev DEV
494              the interface to which this address is associated.
495
496
497       brport DEV
498              the bridge port to which this address is associated. same as dev
499              above.
500
501
502       br DEV the bridge to which this address is associated.
503
504
505       self   - the address is associated with the port drivers fdb. Usually
506              hardware.
507
508
509       master - the address is associated with master devices fdb. Usually
510              software (default).
511
512
513

bridge mdb - multicast group database management

515       mdb objects contain known IP or L2 multicast group addresses on a link.
516
517
518       The corresponding commands display mdb entries, add new entries, and
519       delete old ones.
520
521
522   bridge mdb add - add a new multicast group database entry
523       This command creates a new mdb entry.
524
525
526       dev DEV
527              the interface where this group address is associated.
528
529
530       port PORT
531              the port whose link is known to have members of this multicast
532              group.
533
534
535       grp GROUP
536              the multicast group address (IPv4, IPv6 or L2 multicast) whose
537              members reside on the link connected to the port.
538
539              permanent - the mdb entry is permanent. Optional for IPv4 and
540              IPv6, mandatory for L2.
541
542
543              temp - the mdb entry is temporary (default)
544
545
546
547       src SOURCE
548              optional source IP address of a sender for this multicast group.
549              If IGMPv3 for IPv4, or MLDv2 for IPv6 respectively, are enabled
550              it will be included in the lookup when forwarding multicast
551              traffic.
552
553
554       vid VID
555              the VLAN ID which is known to have members of this multicast
556              group.
557
558
559   bridge mdb delete - delete a multicast group database entry
560       This command removes an existing mdb entry.
561
562
563       The arguments are the same as with bridge mdb add.
564
565
566   bridge mdb show - list multicast group database entries
567       This command displays the current multicast group membership table. The
568       table is populated by IGMP and MLD snooping in the bridge driver auto‐
569       matically. It can be altered by bridge mdb add and bridge mdb del com‐
570       mands manually too.
571
572
573       dev DEV
574              the interface only whose entries should be listed. Default is to
575              list all bridge interfaces.
576
577
578       With the -details option, the command becomes verbose. It prints out
579       the ports known to have a connected router.
580
581
582       With the -statistics option, the command displays timer values for mdb
583       and router port entries.
584
585

bridge vlan - VLAN filter list

587       vlan objects contain known VLAN IDs for a link.
588
589
590       The corresponding commands display vlan filter entries, add new en‐
591       tries, and delete old ones.
592
593
594   bridge vlan add - add a new vlan filter entry
595       This command creates a new vlan filter entry.
596
597
598       dev NAME
599              the interface with which this vlan is associated.
600
601
602       vid VID
603              the VLAN ID that identifies the vlan.
604
605
606       tunnel_info TUNNEL_ID
607              the TUNNEL ID that maps to this vlan. The tunnel id is set in
608              dst_metadata for every packet that belongs to this vlan (appli‐
609              cable to bridge ports with vlan_tunnel flag set).
610
611
612       pvid   the vlan specified is to be considered a PVID at ingress.  Any
613              untagged frames will be assigned to this VLAN.
614
615
616       untagged
617              the vlan specified is to be treated as untagged on egress.
618
619
620       self   the vlan is configured on the specified physical device. Re‐
621              quired if the device is the bridge device.
622
623
624       master the vlan is configured on the software bridge (default).
625
626
627   bridge vlan delete - delete a vlan filter entry
628       This command removes an existing vlan filter entry.
629
630
631       The arguments are the same as with bridge vlan add.  The pvid and un‐
632       tagged flags are ignored.
633
634
635   bridge vlan set - change vlan filter entry's options
636       This command changes vlan filter entry's options.
637
638
639       dev NAME
640              the interface with which this vlan is associated.
641
642
643       vid VID
644              the VLAN ID that identifies the vlan.
645
646
647       state STP_STATE
648              the operation state of the vlan. One may enter STP state name
649              (case insensitive), or one of the numbers below. Negative inputs
650              are ignored, and unrecognized names return an error. Note that
651              the state is set only for the vlan of the specified device, e.g.
652              if it is a bridge port then the state will be set only for the
653              vlan of the port.
654
655              0 - vlan is in STP DISABLED state. Make this vlan completely in‐
656              active for STP. This is also called BPDU filter and could be
657              used to disable STP on an untrusted vlan.
658
659
660              1 - vlan is in STP LISTENING state. Only valid if STP is enabled
661              on the bridge. In this state the vlan listens for STP BPDUs and
662              drops all other traffic frames.
663
664
665              2 - vlan is in STP LEARNING state. Only valid if STP is enabled
666              on the bridge. In this state the vlan will accept traffic only
667              for the purpose of updating MAC address tables.
668
669
670              3 - vlan is in STP FORWARDING state. This is the default vlan
671              state.
672
673
674              4 - vlan is in STP BLOCKING state. Only valid if STP is enabled
675              on the bridge. This state is used during the STP election
676              process. In this state, the vlan will only process STP BPDUs.
677
678
679
680   bridge vlan show - list vlan configuration.
681       This command displays the current VLAN filter table.
682
683
684       With the -details option, the command becomes verbose. It displays the
685       per-vlan options.
686
687
688       With the -statistics option, the command displays per-vlan traffic sta‐
689       tistics.
690
691
692   bridge vlan tunnelshow - list vlan tunnel mapping.
693       This command displays the current vlan tunnel info mapping.
694
695

bridge monitor - state monitoring

697       The bridge utility can monitor the state of devices and addresses con‐
698       tinuously. This option has a slightly different format.  Namely, the
699       monitor command is the first in the command line and then the object
700       list follows:
701
702       bridge monitor [ all | OBJECT-LIST ]
703
704       OBJECT-LIST is the list of object types that we want to monitor.  It
705       may contain link, fdb, vlan and mdb.  If no file argument is given,
706       bridge opens RTNETLINK, listens on it and dumps state changes in the
707       format described in previous sections.
708
709
710       If a file name is given, it does not listen on RTNETLINK, but opens the
711       file containing RTNETLINK messages saved in binary format and dumps
712       them.
713
714

NOTES

716       This command uses facilities added in Linux 3.0.
717
718       Although the forwarding table is maintained on a per-bridge device ba‐
719       sis the bridge device is not part of the syntax. This is a limitation
720       of the underlying netlink neighbour message protocol. When displaying
721       the forwarding table, entries for all bridges are displayed.
722       Add/delete/modify commands determine the underlying bridge device based
723       on the bridge to which the corresponding ethernet device is attached.
724
725
726

SEE ALSO

728       ip(8)
729

BUGS

731       Please direct bugreports and patches to: <netdev@vger.kernel.org>
732
733

AUTHOR

735       Original Manpage by Stephen Hemminger
736
737
738
739iproute2                         1 August 2012                       BRIDGE(8)
Impressum