1.\" $OpenBSD: bridge.4,v 1.53 2003/07/09 13:26:20 jmc Exp $ 2.\" 3.\" Copyright (c) 1999-2001 Jason L. Wright (jason@thought.net) 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 19.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 24.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd February 26, 1999 28.Dt BRIDGE 4 29.Os 30.Sh NAME 31.Nm bridge 32.Nd Ethernet bridge interface 33.Sh SYNOPSIS 34.Cd "pseudo-device bridge 2" 35.Sh DESCRIPTION 36The 37.Nm 38device creates a logical link between two or more Ethernet interfaces or 39encapsulation interfaces (see 40.Xr gif 4 ) . 41This link between the interfaces selectively forwards frames from 42each interface on the bridge to every other interface on the bridge. 43A bridge can serve several services, including isolation of traffic between 44sets of machines so that traffic local to one set of machines is not 45available on the wire of another set of machines, and it can act as 46a transparent filter for 47.Xr ip 4 48datagrams. 49.Pp 50The bridges provided by this interface are learning bridges with 51filtering, see 52.Xr pf 4 . 53In general a bridge works like a hub, forwarding traffic from one interface 54to another. 55It differs from a hub in that it will "learn" which machines 56are on each of its attached segments by actively listening to 57incoming traffic and examining the headers of each frame. 58A table is built containing the MAC address and segment to which the 59MAC address is attached. 60This allows a bridge to be more selective about what it forwards, 61which can be used to reduce traffic on a set of segments and also to provide 62an IP firewall without changing the topology of the network. 63.Pp 64The algorithm works as follows by default, but can be modified via 65.Xr ioctl 2 66or the utility 67.Xr brconfig 8 . 68When a frame comes in, the origin segment and the source address are 69recorded. 70If the bridge has no knowledge about where the destination is to be found, 71the bridge will forward the frame to all attached segments. 72If the destination is known to be on a different segment from its origin, the 73bridge will forward the packet only to the destination segment. 74If the destination is on the same segment as the origin segment, the bridge 75will drop the packet because the receiver has already had a chance to see 76the frame. 77Before forwarding a frame, the bridge will check to see if the packet 78contains an 79.Xr ip 4 80or 81.Xr ip6 4 82datagram; if so, the datagram is run through the 83.Xr pf 4 84interface so that it can be filtered. 85.Sh IOCTLS 86A 87.Nm 88interface responds to all of the 89.Xr ioctl 2 90calls specific to other interfaces listed in 91.Xr netintro 4 . 92The following 93.Xr ioctl 2 94calls are specific to 95.Nm 96devices. 97They are defined in 98.Aq Pa sys/sockio.h . 99.Pp 100.Bl -tag -width SIOCBRDGGIFFLGS 101.It Dv SIOCBRDGIFS 102.Pq Li "struct ifbifconf" 103Retrieve member interface list from a bridge. 104This request takes an 105.Li ifbifconf 106structure (see below) as a value-result parameter. 107The 108.Fa ifbic_len 109field should be initially set to the size of the buffer 110pointed to by 111.Fa ifbic_buf . 112On return it will contain the length, in bytes, of the configuration 113list. 114Alternatively, if the 115.Fa ifbic_len 116passed in is set to 0, 117.Dv SIOCBRDGIFS 118will set 119.Fa ifbic_len 120to the size that 121.Fa ifbic_buf 122needs to be to fit the entire configuration list, 123and will not fill in the other parameters. 124This is useful for determining the exact size that 125.Fa ifbic_buf 126needs to be in advance. 127.Pp 128The argument structure is defined as follows: 129.Bd -literal -offset indent 130struct ifbreq { 131 char ifbr_name[IFNAMSIZ]; /* brdg nam */ 132 char ifbr_ifsname[IFNAMSIZ]; /* if name */ 133 u_int32_t ifbr_ifsflags; /* if flags */ 134}; 135 136#define IFBIF_LEARNING 0x1 /* learns addrs */ 137#define IFBIF_DISCOVER 0x2 /* gets fwd'd pkts */ 138 139struct ifbifconf { 140 char ifbic_name[IFNAMSIZ]; /* brdg name */ 141 u_int32_t ifbic_len; /* buf size */ 142 union { 143 caddr_t ifbicu_buf; /* buffer */ 144 struct ifbreq *ifbicu_req; 145 } ifbic_ifbicu; 146#define ifbic_buf ifbic_ifbicu.ifbicu_buf 147#define ifbic_req ifbic_ifbicu.ifbicu_req 148}; 149.Ed 150.It Dv SIOCBRDGADD 151.Pq Li "struct ifbreq" 152Add the interface named in 153.Fa ifbr_ifsname 154to the bridge named in 155.Fa ifbr_name . 156.It Dv SIOCBRDGDEL 157.Pq Li "struct ifbreq" 158Delete the interface named in 159.Fa ifbr_ifsname 160from the bridge named in 161.Fa ifbr_name . 162.It Dv SIOCBRDGADDS 163.Pq Li "struct ifbreq" 164Add the interface named in 165.Fa ifbr_ifsname 166as a span port to the bridge named in 167.Fa ifbr_name . 168.It Dv SIOCBRDGDELS 169.Pq Li "struct ifbreq" 170Delete the interface named in 171.Fa ifbr_ifsname 172from the list of span ports of the bridge named in 173.Fa ifbr_name . 174.It Dv SIOCBRDGSIFFLGS 175.Pq Li "struct ifbreq" 176Set the bridge member interface flags for the interface named in 177.Fa ifbr_ifsname 178attached to the bridge 179.Fa ifbr_name . 180If the flag 181.Dv IFBIF_LEARNING 182is set on an interface, source addresses from frames received on the 183interface are recorded in the address cache. 184If the flag 185.Dv IFBIF_DISCOVER 186is set, the interface will receive packets destined for unknown 187destinations, otherwise a frame that has a destination not found 188in the address cache is not forwarded to this interface. 189The default for newly added interfaces has both flags set. 190If the flag 191.Dv IFBIF_BLOCKNONIP 192is set, packets that are one of 193.Xr ip 4 , 194.Xr ip6 4 , 195.Xr arp 4 , 196or 197Reverse ARP, will not be bridged from and to the interface. 198.It Dv SIOCBRDGGIFFLGS 199Retrieve the bridge member interface flags for the interface named in 200.Fa ifbr_ifsname 201attached to the bridge 202.Fa ifbr_name . 203.It Dv SIOCBRDGRTS 204.Pq Li "struct ifbaconf" 205Retrieve the address cache of the bridge named in 206.Fa ifbac_name . 207This request takes an 208.Li ifbaconf 209structure (see below) as a value result parameter. 210The 211.Fa ifbac_len 212field should be initially set to the size of the buffer pointed to by 213.Fa ifbac_buf . 214On return, it will contain the length, in bytes, of the configuration list. 215Alternatively, if the 216.Fa ifbac_len 217passed in is set to 0, 218.Dv SIOCBRDGRTS 219will set it to the size that 220.Fa ifbac_buf 221needs to be to fit the entire configuration list and not fill in the other 222parameters. 223As with 224.Dv SIOCBRDGIFS , 225this is useful for determining the exact size that 226.Fa ifbac_buf 227needs to be in advance. 228.Pp 229The argument structure is defined as follows: 230.Bd -literal -offset indent 231struct ifbareq { 232 char ifba_name[IFNAMSIZ]; /* brdg nam */ 233 char ifba_ifsname[IFNAMSIZ];/* dest ifs */ 234 u_int8_t ifba_age; /* addr age */ 235 u_int8_t ifba_flags; /* addr flag */ 236 struct ether_addr ifba_dst; /* dst addr */ 237}; 238 239#define IFBAF_TYPEMASK 0x03 /* addr type mask */ 240#define IFBAF_DYNAMIC 0x00 /* dynamic addr */ 241#define IFBAF_STATIC 0x01 /* static address */ 242 243struct ifbaconf { 244 char ifbac_name[IFNAMSIZ]; /* brdg name */ 245 u_int32_t ifbac_len; /* buf size */ 246 union { 247 caddr_t ifbacu_buf; /* buf */ 248 struct ifbareq *ifbacu_req; 249 } ifbac_ifbacu; 250#define ifbac_buf ifbac_ifbacu.ifbacu_buf 251#define ifbac_req ifbac_ifbacu.ifbacu_req 252}; 253.Ed 254Address cache entries with the type set to 255.Dv IFBAF_DYNAMIC 256in 257.Fa ifba_flags 258are entries learned by the bridge. 259Entries with the type set to 260.Dv IFBAF_STATIC 261are manually added entries. 262.It Dv SIOCBRDGSADDR 263.Pq Li "struct ifbareq" 264Add an entry, manually, to the address cache for the bridge named in 265.Fa ifba_name . 266The address and its associated interface and flags are set in the 267.Fa ifba_dst , 268.Fa ifba_ifsname , 269and 270.Fa ifba_flags 271fields, respectively. 272.It Dv SIOCBRDGDADDR 273.Pq Li "struct ifbareq" 274Delete an entry from the address cache of the bridge named in 275.Fa ifba_name . 276Entries are deleted strictly based on the address field 277.Fa ifba_dst . 278.It Dv SIOCBRDGSCACHE 279.Pq Li "struct ifbcachereq" 280Set the maximum address cache size for the bridge named in 281.Fa ifbc_name 282to 283.Fa ifbc_size 284entries. 285.Pp 286The argument structure is as follows: 287.Bd -literal -offset indent 288struct ifbcachereq { 289 char ifbc_name[IFNAMSIZ]; /* bridge */ 290 u_int32_t ifbc_size; /* size */ 291}; 292.Ed 293.It Dv SIOCBRDGGCACHE 294.Pq Li "struct ifbcachereq" 295Retrieve the maximum size of the address cache for the bridge 296.Fa ifbc_name . 297.It Dv SIOCBRDGSTO 298.Pq Li "struct ifbcachetoreq" 299Set the time, in seconds, that addresses which have not been 300seen on the network (transmitted a packet) remain in the cache. 301If the time is set to zero, no aging is performed on the address cache. 302The argument structure is as follows: 303.Bd -literal -offset indent 304struct ifbcachetoreq { 305 char ifbct_name[IFNAMSIZ]; /* bridge */ 306 u_int32_t ifbct_time; /* time */ 307}; 308.Ed 309.It Dv SIOCBRDGGTO 310.Pq Li "struct ifbcachetoreq" 311Retrieve the address cache expiration time (see above). 312.It Dv SIOCBRDGFLUSH 313.Pq Li "struct ifbreq" 314Flush addresses from the cache. 315.Fa ifbr_name 316contains the name of the bridge device, and 317.Fa ifbr_ifsflags 318should be set to 319.Dv IFBF_FLUSHALL 320to flush all addresses from the cache or 321.Dv IFBF_FLUSHDYN 322to flush only the dynamically learned addresses from the cache. 323.It Dv SIOCBRDGARL 324.Pq Li "struct ifbrlreq" 325Add an Ethernet address filtering rule to the bridge on a specific interface. 326.Fa ifbr_name 327contains the name of the bridge device, and 328.Fa ifbr_ifsname 329contains the name of the bridge member interface. 330The 331.Fa ifbr_action 332field is one of 333.Fa BRL_ACTION_PASS 334or 335.Fa BRL_ACTION_BLOCK , 336to pass or block matching frames respectively. 337The 338.Fa ifbr_flags 339specifies whether the rule should match on input, output, or both 340be using the flags 341.Fa BRL_FLAG_IN 342and 343.Fa BRL_FLAG_OUT . 344It also specifies whether either (or both) of the source and destination 345addresses should be matched by using the 346.Fa BRL_FLAG_SRCVALID 347and 348.Fa BRL_FLAG_DSTVALID 349flags. 350The 351.Fa ifbr_src 352field is the source address that triggers the rule (only considered if 353.Fa ifbr_flags 354has the 355.Fa BRL_FLAG_SRCVALID 356bit set). 357The 358.Fa ifbr_src 359field is the destination address that triggers the rule (only considered if 360.Fa ifbr_flags 361has the 362.Fa BRL_FLAG_DSTVALID 363bit set). 364.Pp 365The argument structure is as follows: 366.Bd -literal -offset indent 367struct ifbrlreq { 368 char ifbr_name[IFNAMSIZ]; 369 char ifbr_ifsname[IFNAMSIZ]; 370 u_int8_t ifbr_action; 371 u_int8_t ifbr_flags; 372 struct ether_addr ifbr_src; 373 struct ether_addr ifbr_dst; 374 char ifbr_tagname[PF_TAG_NAME_SIZE]; 375}; 376#define BRL_ACTION_BLOCK 0x01 377#define BRL_ACTION_PASS 0x02 378#define BRL_FLAG_IN 0x08 379#define BRL_FLAG_OUT 0x04 380.Ed 381.It Dv SIOCBRDGFRL 382.Pq Li "struct ifbrlreq" 383Remove all filtering rules from a bridge interface member. 384.Fa ifbr_name 385contains the name of the bridge device, and 386.Fa ifbr_ifsname 387contains the name of the bridge member interface. 388.It Dv SIOCBRDGGRL 389.Pq Li "struct ifbrlconf" 390Retrieve all of the rules from the bridge, 391.Fa ifbrl_name , 392for the member interface, 393.Fa ifbrl_ifsname . 394This request takes an 395.Li ifbrlconf 396structure (see below) as a value result parameter. 397The 398.Fa ifbrl_len 399field should be initially set to the size of the buffer pointed to by 400.Fa ifbrl_buf . 401On return, it will contain the length, in bytes, of the configuration list. 402Alternatively, if the 403.Fa ifbrl_len 404passed in is set to 0, 405.Dv SIOCBRDGGRL 406will set it to the size that 407.Fa ifbrl_buf 408needs to be to fit the entire configuration list and not fill in the other 409parameters. 410As with 411.Dv SIOCBRDGIFS , 412this is useful for determining the exact size that 413.Fa ifbrl_buf 414needs to be in advance. 415.Pp 416The argument structure is defined as follows: 417.Bd -literal -offset indent 418struct ifbrlconf { 419 char ifbrl_name[IFNAMSIZ]; /* brdg nam */ 420 char ifbrl_ifsname[IFNAMSIZ];/* ifs name */ 421 u_int32_t ifbr_len; /* buf len */ 422 union { 423 caddr_t ifbrlu_buf; 424 struct ifbrlreq *ifbrlu_req; 425 } ifrl_ifbrlu; 426#define ifbrl_buf ifbrl_ifbrlu.ifbrlu_buf 427#define ifbrl_req ifbrl_ifbrlu.ifbrlu_req 428}; 429.Ed 430.It Dv SIOCBRDGARL 431.Pq Li "struct ifbrlreq" 432Add a filtering rule to the bridge named in 433.Fa ifbr_name 434on the interface named in 435.Fa ifbr_ifsname . 436The argument structure is as follows: 437.Bd -literal -offset indent 438struct ifbrlreq { 439 char ifbr_name[IFNAMSIZ]; /* bridge */ 440 char ifbr_ifsname[IFNAMSIZ]; /* ifs */ 441 u_int8_t ifbr_action; /* handling */ 442 u_int8_t ifbr_flags; /* flags */ 443 struct ether_addr ifbr_src; /* src mac */ 444 struct ether_addr ifbr_dst; /* dst mac */ 445}; 446#define BRL_ACTION_BLOCK 0x01 447#define BRL_ACTION_PASS 0x02 448#define BRL_FLAG_IN 0x08 449#define BRL_FLAG_OUT 0x04 450#define BRL_FLAG_SRCVALID 0x02 451#define BRL_FLAG_DSTVALID 0x01 452.Ed 453.Pp 454Rules are applied in the order in which they were added to the bridge, 455and the first matching rule's action parameter determines the fate of 456the packet. 457The 458.Fa ifbr_action 459parameter specifies whether a frame matching the rule is to 460be blocked or passed. 461.Pp 462If the 463.Dv BRL_FLAG_IN 464bit is set in 465.Fa ifbr_flags , 466then the rule applies to frames received by the interface. 467If the 468.Dv BRL_FLAG_OUT 469bit is set, then the rule applies to frame transmitted by the interface. 470At least one of 471.Dv BRL_FLAG_IN 472or 473.Dv BRL_FLAG_OUT 474must be set. 475.Pp 476The source Ethernet address in 477.Fa ifbr_src 478is checked if the 479.Dv BRL_FLAG_SRCVALID 480bit is set in 481.Fa ifbr_flags . 482The destination address in 483.Fa ifbr_dst 484is checked if the 485.Dv BRL_FLAG_DSTVALID 486bit is set. 487If neither bit is set, the rule matches all frames. 488.It Dv SIOCBRDGFRL 489.Pq Li "struct ifbrlreq" 490Flush rules from the bridge 491.Fa ifbr_name 492on the interface 493.Fa ifbr_ifsname . 494.It Dv SIOCBRDGGRL 495.Pq Li "struct ifbrlconf" 496Retrieve an array of rules from the bridge for a particular interface. 497This request takes an 498.Li ifbrlconf 499structure (see below) as a value-result parameter. 500The 501.Fa ifbrl_len 502field should be initially set to the size of the buffer 503pointed to by 504.Fa ifbrl_buf . 505On return it will contain the length, in bytes, of the rule list. 506Alternatively, if the 507.Fa ifbrl_len 508passed in is set to 0, 509.Dv SIOCBRDGGRL 510will set 511.Fa ifbrl_len 512to the size that 513.Fa ifbrl_buf 514needs to be to fit the entire configuration list, 515and will not fill in the other parameters. 516This is useful for determining the exact size that 517.Fa ifbrl_buf 518needs to be in advance. 519.Pp 520The argument structure is as follows: 521.Bd -literal -offset indent 522struct ifbrlconf { 523 char ifbrl_name[IFNAMSIZ]; /* bridge */ 524 char ifbrl_ifsname[IFNAMSIZ];/* member */ 525 u_int32_t ifbrl_len; /* buflen */ 526 union { 527 caddr_t ifbrlu_buf; 528 struct ifbrlreq *ifbrlu_req; 529 } ifbrl_ifbrlu; 530#define ifbrl_buf ifbrl_ifbrlu.ifbrlu_buf 531#define ifbrl_req ifbrl_ifbrlu.ifbrlu_req 532}; 533.Ed 534.El 535.Sh ERRORS 536If the 537.Xr ioctl 2 538call fails, 539.Xr errno 2 540is set to one of the following values: 541.Bl -tag -width Er 542.It Bq Eq ENOENT 543For an add request, this means that the named interface is not configured 544into the system. 545For a delete operation, it means that the named interface is not a member 546of the bridge. 547For an address cache deletion, the address was not found in the table. 548.It Bq Eq ENOMEM 549Memory could not be allocated for an interface or cache entry 550to be added to the bridge. 551.It Bq Eq EEXIST 552The named interface is already a member of the bridge. 553.It Bq Eq EBUSY 554The named interface is already a member of another bridge. 555.It Bq Eq EINVAL 556The named interface is not an Ethernet interface or an invalid ioctl 557was performed on the bridge. 558.It Bq Eq ENETDOWN 559Address cache operation (flush, add, delete) on a bridge that is 560in the down state. 561.It Bq Eq EPERM 562Super-user privilege is required to add and delete interfaces to and from 563bridges and to set the bridge interface flags. 564.It Bq Eq EFAULT 565The buffer used in a 566.Dv SIOCBRDGIFS 567or 568.Dv SIOCBRDGRTS 569request points outside of the process's allocated address space. 570.It Bq Eq ESRCH 571No such member interface in the bridge. 572.El 573.Sh NOTES 574Bridged packets pass through 575.Xr pf 4 576twice. 577They can be filtered on any interface, in both directions. 578For stateful filtering, filtering on only one interface (using 579.Sq keep state ) 580and passing all traffic on the other interfaces is recommended. 581A state entry only permits outgoing packets from initial source to 582destination and incoming packets from initial destination to source. 583Since bridged packets pass through the filter twice with the source 584and destination addresses reversed between interfaces, two state 585entries (one for each direction) are required when all interfaces 586are filtered statefully. 587.Pp 588It is unsupported to use filter rules which would generate packets. 589This applies to rules with 590.Ar return , 591.Ar return-rst , 592.Ar return-icmp , 593.Ar return-icmp6 594or 595.Ar synproxy 596defined. 597.Pp 598If an IP packet is too large for the outgoing interface the bridge 599will perform IP fragmentation. 600This can happen when bridge members 601have different MTUs or when IP fragments are reassembled by 602.Xr pf 4 . 603Non-IP packets which are too large for the outgoing interface will be 604dropped. 605.Pp 606If the LINK2 flag is set on the 607.Nm bridge 608interface, the bridge will also perform transparent 609.Xr ipsec 4 610processing on the packets (encrypt or decrypt them), according to the 611policies set with the 612.Xr ipsecadm 8 613command by the administrator. 614If appropriate security associations (SAs) do not exist, any key 615management daemons such as 616.Xr isakmpd 8 617that are running on the bridge will be invoked to establish the 618necessary SAs. 619These daemons have to be configured as if they were running on the 620host whose traffic they are protecting (i.e., they need to have the 621appropriate authentication and authorization material, such as keys 622and certificates, to impersonate the protected host(s). 623.Sh SEE ALSO 624.Xr errno 2 , 625.Xr ioctl 2 , 626.Xr arp 4 , 627.Xr gif 4 , 628.Xr ip 4 , 629.Xr ip6 4 , 630.Xr ipsec 4 , 631.Xr netintro 4 , 632.Xr pf 4 , 633.Xr bridgename.if 5 , 634.Xr brconfig 8 , 635.Xr ipsecadm 8 , 636.Xr isakmpd 8 637.Sh HISTORY 638The 639.Xr brconfig 8 640command and the 641.Nm bridge 642kernel interface first appeared in 643.Ox 2.5 . 644.Sh AUTHORS 645The 646.Xr brconfig 8 647command and the 648.Nm bridge 649kernel interface were written by 650.An Jason L. Wright Aq jason@thought.net 651as part of an undergraduate independent study at the 652University of North Carolina at Greensboro. 653