Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NG_BRIDGE(4)	       FreeBSD Kernel Interfaces Manual		  NG_BRIDGE(4)

     ng_bridge -- Ethernet bridging netgraph node type

     #include <sys/types.h>
     #include <netgraph/ng_bridge.h>

     The bridge	node type performs Ethernet bridging over one or more links.
     Each link (represented by a connected hook) is used to transmit and re-
     ceive raw Ethernet	frames.	 As packets are	received, the node learns
     which link	each host resides on.  Packets unicast to a known host are di-
     rected 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.

     The 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 per-
     formance.	A packet storm results when the	same packet is sent and	re-
     ceived 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 de-
     tected on link A, then link B is considered to be a looped	back link.
     The time period is	called the minimum stable time.

     A looped back link	will be	temporarily muted, i.e., all traffic received
     on	that link is ignored.

     Processing	of IP packets via the ipfirewall(4) mechanism on a per-link
     basis is not yet implemented.

     This node type supports an	unlimited number of hooks.  Each connected
     hook represents a bridged link.  The hooks	are named link0, link1,	etc.
     Typically these hooks are connected to the	lower hooks of one or more
     ng_ether(4) nodes.	 To connect the	host machine to	a bridged network,
     simply connect the	upper hook of an ng_ether(4) node to the bridge	node.

     Instead of	naming a hook linkX the	hook might be also named uplinkX.  The
     node does not learn MAC addresses on uplink hooks,	which keeps the	inter-
     nal address table small.  This way	it is desirable	to connect the lower
     hook of an	ng_ether(4) node to an uplink hook of the bridge, and ignore
     the complexity of the outside world.  Frames with unknown MACs are	always
     sent out to uplink	hooks, so no functionality is lost.

     Frames with unknown destination MAC addresses are replicated to any
     available hook, unless the	first connected	hook is	an uplink hook.	 In
     this case the node	assumes, that all unknown MAC addresses	are located
     soley on the uplink hooks and only	those hooks will be used to send out
     frames with unknown destination MACs.  If the first connected hook	is an
     link hook,	the node will replicate	such frames to all types of hooks,
     even if uplink hooks are connected	later.

     This node type supports the generic control messages, plus	the following:

     NGM_BRIDGE_SET_CONFIG (setconfig)
	  Set the node configuration.  This command takes a struct
	  ng_bridge_config as an argument:

	  /* 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 */

	  The debugLevel field sets the	debug level on the node.  At level of
	  2 or greater,	detected loops are logged.  The	default	level is 1.

	  The loopTimeout determines how long (in seconds) a looped link is
	  muted.  The default is 60 seconds.  The maxStaleness parameter de-
	  termines how long a period of	inactivity before a host's entry is
	  forgotten.  The default is 15	minutes.  The minStableAge determines
	  how quickly a	host must jump from one	link to	another	before we de-
	  clare	a loopback condition.  The default is one second.

     NGM_BRIDGE_GET_CONFIG (getconfig)
	  Returns the current configuration as a struct	ng_bridge_config.

     NGM_BRIDGE_RESET (reset)
	  Causes the node to forget all	hosts and unmute all links.  The node
	  configuration	is not changed.

     NGM_BRIDGE_GET_STATS (getstats)
	  This command takes a four byte link number as	an argument and	re-
	  turns	a struct ng_bridge_link_stats containing statistics for	the
	  corresponding	link, which must be currently connected:

	  /* 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 */

	  Negative numbers refer to the	uplink hooks.  So querying for -7 will
	  get the statistics for hook uplink7.

     NGM_BRIDGE_CLR_STATS (clrstats)
	  This command takes a four byte link number as	an argument and	clears
	  the statistics for that link.

     NGM_BRIDGE_GETCLR_STATS (getclrstats)
	  Same as NGM_BRIDGE_GET_STATS,	but also atomically clears the statis-
	  tics as well.

     NGM_BRIDGE_GET_TABLE (gettable)
	  Returns the current host mapping table used to direct	packets, in a
	  struct ng_bridge_host_ary.

     NGM_BRIDGE_SET_PERSISTENT (setpersistent)
	  This command sets the	persistent flag	on the node, and takes no ar-

     NGM_BRIDGE_MOVE_HOST (movehost)
	  This command takes a struct ng_bridge_move_host as an	argument.  It
	  assigns the MAC addr to the hook.  If	the hook is the	empty string,
	  the incoming hook of the control message is used as fallback.

	  If necessary,	the MAC	is removed from	the currently assigned hook
	  and moved to the new one.  If	the MAC	is moved faster	than
	  minStableAge,	the hook is considered as a loop and will block	traf-
	  fic for loopTimeout seconds.

	  struct ng_bridge_move_host {
	    u_char  addr[ETHER_ADDR_LEN]; /* ethernet address */
	    char    hook[NG_HOOKSIZ];	  /* link where	addr can be found */

     This node shuts down upon receipt of a NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.  Setting the persistent flag via a
     NGM_BRIDGE_SET_PERSISTENT control message disables	automatic node shut-
     down when the last	hook gets disconnected.

	       Example script showing how to set up a bridging network

     if_bridge(4), netgraph(4),	ng_ether(4), ng_hub(4),	ng_one2many(4),

     The ng_bridge node	type was implemented in	FreeBSD	4.2.

     Archie Cobbs <>

FreeBSD	13.0			 May 13, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help