xref: /freebsd/share/man/man4/ng_bridge.4 (revision e943eceb928d1d277f28f262dd6d758c1d85e8d0)

.\" Copyright (c) 2000 Whistle Communications, Inc.
.\" All rights reserved.
.\"
.\" Subject to the following obligations and disclaimer of warranty, use and
.\" redistribution of this software, in source or object code forms, with or
.\" without modifications are expressly permitted by Whistle Communications;
.\" provided, however, that:
.\" 1. Any and all reproductions of the source or object code must include the
.\"    copyright notice above and the following disclaimer of warranties; and
.\" 2. No rights are granted, in any manner or form, to use Whistle
.\"    Communications, Inc. trademarks, including the mark "WHISTLE
.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
.\"    such appears in the above copyright notice or in the software.
.\"
.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
.\" OF SUCH DAMAGE.
.\"
.\" Author: Archie Cobbs <archie@FreeBSD.org>
.\"
.Dd April 8, 2024
.Dt NG_BRIDGE 4
.Os
.Sh NAME
.Nm ng_bridge
.Nd Ethernet bridging netgraph node type
.Sh SYNOPSIS
.In sys/types.h
.In netgraph/ng_bridge.h
.Sh DESCRIPTION
The
.Nm bridge
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.
.Sh LOOP DETECTION
The
.Nm bridge
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.
.Pp
A looped back link will be temporarily muted, i.e., all traffic
received on that link is ignored.
.Sh IPFW PROCESSING
Processing of IP packets via the
.Xr ipfirewall 4
mechanism on a per-link basis is not yet implemented.
.Sh HOOKS
This node type supports an unlimited number of hooks.
Each connected hook represents a bridged link.
The hooks are named
.Ar link0 ,
.Ar link1 ,
etc.
Typically these hooks are connected to the
.Ar lower
hooks of one or more
.Xr ng_ether 4
nodes.
To connect the host machine to a bridged network, simply connect the
.Ar upper
hook of an
.Xr ng_ether 4
node to the bridge node.
.Pp
Instead of naming a hook
.Ar linkX
the hook might be also named
.Ar uplinkX .
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
.Ar lower
hook of an
.Xr ng_ether 4
node to an
.Ar uplink
hook of the bridge, and ignore the complexity of the outside world.
Frames with unknown MACs are always sent out to
.Ar uplink
hooks, so no functionality is lost.
The
.Ar uplink0
hook is not allowed.
.Pp
The
.Ar linkX
and
.Ar uplinkX
hook numbers can be autoassigned.
If a new hook name was specified as
.Ar link
or
.Ar uplink
the node will append lowest available valid number to the name of the new hook.
.Pp
Frames with unknown destination MAC addresses are replicated to any
available hook, unless the first connected hook is an
.Ar uplink
hook.
In this case the node assumes, that all unknown MAC addresses are
located solely on the
.Ar uplink
hooks and only those hooks will be used to send out frames with
unknown destination MACs.
If the first connected hook is an
.Ar link
hook, the node will replicate such frames to all types of hooks,
even if
.Ar uplink
hooks are connected later.
.Sh CONTROL MESSAGES
This node type supports the generic control messages, plus the
following:
.Bl -tag -width foo
.It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig
Set the node configuration.
This command takes a
.Vt "struct ng_bridge_config"
as an argument:
.Bd -literal -offset 0n
/* 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 */
};
.Ed
.Pp
The
.Va debugLevel
field sets the debug level on the node.
At level of 2 or greater, detected loops are logged.
The default level is 1.
.Pp
The
.Va loopTimeout
determines how long (in seconds) a looped link is muted.
The default is 60 seconds.
The
.Va maxStaleness
parameter determines how long a period of inactivity before
a host's entry is forgotten.
The default is 15 minutes.
The
.Va minStableAge
determines how quickly a host must jump from one link to another
before we declare a loopback condition.
The default is one second.
.It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig
Returns the current configuration as a
.Vt "struct ng_bridge_config" .
.It Dv NGM_BRIDGE_RESET Pq Ar reset
Causes the node to forget all hosts and unmute all links.
The node configuration is not changed.
.It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats
This command takes a four byte link number as an argument and
returns a
.Vt "struct ng_bridge_link_stats"
containing statistics for the corresponding
.Ar link ,
which must be currently connected:
.Bd -literal -offset 0n
/* 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 */
};
.Ed
.Pp
Negative numbers refer to the
.Ar uplink
hooks.
So querying for -7 will get the statistics for hook
.Ar uplink7 .
.It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats
This command takes a four byte link number as an argument and
clears the statistics for that link.
.It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats
Same as
.Dv NGM_BRIDGE_GET_STATS ,
but also atomically clears the statistics as well.
.It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable
Returns the current host mapping table used to direct packets, in a
.Vt "struct ng_bridge_host_ary" .
.It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ar setpersistent
This command sets the persistent flag on the node, and takes no arguments.
.It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost
This command takes a
.Vt "struct ng_bridge_move_host"
as an argument.
It assigns the MAC
.Va addr
to the
.Va hook .
If the
.Va hook
is the empty string, the incoming hook of the control message is
used as fallback.
.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
.Va minStableAge ,
the hook is considered as a loop and will block traffic for
.Va loopTimeout
seconds.
.Bd -literal -offset 0n
struct ng_bridge_move_host {
  u_char  addr[ETHER_ADDR_LEN];	/* ethernet address */
  char    hook[NG_HOOKSIZ];	/* link where addr can be found */
};
.Ed
.El
.Sh SHUTDOWN
This node shuts down upon receipt of a
.Dv NGM_SHUTDOWN
control message, or when all hooks have been disconnected.
Setting the persistent flag via a
.Dv NGM_BRIDGE_SET_PERSISTENT
control message disables automatic node shutdown when the last hook gets
disconnected.
.Sh FILES
.Bl -tag -width XXXXXXXX -compact
.It Pa /usr/share/examples/netgraph/ether.bridge
Example script showing how to set up a bridging network
.El
.Sh SEE ALSO
.Xr if_bridge 4 ,
.Xr netgraph 4 ,
.Xr ng_ether 4 ,
.Xr ng_hub 4 ,
.Xr ng_one2many 4 ,
.Xr ngctl 8
.Sh HISTORY
The
.Nm
node type was implemented in
.Fx 4.2 .
.Sh AUTHORS
.An Archie Cobbs Aq Mt archie@FreeBSD.org
.Sh BUGS
The
.Nm
node refuses to create the
.Ar uplink0
hook to avoid later ambiguity with the
.Dv NGM_BRIDGE_GET_STATS
message.