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.Dd November 13, 2012 36.Dt NG_ONE2MANY 4 37.Os 38.Sh NAME 39.Nm ng_one2many 40.Nd packet multiplexing netgraph node type 41.Sh SYNOPSIS 42.In sys/types.h 43.In netgraph/ng_one2many.h 44.Sh DESCRIPTION 45The 46.Nm one2many 47provides a simple mechanism for routing packets over several links 48in a one-to-many (and in the reverse direction, many-to-one) fashion. 49There is a single hook named 50.Dv one , 51and multiple hooks named 52.Dv many0 , 53.Dv many1 , 54etc. 55Packets received on any of the 56.Dv many 57hooks are forwarded out the 58.Dv one 59hook. 60Packets received on the 61.Dv one 62hook are forwarded out one or more of the 63.Dv many 64hooks; which hook(s) is determined by the node's configured 65transmit algorithm. 66Packets are not altered in any way. 67.Pp 68Each of the connected many links may be considered to be up or down. 69Packets are never delivered out a many hook that is down. 70How a link is determined to be up or down depends on the node's 71configured link failure detection algorithm. 72.Pp 73Before an interface or link can be plumbed into a group, its status 74must be marked as being 75.Dq up . 76This is normally setup during the initial boot stages by 77.Xr rc.conf 5 . 78It is also possible to change an interface's status to 79.Dq up 80by using the 81.Xr ifconfig 8 82utility. 83.Sh TRANSMIT ALGORITHMS 84.Bl -tag -width foo 85.It Dv NG_ONE2MANY_XMIT_ROUNDROBIN 86Packets are delivered out the many hooks in sequential order. 87Each packet goes out on a different 88.Dv many 89hook. 90.It Dv NG_ONE2MANY_XMIT_ALL 91Packets are delivered out all the 92.Dv many 93hooks. 94Each packet goes out each 95.Dv many 96hook. 97.It Dv NG_ONE2MANY_XMIT_FAILOVER 98Packets are delivered out the first active 99.Dv many 100hook. 101.El 102.Pp 103In the future other algorithms may be added as well. 104.Sh LINK FAILURE DETECTION 105The node distinguishes between active and failed links. 106Data is sent only to active links. 107The following link failure detection algorithms are available: 108.Bl -tag -width foo 109.It Dv NG_ONE2MANY_FAIL_MANUAL 110The node is explicitly told which of the links are up via the 111.Dv NGM_ONE2MANY_SET_CONFIG 112control message (see below). 113Newly connected links are down until configured otherwise. 114.It Dv NG_ONE2MANY_FAIL_NOTIFY 115The node listens to flow control message from 116.Va many 117hooks, and considers link failed if 118.Dv NGM_LINK_IS_DOWN 119is received. 120If the 121.Dv NGM_LINK_IS_UP 122message is received, node considers link active. 123.El 124.Pp 125In the future other algorithms may be added as well. 126.Pp 127When all links are considered failed, node sends the 128.Dv NGM_LINK_IS_DOWN 129message towards the 130.Va one 131hook. 132When at least one link comes up, node sends the 133.Dv NGM_LINK_IS_UP 134message towards the 135.Va one 136hook. 137.Sh HOOKS 138This node type supports up to 139.Dv NG_ONE2MANY_MAX_LINKS 140hooks named 141.Dv many0 , 142.Dv many1 , 143etc., 144plus a single hook named 145.Dv one . 146.Sh CONTROL MESSAGES 147This node type supports the generic control messages, plus the 148following: 149.Bl -tag -width foo 150.It Dv NGM_ONE2MANY_SET_CONFIG Pq Ic setconfig 151Sets the node configuration using a 152.Dv "struct ng_one2many_link_config" 153as the control message argument: 154.Bd -literal 155/* Node configuration structure */ 156struct ng_one2many_config { 157 uint32_t xmitAlg; /* how to distribute packets */ 158 uint32_t failAlg; /* how to detect link failure */ 159 u_char enabledLinks[NG_ONE2MANY_MAX_LINKS]; 160}; 161.Ed 162.Pp 163Currently, the valid settings for the 164.Dv xmitAlg 165field are 166.Dv NG_ONE2MANY_XMIT_ROUNDROBIN 167(default) or 168.Dv NG_ONE2MANY_XMIT_ALL . 169The valid settings for 170.Dv failAlg 171are 172.Dv NG_ONE2MANY_FAIL_MANUAL 173(default) or 174.Dv NG_ONE2MANY_FAIL_NOTIFY . 175.It Dv NGM_ONE2MANY_GET_CONFIG Pq Ic getconfig 176Returns the current node configuration in a 177.Dv "struct ng_one2many_link_config" . 178.It Dv NGM_ONE2MANY_GET_STATS Pq Ic getstats 179This command takes a 32 bit link number as an argument and 180returns a 181.Dv "struct ng_one2many_link_stats" 182containing statistics for the corresponding 183.Dv many 184link, which may or may not be currently connected: 185.Bd -literal 186/* Statistics structure (one for each link) */ 187struct ng_one2many_link_stats { 188 uint64_t recvOctets; /* total octets rec'd on link */ 189 uint64_t recvPackets; /* total pkts rec'd on link */ 190 uint64_t xmitOctets; /* total octets xmit'd on link */ 191 uint64_t xmitPackets; /* total pkts xmit'd on link */ 192 uint64_t memoryFailures; /* times couldn't get mem or mbuf */ 193}; 194.Ed 195.Pp 196To access statistics for the 197.Dv one 198link, use the link number 199.Dv -1 . 200.It Dv NGM_ONE2MANY_CLR_STATS Pq Ic clrstats 201This command takes a 32 bit link number as an argument and 202clears the statistics for that link. 203.It Dv NGM_ONE2MANY_GETCLR_STATS Pq Ic getclrstats 204Same as 205.Dv NGM_ONE2MANY_GET_STATS , 206but also atomically clears the statistics for the link as well. 207.El 208.Sh SHUTDOWN 209This node shuts down upon receipt of a 210.Dv NGM_SHUTDOWN 211control message, or when all hooks have been disconnected. 212.Sh EXAMPLES 213The following commands will set up Ethernet interfaces 214.Dv fxp0 215to deliver packets alternating over the physical interfaces 216corresponding to networking interfaces 217.Dv fxp0 218through 219.Dv fxp3 : 220.Bd -literal 221 # Plumb nodes together 222 223 ngctl mkpeer fxp0: one2many upper one 224 ngctl connect fxp0: fxp0:upper lower many0 225 ngctl connect fxp1: fxp0:upper lower many1 226 ngctl connect fxp2: fxp0:upper lower many2 227 ngctl connect fxp3: fxp0:upper lower many3 228 229 # Allow fxp1 through fxp3 to xmit/recv fxp0 frames 230 231 ngctl msg fxp1: setpromisc 1 232 ngctl msg fxp2: setpromisc 1 233 ngctl msg fxp3: setpromisc 1 234 ngctl msg fxp1: setautosrc 0 235 ngctl msg fxp2: setautosrc 0 236 ngctl msg fxp3: setautosrc 0 237 238 # Configure all four links as up 239 240 ngctl msg fxp0:upper \\ 241 setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }" 242 243 # Bring up interface 244 245 ifconfig fxp0 192.168.1.1 netmask 0xfffffffc 246.Ed 247.Pp 248With a similar setup on a peer machine (using the address 249192.168.1.2), a point-to-point 250Ethernet connection with four times normal bandwidth is 251achieved. 252.Sh SEE ALSO 253.Xr netgraph 4 , 254.Xr ng_bridge 4 , 255.Xr ng_ether 4 , 256.Xr ng_hub 4 , 257.Xr ifconfig 8 , 258.Xr ngctl 8 259.Sh HISTORY 260The 261.Nm 262node type was implemented in 263.Fx 4.2 . 264.Sh AUTHORS 265.An -nosplit 266The 267.Nm one2many 268netgraph node (with round-robin algorithm) was written by 269.An Archie Cobbs Aq Mt archie@FreeBSD.org . 270The all algorithm was added by 271.An Rogier R. Mulhuijzen Aq Mt drwilco@drwilco.net . 272.Sh BUGS 273More transmit and link failure algorithms should be supported. 274A good candidate is Cisco's Etherchannel. 275