Fix xref order.
[dragonfly.git] / share / man / man4 / bridge.4
1 .\" Copyright 2001 Wasabi Systems, Inc.
2 .\" All rights reserved.
3 .\"
4 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
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 for the NetBSD Project by
17 .\"     Wasabi Systems, Inc.
18 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
19 .\"    or promote products derived from this software without specific prior
20 .\"    written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
24 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
26 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 .\" POSSIBILITY OF SUCH DAMAGE.
33 .\"
34 .\" $NetBSD: bridge.4,v 1.7 2005/06/23 12:47:38 peter Exp $
35 .\" $DragonFly: src/share/man/man4/bridge.4,v 1.8 2006/03/21 04:24:27 swildner Exp $
36 .\"
37 .Dd January 4, 2004
38 .Dt BRIDGE 4
39 .Os
40 .Sh NAME
41 .Nm bridge
42 .Nd network bridge device
43 .Sh SYNOPSIS
44 .Cd "pseudo-device bridge"
45 .Sh DESCRIPTION
46 The
47 .Nm
48 driver creates a logical link between two or more IEEE 802 networks
49 that use the same (or
50 .Dq similar enough )
51 framing format.
52 For example, it is possible to bridge Ethernet and 802.11 networks together,
53 but it is not possible to bridge Ethernet and Token Ring together.
54 .Pp
55 To use
56 .Nm bridge ,
57 the administrator must first create the interface and configure
58 the bridge parameters.
59 The bridge is created using the
60 .Xr ifconfig 8
61 .Cm create
62 subcommand.
63 The learning and forwarding behavior and other parameters of a
64 bridge are configured by the
65 .Xr brconfig 8
66 utility.
67 .Pp
68 A bridge can be used to provide several services, such as a simple
69 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation.
70 .Pp
71 A bridge works like a hub, forwarding traffic from one interface
72 to another.
73 Multicast and broadcast packets are always forwarded to all
74 interfaces that are part of the bridge.
75 For unicast traffic, the bridge learns which MAC addresses are associated
76 with which interfaces and will forward the traffic selectively.
77 .Pp
78 The
79 .Nm
80 driver implements the IEEE 802.1D Spanning Tree protocol (STP).
81 Spanning Tree is used to detect and remove loops in a network topology.
82 .Pp
83 Packet filtering can be used with any firewall package that hooks in via the
84 .Xr pfil 9
85 framework.
86 When filtering is enabled, bridged packets will pass through the filter
87 inbound on the originating interface, on the bridge interface and outbound on
88 the appropriate interfaces.
89 Either stage can be disabled, this behaviour can be controlled using
90 .Xr sysctl 8 :
91 Set
92 .Va net.link.bridge.pfil_member
93 to
94 .Li 1
95 to enable filtering on the incoming and outgoing member interfaces
96 and set
97 .Va net.link.bridge.pfil_bridge
98 to
99 .Li 1
100 to enable filtering on the bridge interface.
101 .Pp
102 ARP and REVARP packets are forwarded without being filtered and others
103 that are not IP nor IPv6 packets are not forwarded when filtering is
104 enabled.
105 .Pp
106 Note that packets to and from the bridging host will be seen by the
107 filter on the interface with the appropriate address configured as well
108 as on the interface on which the packet arrives or departs.
109 .Pp
110 The MTU of the first member interface to be added is used as the bridge MTU,
111 all additional members are required to have exactly the same value.
112 .Sh SEE ALSO
113 .Xr pf 4 ,
114 .Xr brconfig 8
115 .Sh HISTORY
116 The
117 .Nm
118 driver first appeared in
119 .Ox 2.5
120 and found its way into
121 .Dx 1.3 .
122 .Sh AUTHORS
123 .An -nosplit
124 The
125 .Nm bridge
126 driver was originally written by
127 .An Jason L. Wright
128 .Aq jason@thought.net
129 as part of an undergraduate independent study at the University of
130 North Carolina at Greensboro.
131 .Pp
132 This version of the
133 .Nm
134 driver has been heavily modified from the original version by
135 .An Jason R. Thorpe
136 .Aq thorpej@wasabisystems.com .
137 .Sh BUGS
138 The
139 .Nm
140 driver currently supports only Ethernet and Ethernet-like (e.g. 802.11)
141 network devices, with exactly the same interface MTU size as the bridge device.