.\"	$NetBSD: agr.4,v 1.9 2013/07/13 10:54:00 njoly Exp $
.\"
.\" Copyright (c)2005, 2007 YAMAMOTO Takashi,
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 February 23, 2010
.Dt AGR 4
.Os
.\" ------------------------------------------------------------
.Sh NAME
.Nm agr
.Nd link aggregation pseudo network interface driver
.\" ------------------------------------------------------------
.Sh SYNOPSIS
.Cd pseudo-device agr
.\" ------------------------------------------------------------
.Sh DESCRIPTION
The
.Nm
driver provides link aggregation functionality (a.k.a. L2 trunking
or bonding).
.Pp
It supports the IEEE 802.3ad Link Aggregation Control Protocol
(LACP) and the Marker Protocol.
.Pp
The
.Nm
driver supports the following link specific flags for
.Xr ifconfig 8 :
.Bl -tag -width "-link0"
.It Cm link0
Use the round-robin distribution algorithm.
Don't use it unless you're really sure,
because it violates the frame ordering rule.
.It Cm -link0
Use the default distribution algorithm, which is based on the hash
of DA/SA, TCI, and, if available, some upper layer protocol
information like
.Xr ip 4
DA/SA.
.It Cm link1
Disable LACP.
Prevents any LACP or Marker messaging which leaves
the ports in the default static configuration.
Set this prior to adding ports.
.El
.\" ------------------------------------------------------------
.Sh EXAMPLES
Create an
.Nm
interface,
.Sy agr0 ,
and attach
.Sy re0
and
.Sy re1
to it.
In other words, aggregate
.Sy re0
and
.Sy re1
so that they can be used as a single interface,
.Sy agr0 .
The physical interfaces which are attached to the
.Nm
interface must not have any IP addresses, neither IPv4 nor IPv6.
.Bd -literal -offset indent
	ifconfig re0 inet xxx.xxx.xxx.xxx delete
	ifconfig re0 inet6 fe80::xxxx:xxxx:xxxx:xxxx delete
	ifconfig re1 inet xxx.xxx.xxx.xxx delete
	ifconfig re1 inet6 fe80::xxxx:xxxx:xxxx:xxxx delete

	ifconfig agr0 create
	ifconfig agr0 agrport re0
	ifconfig agr0 agrport re1
.Ed
.Pp
Destroy an interface created in the above example.
.Bd -literal -offset indent
	ifconfig agr0 -agrport re0
	ifconfig agr0 -agrport re1
	ifconfig agr0 destroy
.Ed
.\" ------------------------------------------------------------
.Sh SEE ALSO
.Xr ifconfig 8
.\" ------------------------------------------------------------
.Sh STANDARDS
IEEE 802.3ad Aggregation of Multiple Link Segments
.\" ------------------------------------------------------------
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 4.0 .
.\" ------------------------------------------------------------
.Sh AUTHORS
The
.Nm
driver was written by
.An YAMAMOTO Takashi .
.\" ------------------------------------------------------------
.Sh BUGS
There is no way to configure LACP administrative variables, including
system and port priorities.
The current implementation of the
.Nm
driver always performs active-mode LACP and
uses 0x8000 as system and port priorities.
.Pp
The
.Nm
driver uses the MAC address of the first-added physical
interface as the MAC address of the
.Nm
interface itself.
Thus, removing the physical interface and using it for another purpose
can result in non-unique MAC addresses.
.Pp
The current implementation of the
.Nm
driver doesn't prevent unsafe operations like some ioctls against
underlying physical interfaces.
Such operations can result in unexpected behaviors, and are strongly
discouraged.
.Pp
There is no way to configure
.Nm
interfaces without attaching physical interfaces.
.Pp
Physical interfaces being added to the
.Nm
interface shouldn't have any addresses except for link level address.
Otherwise, the attempt will fail with
.Dv EBUSY .
Note that it includes an automatically assigned IPv6 link-local address.