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 16, 2023 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 46Each 47.Nm 48interface is created at runtime using interface cloning. 49This is 50most easily done with the 51.Xr ifconfig 8 52.Cm create 53command or using the 54.Va cloned_interfaces 55variable in 56.Xr rc.conf 5 . 57.Pp 58A 59.Nm 60interface can be created using the 61.Ic ifconfig lagg Ns Ar N Ic create 62command. 63It can use different link aggregation protocols specified 64using the 65.Ic laggproto Ar proto 66option. 67Child interfaces can be added using the 68.Ic laggport Ar child-iface 69option and removed using the 70.Ic -laggport Ar child-iface 71option. 72.Pp 73The driver currently supports the aggregation protocols 74.Ic failover 75(the default), 76.Ic lacp , 77.Ic loadbalance , 78.Ic roundrobin , 79.Ic broadcast , 80and 81.Ic none . 82The protocols determine which ports are used for outgoing traffic 83and whether a specific port accepts incoming traffic. 84The interface link state is used to validate if the port is active or 85not. 86.Bl -tag -width loadbalance 87.It Ic failover 88Sends traffic only through the active port. 89If the master port becomes unavailable, 90the next active port is used. 91The first interface added is the master port; 92any interfaces added after that are used as failover devices. 93.Pp 94By default, received traffic is only accepted when it is received 95through the active port. 96This constraint can be relaxed by setting the 97.Va net.link.lagg.failover_rx_all 98.Xr sysctl 8 99variable to a nonzero value, 100which is useful for certain bridged network setups. 101.It Ic lacp 102Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol 103(LACP) and the Marker Protocol. 104LACP will negotiate a set of aggregable links with the peer in to one or more 105Link Aggregated Groups. 106Each LAG is composed of ports of the same speed, set to full-duplex operation. 107The traffic will be balanced across the ports in the LAG with the greatest 108total speed, in most cases there will only be one LAG which contains all ports. 109In the event of changes in physical connectivity, Link Aggregation will quickly 110converge to a new configuration. 111.It Ic loadbalance 112Balances outgoing traffic across the active ports based on hashed 113protocol header information and accepts incoming traffic from 114any active port. 115This is a static setup and does not negotiate aggregation with the peer or 116exchange frames to monitor the link. 117The hash includes the Ethernet source and destination address, and, if 118available, the VLAN tag, and the IP source and destination address. 119.It Ic roundrobin 120Distributes outgoing traffic using a round-robin scheduler 121through all active ports and accepts incoming traffic from 122any active port. 123Using 124.Ic roundrobin 125mode can cause unordered packet arrival at the client. 126Throughput might be limited as the client performs CPU-intensive packet 127reordering. 128.It Ic broadcast 129Sends frames to all ports of the LAG and receives frames on 130any port of the LAG. 131.It Ic none 132This protocol is intended to do nothing: it disables any traffic without 133disabling the 134.Nm 135interface itself. 136.El 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.Pp 156When creating a 157.Nm 158interface, the 159.Ic laggtype 160can be specified as either 161.Cm ethernet 162or 163.Cm infiniband . 164If neither is specified then the default is 165.Cm ethernet . 166.Sh EXAMPLES 167Create a link aggregation using LACP with two 168.Xr bge 4 169Gigabit Ethernet interfaces: 170.Bd -literal -offset indent 171# ifconfig bge0 up 172# ifconfig bge1 up 173# ifconfig lagg0 create 174# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \e 175 192.168.1.1 netmask 255.255.255.0 176.Ed 177.Pp 178Create a link aggregation using ROUNDROBIN with two 179.Xr bge 4 180Gigabit Ethernet interfaces and set a stride of 500 packets 181per interface: 182.Bd -literal -offset indent 183# ifconfig bge0 up 184# ifconfig bge1 up 185# ifconfig lagg0 create 186# ifconfig lagg0 laggproto roundrobin laggport bge0 laggport bge1 \e 187 192.168.1.1 netmask 255.255.255.0 188# ifconfig lagg0 rr_limit 500 189.Ed 190.Pp 191The following example uses an active failover interface to set up roaming 192between wired and wireless networks using two network devices. 193Whenever the wired master interface is unplugged, the wireless failover 194device will be used: 195.Bd -literal -offset indent 196# ifconfig em0 ether 00:11:22:33:44:55 up 197# ifconfig wlan0 create wlandev ath0 ssid my_net up 198# ifconfig lagg0 create 199# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e 200 192.168.1.1 netmask 255.255.255.0 201.Ed 202.Pp 203(Note the MAC address of the wired device is forced to match that of the 204wireless device, 205.Sq 00:11:22:33:44:55 206in this example, as some common wireless devices will not allow MAC 207addresses to be changed.) 208.Pp 209The following example shows how to create an infiniband failover interface. 210.Bd -literal -offset indent 211# ifconfig ib0 up 212# ifconfig ib1 up 213# ifconfig lagg0 create laggtype infiniband 214# ifconfig lagg0 laggproto failover laggport ib0 laggport ib1 \e 215 1.1.1.1 netmask 255.255.255.0 216.Ed 217.Pp 218Configure two ethernets for failover with static IP in 219.Xr /etc/rc.conf 5 : 220.Bd -literal -offset indent 221cloned_interfaces="lagg0" 222ifconfig_lagg0="laggproto failover laggport bge0 laggport bge1 \e 223 10.1.29.21/24" 224ifconfig_bge0="up" 225ifconfig_bge1="up" 226.Ed 227.Sh SEE ALSO 228.Xr ng_one2many 4 , 229.Xr rc.conf 5 , 230.Xr ifconfig 8 , 231.Xr sysctl 8 232.Sh HISTORY 233The 234.Nm 235device first appeared in 236.Fx 6.3 . 237.Sh AUTHORS 238.An -nosplit 239The 240.Nm 241driver was written under the name 242.Nm trunk 243by 244.An Reyk Floeter Aq Mt reyk@openbsd.org . 245The LACP implementation was written by 246.An YAMAMOTO Takashi 247for 248.Nx . 249.Sh BUGS 250There is no way to configure LACP administrative variables, including system 251and port priorities. 252The current implementation always performs active-mode LACP and uses 0x8000 as 253system and port priorities. 254