NAME

       ng_bridge — Ethernet bridging netgraph node type

SYNOPSIS

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

DESCRIPTION

       The  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.

LOOP DETECTION

       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 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.

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

IPFW PROCESSING

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

HOOKS

       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.

CONTROL MESSAGES

       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 determines 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 declare 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 returns 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 */
            };

       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 statistics 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 arguments.

SHUTDOWN

       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 shutdown when the last hook gets disconnected.

FILES

       /usr/share/examples/netgraph/ether.bridge
                 Example script showing how to set up a bridging network

SEE ALSO

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

HISTORY

       The ng_bridge node type was implemented in FreeBSD 4.2.

AUTHORS

       Archie Cobbs <archie@FreeBSD.org>

Debian                                           October 2, 2019                                    NG_BRIDGE(4)