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