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 21, 2020 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.It Ic lacp 90Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol 91(LACP) and the Marker Protocol. 92LACP will negotiate a set of aggregable links with the peer in to one or more 93Link Aggregated Groups. 94Each LAG is composed of ports of the same speed, set to full-duplex operation. 95The traffic will be balanced across the ports in the LAG with the greatest 96total speed, in most cases there will only be one LAG which contains all ports. 97In the event of changes in physical connectivity, Link Aggregation will quickly 98converge to a new configuration. 99.It Ic loadbalance 100Balances outgoing traffic across the active ports based on hashed 101protocol header information and accepts incoming traffic from 102any active port. 103This is a static setup and does not negotiate aggregation with the peer or 104exchange frames to monitor the link. 105The hash includes the Ethernet source and destination address, and, if 106available, the VLAN tag, and the IP source and destination address. 107.It Ic roundrobin 108Distributes outgoing traffic using a round-robin scheduler 109through all active ports and accepts incoming traffic from 110any active port. 111Using 112.Ic roundrobin 113mode can cause unordered packet arrival at the client. 114Throughput might be limited as the client performs CPU-intensive packet 115reordering. 116.It Ic broadcast 117Sends frames to all ports of the LAG and receives frames on 118any port of the LAG. 119.It Ic none 120This protocol is intended to do nothing: it disables any traffic without 121disabling the 122.Nm 123interface itself. 124.El 125.Pp 126Each 127.Nm 128interface is created at runtime using interface cloning. 129This is 130most easily done with the 131.Xr ifconfig 8 132.Cm create 133command or using the 134.Va cloned_interfaces 135variable in 136.Xr rc.conf 5 . 137.Pp 138The MTU of the first interface to be added is used as the lagg MTU. 139All additional interfaces are required to have exactly the same value. 140.Pp 141The 142.Ic loadbalance 143and 144.Ic lacp 145modes will use the RSS hash from the network card if available to avoid 146computing one, this may give poor traffic distribution if the hash is invalid 147or uses less of the protocol header information. 148Local hash computation can be forced per interface by setting the 149.Cm -use_flowid 150.Xr ifconfig 8 151flag. 152The default for new interfaces is set via the 153.Va net.link.lagg.default_use_flowid 154.Xr sysctl 8 . 155.Sh EXAMPLES 156Create a link aggregation using LACP with two 157.Xr bge 4 158Gigabit Ethernet interfaces: 159.Bd -literal -offset indent 160# ifconfig bge0 up 161# ifconfig bge1 up 162# ifconfig lagg0 create 163# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \e 164 192.168.1.1 netmask 255.255.255.0 165.Ed 166.Pp 167Create a link aggregation using ROUNDROBIN with two 168.Xr bge 4 169Gigabit Ethernet interfaces and set a stride of 500 packets 170per interface: 171.Bd -literal -offset indent 172# ifconfig bge0 up 173# ifconfig bge1 up 174# ifconfig lagg0 create 175# ifconfig lagg0 laggproto roundrobin laggport bge0 laggport bge1 \e 176 192.168.1.1 netmask 255.255.255.0 177# ifconfig lagg0 rr_limit 500 178.Ed 179.Pp 180The following example uses an active failover interface to set up roaming 181between wired and wireless networks using two network devices. 182Whenever the wired master interface is unplugged, the wireless failover 183device will be used: 184.Bd -literal -offset indent 185# ifconfig em0 up 186# ifconfig ath0 ether 00:11:22:33:44:55 187# ifconfig create wlan0 wlandev ath0 ssid my_net up 188# ifconfig lagg0 create 189# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e 190 192.168.1.1 netmask 255.255.255.0 191.Ed 192.Pp 193(Note the mac address of the wireless device is forced to match the wired 194device as a workaround.) 195.Pp 196The following example shows how to create an infiniband failover interface. 197.Bd -literal -offset indent 198# ifconfig ib0 up 199# ifconfig ib1 up 200# ifconfig lagg0 create laggtype infiniband 201# ifconfig lagg0 laggproto failover laggport ib0 laggport ib1 \e 202 1.1.1.1 netmask 255.255.255.0 203.Ed 204.Sh SEE ALSO 205.Xr ng_one2many 4 , 206.Xr ifconfig 8 , 207.Xr sysctl 8 208.Sh HISTORY 209The 210.Nm 211device first appeared in 212.Fx 6.3 . 213.Sh AUTHORS 214.An -nosplit 215The 216.Nm 217driver was written under the name 218.Nm trunk 219by 220.An Reyk Floeter Aq Mt reyk@openbsd.org . 221The LACP implementation was written by 222.An YAMAMOTO Takashi 223for 224.Nx . 225.Sh BUGS 226There is no way to configure LACP administrative variables, including system 227and port priorities. 228The current implementation always performs active-mode LACP and uses 0x8000 as 229system and port priorities. 230