1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<table class="head">
<tr>
<td class="head-ltitle">NG_BRIDGE(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">NG_BRIDGE(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ng_bridge</code> —
<span class="Nd">Ethernet bridging netgraph node type</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/types.h</a>></code>
<br/>
<code class="In">#include
<<a class="In">netgraph/ng_bridge.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">bridge</code> node type performs Ethernet
bridging over one or more links. Each link (represented by a connected hook)
is used to transmit and receive raw Ethernet frames. As packets are
received, the node learns which link each host resides on. Packets unicast
to a known host are directed out the appropriate link only, and other links
are spared the traffic. This behavior is in contrast to a hub, which always
forwards every received packet to every other link.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="LOOP_DETECTION"><a class="permalink" href="#LOOP_DETECTION">LOOP
DETECTION</a></h1>
<p class="Pp">The <code class="Nm">bridge</code> node incorporates a simple loop
detection algorithm. A loop is when two ports are connected to the same
physical medium. Loops are important to avoid because of packet storms,
which severely degrade performance. A packet storm results when the same
packet is sent and received over and over again. If a host is detected on
link A, and is then detected on link B within a certain time period after
first being detected on link A, then link B is considered to be a looped
back link. The time period is called the minimum stable time.</p>
<p class="Pp">A looped back link will be temporarily muted, i.e., all traffic
received on that link is ignored.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="IPFW_PROCESSING"><a class="permalink" href="#IPFW_PROCESSING">IPFW
PROCESSING</a></h1>
<p class="Pp">Processing of IP packets via the <a class="Xr">ipfirewall(4)</a>
mechanism on a per-link basis is not yet implemented.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1>
<p class="Pp">This node type supports an unlimited number of hooks. Each
connected hook represents a bridged link. The hooks are named
<var class="Ar">link0</var>, <var class="Ar">link1</var>, etc. Typically
these hooks are connected to the <var class="Ar">lower</var> hooks of one or
more <a class="Xr">ng_ether(4)</a> nodes. To connect the host machine to a
bridged network, simply connect the <var class="Ar">upper</var> hook of an
<a class="Xr">ng_ether(4)</a> node to the bridge node.</p>
<p class="Pp">Instead of naming a hook <var class="Ar">linkX</var> the hook
might be also named <var class="Ar">uplinkX</var>. The node does not learn
MAC addresses on uplink hooks, which keeps the internal address table small.
This way it is desirable to connect the <var class="Ar">lower</var> hook of
an <a class="Xr">ng_ether(4)</a> node to an <var class="Ar">uplink</var>
hook of the bridge, and ignore the complexity of the outside world. Frames
with unknown MACs are always sent out to <var class="Ar">uplink</var> hooks,
so no functionality is lost. The <var class="Ar">uplink0</var> hook is not
allowed.</p>
<p class="Pp">The <var class="Ar">linkX</var> and <var class="Ar">uplinkX</var>
hook numbers can be autoassigned. If a new hook name was specified as
<var class="Ar">link</var> or <var class="Ar">uplink</var> the node will
append lowest available valid number to the name of the new hook.</p>
<p class="Pp">Frames with unknown destination MAC addresses are replicated to
any available hook, unless the first connected hook is an
<var class="Ar">uplink</var> hook. In this case the node assumes, that all
unknown MAC addresses are located solely on the <var class="Ar">uplink</var>
hooks and only those hooks will be used to send out frames with unknown
destination MACs. If the first connected hook is an
<var class="Ar">link</var> hook, the node will replicate such frames to all
types of hooks, even if <var class="Ar">uplink</var> hooks are connected
later.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL
MESSAGES</a></h1>
<p class="Pp">This node type supports the generic control messages, plus the
following:</p>
<dl class="Bl-tag">
<dt id="NGM_BRIDGE_SET_CONFIG"><a class="permalink" href="#NGM_BRIDGE_SET_CONFIG"><code class="Dv">NGM_BRIDGE_SET_CONFIG</code></a>
(<var class="Ar">setconfig</var>)</dt>
<dd>Set the node configuration. This command takes a <var class="Vt">struct
ng_bridge_config</var> as an argument:
<div class="Bd Pp Bd-indent Li">
<pre>/* Node configuration structure */
struct ng_bridge_config {
u_char debugLevel; /* debug level */
uint32_t loopTimeout; /* link loopback mute time */
uint32_t maxStaleness; /* max host age before nuking */
uint32_t minStableAge; /* min time for a stable host */
};</pre>
</div>
<p class="Pp">The <var class="Va">debugLevel</var> field sets the debug
level on the node. At level of 2 or greater, detected loops are logged.
The default level is 1.</p>
<p class="Pp">The <var class="Va">loopTimeout</var> determines how long (in
seconds) a looped link is muted. The default is 60 seconds. The
<var class="Va">maxStaleness</var> parameter determines how long a
period of inactivity before a host's entry is forgotten. The default is
15 minutes. The <var class="Va">minStableAge</var> determines how
quickly a host must jump from one link to another before we declare a
loopback condition. The default is one second.</p>
</dd>
<dt id="NGM_BRIDGE_GET_CONFIG"><a class="permalink" href="#NGM_BRIDGE_GET_CONFIG"><code class="Dv">NGM_BRIDGE_GET_CONFIG</code></a>
(<var class="Ar">getconfig</var>)</dt>
<dd>Returns the current configuration as a <var class="Vt">struct
ng_bridge_config</var>.</dd>
<dt id="NGM_BRIDGE_RESET"><a class="permalink" href="#NGM_BRIDGE_RESET"><code class="Dv">NGM_BRIDGE_RESET</code></a>
(<var class="Ar">reset</var>)</dt>
<dd>Causes the node to forget all hosts and unmute all links. The node
configuration is not changed.</dd>
<dt id="NGM_BRIDGE_GET_STATS"><a class="permalink" href="#NGM_BRIDGE_GET_STATS"><code class="Dv">NGM_BRIDGE_GET_STATS</code></a>
(<var class="Ar">getstats</var>)</dt>
<dd>This command takes a four byte link number as an argument and returns a
<var class="Vt">struct ng_bridge_link_stats</var> containing statistics
for the corresponding <var class="Ar">link</var>, which must be currently
connected:
<div class="Bd Pp Bd-indent Li">
<pre>/* Statistics structure (one for each link) */
struct ng_bridge_link_stats {
uint64_t recvOctets; /* total octets rec'd on link */
uint64_t recvPackets; /* total pkts rec'd on link */
uint64_t recvMulticasts; /* multicast pkts rec'd on link */
uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */
uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */
uint64_t recvRunts; /* pkts rec'd less than 14 bytes */
uint64_t recvInvalid; /* pkts rec'd with bogus source addr */
uint64_t xmitOctets; /* total octets xmit'd on link */
uint64_t xmitPackets; /* total pkts xmit'd on link */
uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */
uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */
uint64_t loopDrops; /* pkts dropped due to loopback */
uint64_t loopDetects; /* number of loop detections */
uint64_t memoryFailures; /* times couldn't get mem or mbuf */
};</pre>
</div>
<p class="Pp">Negative numbers refer to the <var class="Ar">uplink</var>
hooks. So querying for -7 will get the statistics for hook
<var class="Ar">uplink7</var>.</p>
</dd>
<dt id="NGM_BRIDGE_CLR_STATS"><a class="permalink" href="#NGM_BRIDGE_CLR_STATS"><code class="Dv">NGM_BRIDGE_CLR_STATS</code></a>
(<var class="Ar">clrstats</var>)</dt>
<dd>This command takes a four byte link number as an argument and clears the
statistics for that link.</dd>
<dt id="NGM_BRIDGE_GETCLR_STATS"><a class="permalink" href="#NGM_BRIDGE_GETCLR_STATS"><code class="Dv">NGM_BRIDGE_GETCLR_STATS</code></a>
(<var class="Ar">getclrstats</var>)</dt>
<dd>Same as <code class="Dv">NGM_BRIDGE_GET_STATS</code>, but also atomically
clears the statistics as well.</dd>
<dt id="NGM_BRIDGE_GET_TABLE"><a class="permalink" href="#NGM_BRIDGE_GET_TABLE"><code class="Dv">NGM_BRIDGE_GET_TABLE</code></a>
(<var class="Ar">gettable</var>)</dt>
<dd>Returns the current host mapping table used to direct packets, in a
<var class="Vt">struct ng_bridge_host_ary</var>.</dd>
<dt id="NGM_BRIDGE_SET_PERSISTENT"><a class="permalink" href="#NGM_BRIDGE_SET_PERSISTENT"><code class="Dv">NGM_BRIDGE_SET_PERSISTENT</code></a>
(<var class="Ar">setpersistent</var>)</dt>
<dd>This command sets the persistent flag on the node, and takes no
arguments.</dd>
<dt id="NGM_BRIDGE_MOVE_HOST"><a class="permalink" href="#NGM_BRIDGE_MOVE_HOST"><code class="Dv">NGM_BRIDGE_MOVE_HOST</code></a>
(<var class="Ar">movehost</var>)</dt>
<dd>This command takes a <var class="Vt">struct ng_bridge_move_host</var> as
an argument. It assigns the MAC <var class="Va">addr</var> to the
<var class="Va">hook</var>. If the <var class="Va">hook</var> is the empty
string, the incoming hook of the control message is used as fallback.
<p class="Pp">If necessary, the MAC is removed from the currently assigned
hook and moved to the new one. If the MAC is moved faster than
<var class="Va">minStableAge</var>, the hook is considered as a loop and
will block traffic for <var class="Va">loopTimeout</var> seconds.</p>
<div class="Bd Pp Bd-indent Li">
<pre>struct ng_bridge_move_host {
u_char addr[ETHER_ADDR_LEN]; /* ethernet address */
char hook[NG_HOOKSIZ]; /* link where addr can be found */
};</pre>
</div>
</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1>
<p class="Pp">This node shuts down upon receipt of a
<code class="Dv">NGM_SHUTDOWN</code> control message, or when all hooks have
been disconnected. Setting the persistent flag via a
<code class="Dv">NGM_BRIDGE_SET_PERSISTENT</code> control message disables
automatic node shutdown when the last hook gets disconnected.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
<dt><span class="Pa">/usr/share/examples/netgraph/ether.bridge</span></dt>
<dd>Example script showing how to set up a bridging network</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">if_bridge(4)</a>, <a class="Xr">netgraph(4)</a>,
<a class="Xr">ng_ether(4)</a>, <a class="Xr">ng_hub(4)</a>,
<a class="Xr">ng_one2many(4)</a>, <a class="Xr">ngctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">ng_bridge</code> node type was implemented in
<span class="Ux">FreeBSD 4.2</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Archie Cobbs</span>
<<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>></p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">The <code class="Nm">ng_bridge</code> node refuses to create the
<var class="Ar">uplink0</var> hook to avoid later ambiguity with the
<code class="Dv">NGM_BRIDGE_GET_STATS</code> message.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">April 8, 2024</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
