[src/uebayasi-xip]: src/share/man/man4 Note that the physical interfaces must...

[martti <martti%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/64f76b0e14fb
branches:  uebayasi-xip
changeset: 751587:64f76b0e14fb
user:      martti <martti%NetBSD.org@localhost>
date:      Tue Feb 23 07:02:24 2010 +0000

description:
Note that the physical interfaces must not have any (IPv4 or IPv6) address
before attaching them to agr.

diffstat:

 share/man/man4/agr.4 |  158 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 158 insertions(+), 0 deletions(-)

diffs (162 lines):

diff -r 2b24f127f056 -r 64f76b0e14fb share/man/man4/agr.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/agr.4      Tue Feb 23 07:02:24 2010 +0000
@@ -0,0 +1,158 @@
+.\"    $NetBSD: agr.4,v 1.8.2.2 2010/02/23 07:02:24 martti 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.