NG_FWDSWITCH(4)

NAME
ng_fwdswitch - basic packet forwarding netgraph node type

SYNOPSIS
#include <netgraph/ng_fwdswitch.h>

DESCRIPTION
The fwdswitch provides a simple mechanism to forward packets over several links based on a custom forwarding table. In hooks are named as in0, in1, etc. while out hooks are named as out0, out1, etc. IP Packets coming into the in hooks will be checked against a table and will be fastforwarded to one of the out hooks. The filter is only able to catch packets checking its source or destination address against a specified IP network/netmask. Packets which are not caught by the filter or non-IP packets will be forwarded to the designated default out hook. Packets incoming in the out hooks will be silently discarded. Not a single packet will ever be forwarded to the in hooks.

Each of the connected many links may be considered to be up or down. Packets are never delivered out a many hook that is down. How a link is determined to be up or down depends on the node's configured link failure detection algorithm.

LINK FAILURE DETECTION
At this time, the only algorithm for determining when a link has failed, other than the hook being disconnected, is the ``manual'' algorithm: the node is explicitly told which of the links are up via the NGM_FWDSWITCH_SET_CONFIG control message (see below). Newly connected links are down until configured otherwise.

HOOKS
This node type supports up to NG_FWDSWITCH_MAX_INPUTS hooks named in0, in1, etc., and up to NG_FWDSWITCH_MAX_LINKS hooks named out0, out1, etc.

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

NGM_FWDSWITCH_SET_CONFIG
    Sets the node configuration using a struct ng_fwdswitch_link_config as the control message argument:

        /* Node configuration structure */
        struct ng_fwdswitch_config {
          u_int32_t   xmitAlg;        /* how to distribute packets */
          u_int32_t   failAlg;        /* how to detect link failure */
          u_char      enabledLinks[NG_FWDSWITCH_MAX_LINKS];
        };

    Currently, the only valid setting for the xmitAlg field is NG_ONE2MANY_XMIT_ROUNDROBIN; this is also the default setting. The only valid setting for failAlg is NG_FWDSWITCH_FAIL_MANUAL; this is also the default setting.

NGM_FWDSWITCH_GET_CONFIG
    Returns the current node configuration in a struct ng_fwdswitch_link_config.

NGM_FWDSWITCH_SET_FWDCONFIG
    This commands loads into the node the forwarding table which will be used to deliver packets. The commands takes as argument the struct ng_fwdswotch_fwdconfig as the control message argument:

        /* Forwarding switch configuration structure */
        struct ng_fwdswitch_fwdconfig {
          int32_t                               fwd_table_len;  /* number of filters */
          struct ng_fwdswitch_fwdconfig_entry   fwd_table[0];   /* forwarding table */
        };

NGM_FWDSWITCH_GET_FWDCONFIG
    Returns the current node configuration in a struct ng_fwdswitch_fwdconfig.

NGM_FWDSWITCH_GET_STATS
    This command takes a 32 bit link number as an argument and returns a struct ng_fwdswitch_link_stats containing statistics for the corresponding out link, which may or may not be currently connected:

        /* Statistics structure (one for each link) */
        struct ng_fwdswitch_link_stats {
          u_int64_t   recvOctets;     /* total octets rec'd on link */
          u_int64_t   recvPackets;    /* total pkts rec'd on link */
          u_int64_t   xmitOctets;     /* total octets xmit'd on link */
          u_int64_t   xmitPackets;    /* total pkts xmit'd on link */
        };

    To access statistics for the in0 and in1 links, use the link number -1 and -2.

NGM_FWDSWITCH_CLR_STATS
    This command takes a 32 bit link number as an argument and clears the statistics for that link.

NGM_FWDSWITCH_GETCLR_STATS
    Same as NGM_FWDSWITCH_GET_STATS, but also atomically clears the statistics for the link as well.

SHUTDOWN
This node shuts down upon receipt of a NGM_SHUTDOWN control message, or when all hooks have been disconnected.

EXAMPLES
In this example we will configure a couple of Ethernet interfaces as inputs whose packets will be forwarded to four output interfaces:

      # Plumb nodes together
      ngctl mkpeer ti0: fwdswitch lower in0
      ngctl name ti0:lower fswitch0
      ngctl connect ti1: fswitch0: lower in1
      ngctl connect xl0: fswitch0: lower out0
      ngctl connect xl1: fswitch0: lower out1
      ngctl connect xl2: fswitch0: lower out2
      ngctl connect xl3: fswitch0: lower out3
      # Allow xl0 through xl3 to recv ti0 and ti1 frames
      ngctl msg ti0: setpromisc 1
      ngctl msg ti1: setpromisc 1
      ngctl msg xl0: setautosrc 0
      ngctl msg xl1: setautosrc 0
      ngctl msg xl2: setautosrc 0
      ngctl msg xl3: setautosrc 0
      # Configure all four links as up
      ngctl msg fswitch0: \
        setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }"
      # Setup the packet switch
      ngctl msg fswitch0: \
        setfwdconfig "{ defaultlink=2 fwdtable_len=4 \
          { ipaddr=192.168.0.0 netmask=255.255.255.0 dstlink=0 } \
          { ipaddr=192.168.1.0 netmask=255.255.255.0 dstlink=1 } \
          { ipaddr=192.168.2.0 netmask=255.255.255.128 dstlink=2 } \
          { ipaddr=192.168.2.128 netmask=255.255.255.128 dstlink=3 } ] }"

BUGS
Some nasty bugs will panic your kernel.

SEE ALSO
netgraph(4), ng_ether(4), ng_one2many(4), ngctl(8)

HISTORY
The ng_fwdswitch node type has never seen light into FreeBSD.

AUTHORS
Rocco Lucia <rlucia@iscanet.com>