xref: /freebsd/share/man/man4/ng_bridge.4 (revision 631cabba47716ccecae352bb2b4521a489b64bb2)
1aebf2d1dSArchie Cobbs.\" Copyright (c) 2000 Whistle Communications, Inc.
2aebf2d1dSArchie Cobbs.\" All rights reserved.
3aebf2d1dSArchie Cobbs.\"
4aebf2d1dSArchie Cobbs.\" Subject to the following obligations and disclaimer of warranty, use and
5aebf2d1dSArchie Cobbs.\" redistribution of this software, in source or object code forms, with or
6aebf2d1dSArchie Cobbs.\" without modifications are expressly permitted by Whistle Communications;
7aebf2d1dSArchie Cobbs.\" provided, however, that:
8aebf2d1dSArchie Cobbs.\" 1. Any and all reproductions of the source or object code must include the
9aebf2d1dSArchie Cobbs.\"    copyright notice above and the following disclaimer of warranties; and
10aebf2d1dSArchie Cobbs.\" 2. No rights are granted, in any manner or form, to use Whistle
11aebf2d1dSArchie Cobbs.\"    Communications, Inc. trademarks, including the mark "WHISTLE
12aebf2d1dSArchie Cobbs.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13aebf2d1dSArchie Cobbs.\"    such appears in the above copyright notice or in the software.
14aebf2d1dSArchie Cobbs.\"
15aebf2d1dSArchie Cobbs.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16aebf2d1dSArchie Cobbs.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17aebf2d1dSArchie Cobbs.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18aebf2d1dSArchie Cobbs.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19aebf2d1dSArchie Cobbs.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20aebf2d1dSArchie Cobbs.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21aebf2d1dSArchie Cobbs.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22aebf2d1dSArchie Cobbs.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23aebf2d1dSArchie Cobbs.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24aebf2d1dSArchie Cobbs.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25aebf2d1dSArchie Cobbs.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26aebf2d1dSArchie Cobbs.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27aebf2d1dSArchie Cobbs.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28aebf2d1dSArchie Cobbs.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29aebf2d1dSArchie Cobbs.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30aebf2d1dSArchie Cobbs.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31aebf2d1dSArchie Cobbs.\" OF SUCH DAMAGE.
32aebf2d1dSArchie Cobbs.\"
33eddc45e7SJeroen Ruigrok van der Werven.\" Author: Archie Cobbs <archie@FreeBSD.org>
34aebf2d1dSArchie Cobbs.\"
35aebf2d1dSArchie Cobbs.\" $FreeBSD$
36aebf2d1dSArchie Cobbs.\"
37*631cabbaSGleb Smirnoff.Dd October 2, 2019
38aebf2d1dSArchie Cobbs.Dt NG_BRIDGE 4
393d45e180SRuslan Ermilov.Os
40aebf2d1dSArchie Cobbs.Sh NAME
41aebf2d1dSArchie Cobbs.Nm ng_bridge
42aebf2d1dSArchie Cobbs.Nd Ethernet bridging netgraph node type
43aebf2d1dSArchie Cobbs.Sh SYNOPSIS
4432eef9aeSRuslan Ermilov.In sys/types.h
4532eef9aeSRuslan Ermilov.In netgraph/ng_bridge.h
46aebf2d1dSArchie Cobbs.Sh DESCRIPTION
47aebf2d1dSArchie CobbsThe
48aebf2d1dSArchie Cobbs.Nm bridge
49aebf2d1dSArchie Cobbsnode type performs Ethernet bridging over one or more links.
50aebf2d1dSArchie CobbsEach link (represented by a connected hook) is used to transmit
51aebf2d1dSArchie Cobbsand receive raw Ethernet frames.
52aebf2d1dSArchie CobbsAs packets are received, the node learns which link each
53aebf2d1dSArchie Cobbshost resides on.
54aebf2d1dSArchie CobbsPackets unicast to a known host are directed out the appropriate
55aebf2d1dSArchie Cobbslink only, and other links are spared the traffic.
56aebf2d1dSArchie CobbsThis behavior is in contrast to a hub, which always forwards
57aebf2d1dSArchie Cobbsevery received packet to every other link.
58aebf2d1dSArchie Cobbs.Sh LOOP DETECTION
59aebf2d1dSArchie CobbsThe
60aebf2d1dSArchie Cobbs.Nm bridge
61aebf2d1dSArchie Cobbsnode incorporates a simple loop detection algorithm.
62aebf2d1dSArchie CobbsA loop is when two ports are connected to the same physical medium.
63aebf2d1dSArchie CobbsLoops are important to avoid because of packet storms, which severely
64aebf2d1dSArchie Cobbsdegrade performance.
65aebf2d1dSArchie CobbsA packet storm results when the same packet is sent and received
66aebf2d1dSArchie Cobbsover and over again.
67aebf2d1dSArchie CobbsIf a host is detected on link A, and is then detected on link B
68aebf2d1dSArchie Cobbswithin a certain time period after first being detected on link A,
69aebf2d1dSArchie Cobbsthen link B is considered to be a looped back link.
70aebf2d1dSArchie CobbsThe time period is called the minimum stable time.
71aebf2d1dSArchie Cobbs.Pp
72aebf2d1dSArchie CobbsA looped back link will be temporarily muted, i.e., all traffic
73aebf2d1dSArchie Cobbsreceived on that link is ignored.
74aebf2d1dSArchie Cobbs.Sh IPFW PROCESSING
75aebf2d1dSArchie CobbsProcessing of IP packets via the
76aebf2d1dSArchie Cobbs.Xr ipfirewall 4
77aebf2d1dSArchie Cobbsmechanism on a per-link basis is not yet implemented.
78aebf2d1dSArchie Cobbs.Sh HOOKS
79*631cabbaSGleb SmirnoffThis node type supports an unlimited number of hooks.
80aebf2d1dSArchie CobbsEach connected hook represents a bridged link.
81aebf2d1dSArchie CobbsThe hooks are named
82aebf2d1dSArchie Cobbs.Dv link0 ,
83aebf2d1dSArchie Cobbs.Dv link1 ,
84aebf2d1dSArchie Cobbsetc.
85aebf2d1dSArchie CobbsTypically these hooks are connected to the
86aebf2d1dSArchie Cobbs.Dv lower
87aebf2d1dSArchie Cobbshooks of one or more
88c2d6966aSPhilippe Charnier.Xr ng_ether 4
89aebf2d1dSArchie Cobbsnodes.
90aebf2d1dSArchie CobbsTo connect the host machine to a bridged network, simply connect the
91aebf2d1dSArchie Cobbs.Dv upper
92aebf2d1dSArchie Cobbshook of an
93c2d6966aSPhilippe Charnier.Xr ng_ether 4
94aebf2d1dSArchie Cobbsnode to the bridge node.
95aebf2d1dSArchie Cobbs.Sh CONTROL MESSAGES
96aebf2d1dSArchie CobbsThis node type supports the generic control messages, plus the
97aebf2d1dSArchie Cobbsfollowing:
98aebf2d1dSArchie Cobbs.Bl -tag -width foo
99c60bda17SJoel Dahl.It Dv NGM_BRIDGE_SET_CONFIG Pq Ic setconfig
100aebf2d1dSArchie CobbsSet the node configuration.
101aebf2d1dSArchie CobbsThis command takes a
102aebf2d1dSArchie Cobbs.Dv "struct ng_bridge_config"
103aebf2d1dSArchie Cobbsas an argument:
1043f610476SRuslan Ermilov.Bd -literal -offset 0n
105aebf2d1dSArchie Cobbs/* Node configuration structure */
106aebf2d1dSArchie Cobbsstruct ng_bridge_config {
107aebf2d1dSArchie Cobbs  u_char      debugLevel;           /* debug level */
1086b99842aSEd Schouten  uint32_t    loopTimeout;          /* link loopback mute time */
1096b99842aSEd Schouten  uint32_t    maxStaleness;         /* max host age before nuking */
1106b99842aSEd Schouten  uint32_t    minStableAge;         /* min time for a stable host */
111aebf2d1dSArchie Cobbs};
112aebf2d1dSArchie Cobbs.Ed
113aebf2d1dSArchie Cobbs.Pp
114aebf2d1dSArchie CobbsThe
115aebf2d1dSArchie Cobbs.Dv debugLevel
116aebf2d1dSArchie Cobbsfield sets the debug level on the node.
117aebf2d1dSArchie CobbsAt level of 2 or greater, detected loops are logged.
118aebf2d1dSArchie CobbsThe default level is 1.
119aebf2d1dSArchie Cobbs.Pp
120aebf2d1dSArchie CobbsThe
121aebf2d1dSArchie Cobbs.Dv loopTimeout
122aebf2d1dSArchie Cobbsdetermines how long (in seconds) a looped link is muted.
123aebf2d1dSArchie CobbsThe default is 60 seconds.
124aebf2d1dSArchie CobbsThe
125aebf2d1dSArchie Cobbs.Dv maxStaleness
126aebf2d1dSArchie Cobbsparameter determines how long a period of inactivity before
127aebf2d1dSArchie Cobbsa host's entry is forgotten.
128aebf2d1dSArchie CobbsThe default is 15 minutes.
129aebf2d1dSArchie CobbsThe
130aebf2d1dSArchie Cobbs.Dv minStableAge
131aebf2d1dSArchie Cobbsdetermines how quickly a host must jump from one link to another
132aebf2d1dSArchie Cobbsbefore we declare a loopback condition.
133aebf2d1dSArchie CobbsThe default is one second.
134c60bda17SJoel Dahl.It Dv NGM_BRIDGE_GET_CONFIG Pq Ic getconfig
135aebf2d1dSArchie CobbsReturns the current configuration as a
136aebf2d1dSArchie Cobbs.Dv "struct ng_bridge_config" .
137c60bda17SJoel Dahl.It Dv NGM_BRIDGE_RESET Pq Ic reset
138aebf2d1dSArchie CobbsCauses the node to forget all hosts and unmute all links.
139aebf2d1dSArchie CobbsThe node configuration is not changed.
140c60bda17SJoel Dahl.It Dv NGM_BRIDGE_GET_STATS Pq Ic getstats
141aebf2d1dSArchie CobbsThis command takes a four byte link number as an argument and
142aebf2d1dSArchie Cobbsreturns a
143aebf2d1dSArchie Cobbs.Dv "struct ng_bridge_link_stats"
144aebf2d1dSArchie Cobbscontaining statistics for the corresponding link, which must be
145aebf2d1dSArchie Cobbscurrently connected:
1463f610476SRuslan Ermilov.Bd -literal -offset 0n
147aebf2d1dSArchie Cobbs/* Statistics structure (one for each link) */
148aebf2d1dSArchie Cobbsstruct ng_bridge_link_stats {
1496b99842aSEd Schouten  uint64_t   recvOctets;     /* total octets rec'd on link */
1506b99842aSEd Schouten  uint64_t   recvPackets;    /* total pkts rec'd on link */
1516b99842aSEd Schouten  uint64_t   recvMulticasts; /* multicast pkts rec'd on link */
1526b99842aSEd Schouten  uint64_t   recvBroadcasts; /* broadcast pkts rec'd on link */
1536b99842aSEd Schouten  uint64_t   recvUnknown;    /* pkts rec'd with unknown dest addr */
1546b99842aSEd Schouten  uint64_t   recvRunts;      /* pkts rec'd less than 14 bytes */
1556b99842aSEd Schouten  uint64_t   recvInvalid;    /* pkts rec'd with bogus source addr */
1566b99842aSEd Schouten  uint64_t   xmitOctets;     /* total octets xmit'd on link */
1576b99842aSEd Schouten  uint64_t   xmitPackets;    /* total pkts xmit'd on link */
1586b99842aSEd Schouten  uint64_t   xmitMulticasts; /* multicast pkts xmit'd on link */
1596b99842aSEd Schouten  uint64_t   xmitBroadcasts; /* broadcast pkts xmit'd on link */
1606b99842aSEd Schouten  uint64_t   loopDrops;      /* pkts dropped due to loopback */
1616b99842aSEd Schouten  uint64_t   loopDetects;    /* number of loop detections */
1626b99842aSEd Schouten  uint64_t   memoryFailures; /* times couldn't get mem or mbuf */
163aebf2d1dSArchie Cobbs};
164aebf2d1dSArchie Cobbs.Ed
165c60bda17SJoel Dahl.It Dv NGM_BRIDGE_CLR_STATS Pq Ic clrstats
166aebf2d1dSArchie CobbsThis command takes a four byte link number as an argument and
167aebf2d1dSArchie Cobbsclears the statistics for that link.
168c60bda17SJoel Dahl.It Dv NGM_BRIDGE_GETCLR_STATS Pq Ic getclrstats
169aebf2d1dSArchie CobbsSame as
170aebf2d1dSArchie Cobbs.Dv NGM_BRIDGE_GET_STATS ,
171aebf2d1dSArchie Cobbsbut also atomically clears the statistics as well.
172c60bda17SJoel Dahl.It Dv NGM_BRIDGE_GET_TABLE Pq Ic gettable
173aebf2d1dSArchie CobbsReturns the current host mapping table used to direct packets, in a
174aebf2d1dSArchie Cobbs.Dv "struct ng_bridge_host_ary" .
175c60bda17SJoel Dahl.It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ic setpersistent
176f8aab721SMarko ZecThis command sets the persistent flag on the node, and takes no arguments.
177aebf2d1dSArchie Cobbs.El
178aebf2d1dSArchie Cobbs.Sh SHUTDOWN
179aebf2d1dSArchie CobbsThis node shuts down upon receipt of a
180aebf2d1dSArchie Cobbs.Dv NGM_SHUTDOWN
18125972509SEdward Tomasz Napieralacontrol message, or when all hooks have been disconnected.
18225972509SEdward Tomasz NapieralaSetting the persistent flag via a
183f8aab721SMarko Zec.Dv NGM_BRIDGE_SET_PERSISTENT
184f8aab721SMarko Zeccontrol message disables automatic node shutdown when the last hook gets
185f8aab721SMarko Zecdisconnected.
1862573be5cSArchie Cobbs.Sh FILES
1872573be5cSArchie Cobbs.Bl -tag -width XXXXXXXX -compact
1882573be5cSArchie Cobbs.It Pa /usr/share/examples/netgraph/ether.bridge
1892573be5cSArchie CobbsExample script showing how to set up a bridging network
1902573be5cSArchie Cobbs.El
191aebf2d1dSArchie Cobbs.Sh SEE ALSO
192b6de9e91SMax Laier.Xr if_bridge 4 ,
193aebf2d1dSArchie Cobbs.Xr netgraph 4 ,
194aebf2d1dSArchie Cobbs.Xr ng_ether 4 ,
195b462702fSRuslan Ermilov.Xr ng_hub 4 ,
196b462702fSRuslan Ermilov.Xr ng_one2many 4 ,
197aebf2d1dSArchie Cobbs.Xr ngctl 8
198aebf2d1dSArchie Cobbs.Sh HISTORY
199aebf2d1dSArchie CobbsThe
200aebf2d1dSArchie Cobbs.Nm
201aebf2d1dSArchie Cobbsnode type was implemented in
202aebf2d1dSArchie Cobbs.Fx 4.2 .
203aebf2d1dSArchie Cobbs.Sh AUTHORS
2046c899950SBaptiste Daroussin.An Archie Cobbs Aq Mt archie@FreeBSD.org
205