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