.\"	$NetBSD: lagg.4,v 1.4 2022/05/24 20:50:18 andvar Exp $
.\"
.\" Copyright (c) 2005, 2006 Reyk Floeter <reyk@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
.\" Copyright (C) 2021 Internet Initiative Japan Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd April 2, 2020
.Dt LAGG 4
.Os
.Sh NAME
.Nm lagg
.Nd link aggregation and link failover interface
.Sh SYNOPSIS
.Cd "pseudo-device lagg"
.Sh DESCRIPTION
The
.Nm
interface allows aggregation of multiple network interfaces as one virtual
.Nm
interface for the purpose of providing fault-tolerance and high-speed links.
.Pp
A
.Nm
interface can be created using the
.Ic ifconfig lagg Ns Ar N Ic create
command.
It can use different link aggregation protocols specified
using the
.Ic laggproto Ar proto
option.
Child interfaces can be added using the
.Ic laggport Ar child-iface
option and removed using the
.Ic -laggport Ar child-iface
option.
A priority of each child interface can be configured using the
.Ic laggport Ar child-iface pri Ar N
or
.Ic laggportpri Ar child-iface Ar N
option.
The interface preferentially uses the child interface that is
the smallest numeric in the priority.
.Pp
The driver currently supports the aggregation protocols
.Ic failover ,
.Ic loadbalance ,
.Ic lacp ,
and
.Ic none
(the default).
The protocols determine which ports are used for outgoing traffic
and whether a specific port accepts incoming traffic.
The interface link state is used to validate if the port is active or
not.
.Bl -tag -width loadbalance
.It Ic failover
Sends traffic only through the active port that is the highest priority.
When the same priority is configured,
The first interface added is used for sending traffic.
If the link-state of the sending port becomes down,
The next priority port is used.
.Pp
Received traffic is accepted through all active port
if
.Ic laggfailover Nm rx-all
option is enabled.
The option is enabled by default, and it can be
disabled by
.Ic laggfailover Nm -rx-all
option.
If the option is disabled, received traffic is only accepted
through the sending port.
.It Ic loadbalance
Balances outgoing traffic across the active ports based on hashed
protocol header information and accepts incoming traffic from
any active port.
This is a static setup and does not negotiate aggregation with the peer or
exchange frames to monitor the link.
The hash includes the Ethernet source and destination address, and, if
available, the VLAN tag, and the IP source and destination address.
.It Ic lacp
Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol
(LACP) and the Marker Protocol.
LACP will negotiate a set of aggregable links wit the peer in to a Link
Aggregated Group.
The LAG is composed of ports of the different speed, set to full-duplex operation,
if
.Ic lagglacp Nm multi-speed
option is configured.
The function can be disabled by
.Ic lagglacp Nm \-multi-speed
option.
Outgoing traffic across the distributing ports based on hashed
protocol header information and accepts incoming traffic from
any collecting port.
The maximum number of active ports in a LAG can be configured by
.Ic lagglacp Nm maxports Ar N
option.
.It Ic none
This protocol is intended to do nothing: it disables any traffic without
disabling the
.Nm
interface itself.
.El
.Pp
Each
.Nm
interface is created at runtime using interface cloning.
This is
most easily done with the
.Xr ifconfig 8
.Cm create
command.
.Pp
The MTU of the first interface to be added is used as the lagg MTU.
All additional interfaces are required to have exactly the same value.
.Sh EXAMPLES
Create a link aggregation using LACP with two
.Xr wm 4
Gigabit Ethernet interfaces:
.Bd -literal -offset indent
# ifconfig wm0 up
# ifconfig wm1 up
# ifconfig lagg0 create
# ifconfig lagg0 laggproto lacp laggport wm0 laggport wm1 \e
	192.168.1.1 netmask 255.255.255.0
.Ed
.Pp
Create a link aggregation using FAILOVER with two
.Xr wm 4
Gigabit Ethernet interfaces and set each priority:
.Bd -literal -offset indent
# ifconfig wm0 up
# ifconfig wm1 up
# ifconfig lagg0 create
# ifconfig lagg0 laggproto failover \e
	laggport wm0 pri 1000 laggport wm1 pri 2000 \e
	192.168.1.1 netmask 255.255.255.0
.Ed
.Sh SEE ALSO
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
device first appeared in
.Nx 10.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written under the name
.Nm trunk
by
.An Reyk Floeter Aq Mt reyk@openbsd.org .
.Sh BUGS
There is no way to configure LACP administrative variables, including system
priority.
The current implementation always performs active-mode LACP and uses 0x8000 as
system priority.