share/man/man4/ng_one2many.4

   1 .\" Copyright (c) 2000 Whistle Communications, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Subject to the following obligations and disclaimer of warranty, use and
   5 .\" redistribution of this software, in source or object code forms, with or
   6 .\" without modifications are expressly permitted by Whistle Communications;
   7 .\" provided, however, that:
   8 .\" 1. Any and all reproductions of the source or object code must include the
   9 .\"    copyright notice above and the following disclaimer of warranties; and
  10 .\" 2. No rights are granted, in any manner or form, to use Whistle
  11 .\"    Communications, Inc. trademarks, including the mark "WHISTLE
  12 .\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
  13 .\"    such appears in the above copyright notice or in the software.
  14 .\"
  15 .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
  16 .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
  17 .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
  18 .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
  20 .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
  21 .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
  22 .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
  23 .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
  24 .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
  25 .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  26 .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
  27 .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
  31 .\" OF SUCH DAMAGE.
  32 .\"
  33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd November 13, 2012
  38 .Dt NG_ONE2MANY 4
  39 .Os
  40 .Sh NAME
  41 .Nm ng_one2many
  42 .Nd packet multiplexing netgraph node type
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In netgraph/ng_one2many.h
  46 .Sh DESCRIPTION
  47 The
  48 .Nm one2many
  49 provides a simple mechanism for routing packets over several links
  50 in a one-to-many (and in the reverse direction, many-to-one) fashion.
  51 There is a single hook named
  52 .Dv one ,
  53 and multiple hooks named
  54 .Dv many0 ,
  55 .Dv many1 ,
  56 etc.
  57 Packets received on any of the
  58 .Dv many
  59 hooks are forwarded out the
  60 .Dv one
  61 hook.
  62 Packets received on the
  63 .Dv one
  64 hook are forwarded out one or more of the
  65 .Dv many
  66 hooks; which hook(s) is determined by the node's configured
  67 transmit algorithm.
  68 Packets are not altered in any way.
  69 .Pp
  70 Each of the connected many links may be considered to be up or down.
  71 Packets are never delivered out a many hook that is down.
  72 How a link is determined to be up or down depends on the node's
  73 configured link failure detection algorithm.
  74 .Pp
  75 Before an interface or link can be plumbed into a group, its status
  76 must be marked as being
  77 .Dq up .
  78 This is normally setup during the initial boot stages by
  79 .Xr rc.conf 5 .
  80 It is also possible to change an interface's status to
  81 .Dq up
  82 by using the
  83 .Xr ifconfig 8
  84 utility.
  85 .Sh TRANSMIT ALGORITHMS
  86 .Bl -tag -width foo
  87 .It Dv NG_ONE2MANY_XMIT_ROUNDROBIN
  88 Packets are delivered out the many hooks in sequential order.
  89 Each packet goes out on a different
  90 .Dv many
  91 hook.
  92 .It Dv NG_ONE2MANY_XMIT_ALL
  93 Packets are delivered out all the
  94 .Dv many
  95 hooks.
  96 Each packet goes out each
  97 .Dv many
  98 hook.
  99 .It Dv NG_ONE2MANY_XMIT_FAILOVER
 100 Packets are delivered out the first active
 101 .Dv many
 102 hook.
 103 .El
 104 .Pp
 105 In the future other algorithms may be added as well.
 106 .Sh LINK FAILURE DETECTION
 107 The node distinguishes between active and failed links.
 108 Data is sent only to active links.
 109 The following link failure detection algorithms are available:
 110 .Bl -tag -width foo
 111 .It Dv NG_ONE2MANY_FAIL_MANUAL
 112 The node is explicitly told which of the links are up via the
 113 .Dv NGM_ONE2MANY_SET_CONFIG
 114 control message (see below).
 115 Newly connected links are down until configured otherwise.
 116 .It Dv NG_ONE2MANY_FAIL_NOTIFY
 117 The node listens to flow control message from
 118 .Va many
 119 hooks, and considers link failed if
 120 .Dv NGM_LINK_IS_DOWN
 121 is received.
 122 If the
 123 .Dv NGM_LINK_IS_UP
 124 message is received, node considers link active.
 125 .El
 126 .Pp
 127 In the future other algorithms may be added as well.
 128 .Pp
 129 When all links are considered failed, node sends the
 130 .Dv NGM_LINK_IS_DOWN
 131 message towards the
 132 .Va one
 133 hook.
 134 When at least one link comes up, node sends the
 135 .Dv NGM_LINK_IS_UP
 136 message towards the
 137 .Va one
 138 hook.
 139 .Sh HOOKS
 140 This node type supports up to
 141 .Dv NG_ONE2MANY_MAX_LINKS
 142 hooks named
 143 .Dv many0 ,
 144 .Dv many1 ,
 145 etc.,
 146 plus a single hook named
 147 .Dv one .
 148 .Sh CONTROL MESSAGES
 149 This node type supports the generic control messages, plus the
 150 following:
 151 .Bl -tag -width foo
 152 .It Dv NGM_ONE2MANY_SET_CONFIG Pq Ic setconfig
 153 Sets the node configuration using a
 154 .Dv "struct ng_one2many_link_config"
 155 as the control message argument:
 156 .Bd -literal
 157 /* Node configuration structure */
 158 struct ng_one2many_config {
 159   uint32_t    xmitAlg;        /* how to distribute packets */
 160   uint32_t    failAlg;        /* how to detect link failure */
 161   u_char      enabledLinks[NG_ONE2MANY_MAX_LINKS];
 162 };
 163 .Ed
 164 .Pp
 165 Currently, the valid settings for the
 166 .Dv xmitAlg
 167 field are
 168 .Dv NG_ONE2MANY_XMIT_ROUNDROBIN
 169 (default) or
 170 .Dv NG_ONE2MANY_XMIT_ALL .
 171 The valid settings for
 172 .Dv failAlg
 173 are
 174 .Dv NG_ONE2MANY_FAIL_MANUAL
 175 (default) or
 176 .Dv NG_ONE2MANY_FAIL_NOTIFY .
 177 .It Dv NGM_ONE2MANY_GET_CONFIG Pq Ic getconfig
 178 Returns the current node configuration in a
 179 .Dv "struct ng_one2many_link_config" .
 180 .It Dv NGM_ONE2MANY_GET_STATS Pq Ic getstats
 181 This command takes a 32 bit link number as an argument and
 182 returns a
 183 .Dv "struct ng_one2many_link_stats"
 184 containing statistics for the corresponding
 185 .Dv many
 186 link, which may or may not be currently connected:
 187 .Bd -literal
 188 /* Statistics structure (one for each link) */
 189 struct ng_one2many_link_stats {
 190   uint64_t   recvOctets;     /* total octets rec'd on link */
 191   uint64_t   recvPackets;    /* total pkts rec'd on link */
 192   uint64_t   xmitOctets;     /* total octets xmit'd on link */
 193   uint64_t   xmitPackets;    /* total pkts xmit'd on link */
 194   uint64_t   memoryFailures; /* times couldn't get mem or mbuf */
 195 };
 196 .Ed
 197 .Pp
 198 To access statistics for the
 199 .Dv one
 200 link, use the link number
 201 .Dv -1 .
 202 .It Dv NGM_ONE2MANY_CLR_STATS Pq Ic clrstats
 203 This command takes a 32 bit link number as an argument and
 204 clears the statistics for that link.
 205 .It Dv NGM_ONE2MANY_GETCLR_STATS Pq Ic getclrstats
 206 Same as
 207 .Dv NGM_ONE2MANY_GET_STATS ,
 208 but also atomically clears the statistics for the link as well.
 209 .El
 210 .Sh SHUTDOWN
 211 This node shuts down upon receipt of a
 212 .Dv NGM_SHUTDOWN
 213 control message, or when all hooks have been disconnected.
 214 .Sh EXAMPLES
 215 The following commands will set up Ethernet interfaces
 216 .Dv fxp0
 217 to deliver packets alternating over the physical interfaces
 218 corresponding to networking interfaces
 219 .Dv fxp0
 220 through
 221 .Dv fxp3 :
 222 .Bd -literal
 223   # Plumb nodes together
 224
 225   ngctl mkpeer fxp0: one2many upper one
 226   ngctl connect fxp0: fxp0:upper lower many0
 227   ngctl connect fxp1: fxp0:upper lower many1
 228   ngctl connect fxp2: fxp0:upper lower many2
 229   ngctl connect fxp3: fxp0:upper lower many3
 230
 231   # Allow fxp1 through fxp3 to xmit/recv fxp0 frames
 232
 233   ngctl msg fxp1: setpromisc 1
 234   ngctl msg fxp2: setpromisc 1
 235   ngctl msg fxp3: setpromisc 1
 236   ngctl msg fxp1: setautosrc 0
 237   ngctl msg fxp2: setautosrc 0
 238   ngctl msg fxp3: setautosrc 0
 239
 240   # Configure all four links as up
 241
 242   ngctl msg fxp0:upper \\
 243     setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }"
 244
 245   # Bring up interface
 246
 247   ifconfig fxp0 192.168.1.1 netmask 0xfffffffc
 248 .Ed
 249 .Pp
 250 With a similar setup on a peer machine (using the address
 251 192.168.1.2), a point-to-point
 252 Ethernet connection with four times normal bandwidth is
 253 achieved.
 254 .Sh SEE ALSO
 255 .Xr netgraph 4 ,
 256 .Xr ng_bridge 4 ,
 257 .Xr ng_ether 4 ,
 258 .Xr ng_hub 4 ,
 259 .Xr ifconfig 8 ,
 260 .Xr ngctl 8
 261 .Sh HISTORY
 262 The
 263 .Nm
 264 node type was implemented in
 265 .Fx 4.2 .
 266 .Sh AUTHORS
 267 .An -nosplit
 268 The
 269 .Nm one2many
 270 netgraph node (with round-robin algorithm) was written by
 271 .An Archie Cobbs
 272 .Aq archie@FreeBSD.org .
 273 The all algorithm was added by
 274 .An Rogier R. Mulhuijzen
 275 .Aq drwilco@drwilco.net .
 276 .Sh BUGS
 277 More transmit and link failure algorithms should be supported.
 278 A good candidate is Cisco's Etherchannel.