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 March 1, 2011
  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 indent
 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
 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   u_int32_t   xmitAlg;        /* how to distribute packets */
 160   u_int32_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
 178 Returns the current node configuration in a
 179 .Dv "struct ng_one2many_link_config" .
 180 .It Dv NGM_ONE2MANY_GET_STATS
 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   u_int64_t   recvOctets;     /* total octets rec'd on link */
 191   u_int64_t   recvPackets;    /* total pkts rec'd on link */
 192   u_int64_t   xmitOctets;     /* total octets xmit'd on link */
 193   u_int64_t   xmitPackets;    /* total pkts xmit'd on link */
 194 };
 195 .Ed
 196 .Pp
 197 To access statistics for the
 198 .Dv one
 199 link, use the link number
 200 .Dv -1 .
 201 .It Dv NGM_ONE2MANY_CLR_STATS
 202 This command takes a 32 bit link number as an argument and
 203 clears the statistics for that link.
 204 .It Dv NGM_ONE2MANY_GETCLR_STATS
 205 Same as
 206 .Dv NGM_ONE2MANY_GET_STATS ,
 207 but also atomically clears the statistics for the link as well.
 208 .El
 209 .Sh SHUTDOWN
 210 This node shuts down upon receipt of a
 211 .Dv NGM_SHUTDOWN
 212 control message, or when all hooks have been disconnected.
 213 .Sh EXAMPLES
 214 The following commands will set up Ethernet interfaces
 215 .Dv fxp0
 216 to deliver packets alternating over the physical interfaces
 217 corresponding to networking interfaces
 218 .Dv fxp0
 219 through
 220 .Dv fxp3 :
 221 .Bd -literal
 222   # Plumb nodes together
 223
 224   ngctl mkpeer fxp0: one2many upper one
 225   ngctl connect fxp0: fxp0:upper lower many0
 226   ngctl connect fxp1: fxp0:upper lower many1
 227   ngctl connect fxp2: fxp0:upper lower many2
 228   ngctl connect fxp3: fxp0:upper lower many3
 229
 230   # Allow fxp1 through fxp3 to xmit/recv fxp0 frames
 231
 232   ngctl msg fxp1: setpromisc 1
 233   ngctl msg fxp2: setpromisc 1
 234   ngctl msg fxp3: setpromisc 1
 235   ngctl msg fxp1: setautosrc 0
 236   ngctl msg fxp2: setautosrc 0
 237   ngctl msg fxp3: setautosrc 0
 238
 239   # Configure all four links as up
 240
 241   ngctl msg fxp0:upper \\
 242     setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }"
 243
 244   # Bring up interface
 245
 246   ifconfig fxp0 192.168.1.1 netmask 0xfffffffc
 247 .Ed
 248 .Pp
 249 With a similar setup on a peer machine (using the address
 250 192.168.1.2), a point-to-point
 251 Ethernet connection with four times normal bandwidth is
 252 achieved.
 253 .Sh SEE ALSO
 254 .Xr netgraph 4 ,
 255 .Xr ng_bridge 4 ,
 256 .Xr ng_ether 4 ,
 257 .Xr ng_hub 4 ,
 258 .Xr ifconfig 8 ,
 259 .Xr ngctl 8
 260 .Sh HISTORY
 261 The
 262 .Nm
 263 node type was implemented in
 264 .Fx 4.2 .
 265 .Sh AUTHORS
 266 .An -nosplit
 267 The
 268 .Nm one2many
 269 netgraph node (with round-robin algorithm) was written by
 270 .An Archie Cobbs
 271 .Aq archie@FreeBSD.org .
 272 The all algorithm was added by
 273 .An Rogier R. Mulhuijzen
 274 .Aq drwilco@drwilco.net .
 275 .Sh BUGS
 276 More transmit and link failure algorithms should be supported.
 277 A good candidate is Cisco's Etherchannel.