1.\" $NetBSD: lagg.4,v 1.4 2022/05/24 20:50:18 andvar 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.\" 18.\" Copyright (C) 2021 Internet Initiative Japan Inc. 19.\" All rights reserved. 20.\" 21.\" Redistribution and use in source and binary forms, with or without 22.\" modification, are permitted provided that the following conditions 23.\" are met: 24.\" 1. Redistributions of source code must retain the above copyright 25.\" notice, this list of conditions and the following disclaimer. 26.\" 2. Redistributions in binary form must reproduce the above copyright 27.\" notice, this list of conditions and the following disclaimer in the 28.\" documentation and/or other materials provided with the distribution. 29.\" 3. Neither the name of the project nor the names of its contributors 30.\" may be used to endorse or promote products derived from this software 31.\" without specific prior written permission. 32.\" 33.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 34.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 35.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 36.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 37.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 38.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 39.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 40.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 41.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 42.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 43.\" SUCH DAMAGE. 44.\" 45.Dd April 2, 2020 46.Dt LAGG 4 47.Os 48.Sh NAME 49.Nm lagg 50.Nd link aggregation and link failover interface 51.Sh SYNOPSIS 52.Cd "pseudo-device lagg" 53.Sh DESCRIPTION 54The 55.Nm 56interface allows aggregation of multiple network interfaces as one virtual 57.Nm 58interface for the purpose of providing fault-tolerance and high-speed links. 59.Pp 60A 61.Nm 62interface can be created using the 63.Ic ifconfig lagg Ns Ar N Ic create 64command. 65It can use different link aggregation protocols specified 66using the 67.Ic laggproto Ar proto 68option. 69Child interfaces can be added using the 70.Ic laggport Ar child-iface 71option and removed using the 72.Ic -laggport Ar child-iface 73option. 74A priority of each child interface can be configured using the 75.Ic laggport Ar child-iface pri Ar N 76or 77.Ic laggportpri Ar child-iface Ar N 78option. 79The interface preferentially uses the child interface that is 80the smallest numeric in the priority. 81.Pp 82The driver currently supports the aggregation protocols 83.Ic failover , 84.Ic loadbalance , 85.Ic lacp , 86and 87.Ic none 88(the default). 89The protocols determine which ports are used for outgoing traffic 90and whether a specific port accepts incoming traffic. 91The interface link state is used to validate if the port is active or 92not. 93.Bl -tag -width loadbalance 94.It Ic failover 95Sends traffic only through the active port that is the highest priority. 96When the same priority is configured, 97The first interface added is used for sending traffic. 98If the link-state of the sending port becomes down, 99The next priority port is used. 100.Pp 101Received traffic is accepted through all active port 102if 103.Ic laggfailover Nm rx-all 104option is enabled. 105The option is enabled by default, and it can be 106disabled by 107.Ic laggfailover Nm -rx-all 108option. 109If the option is disabled, received traffic is only accepted 110through the sending port. 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 lacp 120Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol 121(LACP) and the Marker Protocol. 122LACP will negotiate a set of aggregable links wit the peer in to a Link 123Aggregated Group. 124The LAG is composed of ports of the different speed, set to full-duplex operation, 125if 126.Ic lagglacp Nm multi-speed 127option is configured. 128The function can be disabled by 129.Ic lagglacp Nm \-multi-speed 130option. 131Outgoing traffic across the distributing ports based on hashed 132protocol header information and accepts incoming traffic from 133any collecting port. 134The maximum number of active ports in a LAG can be configured by 135.Ic lagglacp Nm maxports Ar N 136option. 137.It Ic none 138This protocol is intended to do nothing: it disables any traffic without 139disabling the 140.Nm 141interface itself. 142.El 143.Pp 144Each 145.Nm 146interface is created at runtime using interface cloning. 147This is 148most easily done with the 149.Xr ifconfig 8 150.Cm create 151command. 152.Pp 153The MTU of the first interface to be added is used as the lagg MTU. 154All additional interfaces are required to have exactly the same value. 155.Sh EXAMPLES 156Create a link aggregation using LACP with two 157.Xr wm 4 158Gigabit Ethernet interfaces: 159.Bd -literal -offset indent 160# ifconfig wm0 up 161# ifconfig wm1 up 162# ifconfig lagg0 create 163# ifconfig lagg0 laggproto lacp laggport wm0 laggport wm1 \e 164 192.168.1.1 netmask 255.255.255.0 165.Ed 166.Pp 167Create a link aggregation using FAILOVER with two 168.Xr wm 4 169Gigabit Ethernet interfaces and set each priority: 170.Bd -literal -offset indent 171# ifconfig wm0 up 172# ifconfig wm1 up 173# ifconfig lagg0 create 174# ifconfig lagg0 laggproto failover \e 175 laggport wm0 pri 1000 laggport wm1 pri 2000 \e 176 192.168.1.1 netmask 255.255.255.0 177.Ed 178.Sh SEE ALSO 179.Xr ifconfig 8 180.Sh HISTORY 181The 182.Nm 183device first appeared in 184.Nx 10.0 . 185.Sh AUTHORS 186.An -nosplit 187The 188.Nm 189driver was written under the name 190.Nm trunk 191by 192.An Reyk Floeter Aq Mt reyk@openbsd.org . 193.Sh BUGS 194There is no way to configure LACP administrative variables, including system 195priority. 196The current implementation always performs active-mode LACP and uses 0x8000 as 197system priority. 198