1.\" $OpenBSD: trunk.4,v 1.18 2006/06/09 13:53:34 jmc Exp $ 2.\" 3.\" Copyright (c) 2005, 2006 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" $FreeBSD$ 18.\" 19.Dd January 23, 2016 20.Dt LAGG 4 21.Os 22.Sh NAME 23.Nm lagg 24.Nd link aggregation and link failover interface 25.Sh SYNOPSIS 26To compile this driver into the kernel, 27place the following line in your 28kernel configuration file: 29.Bd -ragged -offset indent 30.Cd "device lagg" 31.Ed 32.Pp 33Alternatively, to load the driver as a 34module at boot time, place the following line in 35.Xr loader.conf 5 : 36.Bd -literal -offset indent 37if_lagg_load="YES" 38.Ed 39.Sh DESCRIPTION 40The 41.Nm 42interface allows aggregation of multiple network interfaces as one virtual 43.Nm 44interface for the purpose of providing fault-tolerance and high-speed links. 45.Pp 46A 47.Nm 48interface can be created using the 49.Ic ifconfig lagg Ns Ar N Ic create 50command. 51It can use different link aggregation protocols specified 52using the 53.Ic laggproto Ar proto 54option. 55Child interfaces can be added using the 56.Ic laggport Ar child-iface 57option and removed using the 58.Ic -laggport Ar child-iface 59option. 60.Pp 61The driver currently supports the aggregation protocols 62.Ic failover 63(the default), 64.Ic lacp , 65.Ic loadbalance , 66.Ic roundrobin , 67.Ic broadcast , 68and 69.Ic none . 70The protocols determine which ports are used for outgoing traffic 71and whether a specific port accepts incoming traffic. 72The interface link state is used to validate if the port is active or 73not. 74.Bl -tag -width loadbalance 75.It Ic failover 76Sends traffic only through the active port. 77If the master port becomes unavailable, 78the next active port is used. 79The first interface added is the master port; 80any interfaces added after that are used as failover devices. 81.Pp 82By default, received traffic is only accepted when they are received 83through the active port. 84This constraint can be relaxed by setting the 85.Va net.link.lagg.failover_rx_all 86.Xr sysctl 8 87variable to a nonzero value, 88which is useful for certain bridged network setups. 89.Ic loadbalance 90mode. 91.It Ic lacp 92Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol 93(LACP) and the Marker Protocol. 94LACP will negotiate a set of aggregable links with the peer in to one or more 95Link Aggregated Groups. 96Each LAG is composed of ports of the same speed, set to full-duplex operation. 97The traffic will be balanced across the ports in the LAG with the greatest 98total speed, in most cases there will only be one LAG which contains all ports. 99In the event of changes in physical connectivity, Link Aggregation will quickly 100converge to a new configuration. 101.It Ic loadbalance 102Balances outgoing traffic across the active ports based on hashed 103protocol header information and accepts incoming traffic from 104any active port. 105This is a static setup and does not negotiate aggregation with the peer or 106exchange frames to monitor the link. 107The hash includes the Ethernet source and destination address, and, if 108available, the VLAN tag, and the IP source and destination address. 109.It Ic roundrobin 110Distributes outgoing traffic using a round-robin scheduler 111through all active ports and accepts incoming traffic from 112any active port. 113Using 114.Ic roundrobin 115mode can cause unordered packet arrival at the client. 116Throughput might be limited as the client performs CPU-intensive packet 117reordering. 118.It Ic broadcast 119Sends frames to all ports of the LAG and receives frames on 120any port of the LAG. 121.It Ic none 122This protocol is intended to do nothing: it disables any traffic without 123disabling the 124.Nm 125interface itself. 126.El 127.Pp 128Each 129.Nm 130interface is created at runtime using interface cloning. 131This is 132most easily done with the 133.Xr ifconfig 8 134.Cm create 135command or using the 136.Va cloned_interfaces 137variable in 138.Xr rc.conf 5 . 139.Pp 140The MTU of the first interface to be added is used as the lagg MTU. 141All additional interfaces are required to have exactly the same value. 142.Pp 143The 144.Ic loadbalance 145and 146.Ic lacp 147modes will use the RSS hash from the network card if available to avoid 148computing one, this may give poor traffic distribution if the hash is invalid 149or uses less of the protocol header information. 150Local hash computation can be forced per interface by setting the 151.Cm use_flowid 152.Xr ifconfig 8 153flag. 154The default for new interfaces is set via the 155.Va net.link.lagg.default_use_flowid 156.Xr sysctl 8 . 157.Sh EXAMPLES 158Create a link aggregation using LACP with two 159.Xr bge 4 160Gigabit Ethernet interfaces: 161.Bd -literal -offset indent 162# ifconfig bge0 up 163# ifconfig bge1 up 164# ifconfig lagg0 create 165# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \e 166 192.168.1.1 netmask 255.255.255.0 167.Ed 168.Pp 169Create a link aggregation using ROUNDROBIN with two 170.Xr bge 4 171Gigabit Ethernet interfaces and set the limit of 500 packets 172per interface: 173.Bd -literal -offset indent 174# ifconfig bge0 up 175# ifconfig bge1 up 176# ifconfig lagg0 create 177# ifconfig lagg0 laggproto roundrobin laggport bge0 laggport bge1 \e 178 192.168.1.1 netmask 255.255.255.0 179# ifconfig lagg0 rr_limit 500 180.Ed 181.Pp 182The following example uses an active failover interface to set up roaming 183between wired and wireless networks using two network devices. 184Whenever the wired master interface is unplugged, the wireless failover 185device will be used: 186.Bd -literal -offset indent 187# ifconfig em0 up 188# ifconfig ath0 ether 00:11:22:33:44:55 189# ifconfig create wlan0 wlandev ath0 ssid my_net up 190# ifconfig lagg0 create 191# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e 192 192.168.1.1 netmask 255.255.255.0 193.Ed 194.Pp 195(Note the mac address of the wireless device is forced to match the wired 196device as a workaround.) 197.Sh SEE ALSO 198.Xr ng_one2many 4 , 199.Xr ifconfig 8 , 200.Xr sysctl 8 201.Sh HISTORY 202The 203.Nm 204device first appeared in 205.Fx 6.3 . 206.Sh AUTHORS 207.An -nosplit 208The 209.Nm 210driver was written under the name 211.Nm trunk 212by 213.An Reyk Floeter Aq Mt reyk@openbsd.org . 214The LACP implementation was written by 215.An YAMAMOTO Takashi 216for 217.Nx . 218.Sh BUGS 219There is no way to configure LACP administrative variables, including system 220and port priorities. 221The current implementation always performs active-mode LACP and uses 0x8000 as 222system and port priorities. 223