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 October 1, 2014 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. 113.It Ic broadcast 114Sends frames to all ports of the LAG and receives frames on 115any port of the LAG. 116.It Ic none 117This protocol is intended to do nothing: it disables any traffic without 118disabling the 119.Nm 120interface itself. 121.El 122.Pp 123Each 124.Nm 125interface is created at runtime using interface cloning. 126This is 127most easily done with the 128.Xr ifconfig 8 129.Cm create 130command or using the 131.Va cloned_interfaces 132variable in 133.Xr rc.conf 5 . 134.Pp 135The MTU of the first interface to be added is used as the lagg MTU. 136All additional interfaces are required to have exactly the same value. 137.Pp 138The 139.Ic loadbalance 140and 141.Ic lacp 142modes will use the RSS hash from the network card if available to avoid 143computing one, this may give poor traffic distribution if the hash is invalid 144or uses less of the protocol header information. 145Local hash computation can be forced per interface by setting the 146.Cm use_flowid 147.Xr ifconfig 8 148flag. 149The default for new interfaces is set via the 150.Va net.link.lagg.default_use_flowid 151.Xr sysctl 8 . 152.Sh EXAMPLES 153Create a link aggregation using LACP with two 154.Xr bge 4 155Gigabit Ethernet interfaces: 156.Bd -literal -offset indent 157# ifconfig bge0 up 158# ifconfig bge1 up 159# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \e 160 192.168.1.1 netmask 255.255.255.0 161.Ed 162.Pp 163The following example uses an active failover interface to set up roaming 164between wired and wireless networks using two network devices. 165Whenever the wired master interface is unplugged, the wireless failover 166device will be used: 167.Bd -literal -offset indent 168# ifconfig em0 up 169# ifconfig ath0 ether 00:11:22:33:44:55 170# ifconfig create wlan0 wlandev ath0 ssid my_net up 171# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e 172 192.168.1.1 netmask 255.255.255.0 173.Ed 174.Pp 175(Note the mac address of the wireless device is forced to match the wired 176device as a workaround.) 177.Sh SEE ALSO 178.Xr ng_one2many 4 , 179.Xr ifconfig 8 , 180.Xr sysctl 8 181.Sh HISTORY 182The 183.Nm 184device first appeared in 185.Fx 6.3 . 186.Sh AUTHORS 187.An -nosplit 188The 189.Nm 190driver was written under the name 191.Nm trunk 192by 193.An Reyk Floeter Aq Mt reyk@openbsd.org . 194The LACP implementation was written by 195.An YAMAMOTO Takashi 196for 197.Nx . 198.Sh BUGS 199There is no way to configure LACP administrative variables, including system 200and port priorities. 201The current implementation always performs active-mode LACP and uses 0x8000 as 202system and port priorities. 203