xref: /netbsd/share/man/man4/agr.4 (revision 6550d01e) 
1.\"	$NetBSD: agr.4,v 1.8 2010/02/23 07:02:23 martti Exp $
2.\"
3.\" Copyright (c)2005, 2007 YAMAMOTO Takashi,
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" ------------------------------------------------------------
28.Dd February 23, 2010
29.Dt AGR 4
30.Os
31.\" ------------------------------------------------------------
32.Sh NAME
33.Nm agr
34.Nd link aggregation pseudo network interface driver
35.\" ------------------------------------------------------------
36.Sh SYNOPSIS
37.Cd pseudo-device agr
38.\" ------------------------------------------------------------
39.Sh DESCRIPTION
40The
41.Nm
42driver provides link aggregation functionality (a.k.a. L2 trunking
43or bonding).
44.Pp
45It supports the IEEE 802.3ad Link Aggregation Control Protocol
46(LACP) and the Marker Protocol.
47.Pp
48The
49.Nm
50driver supports the following link specific flags for
51.Xr ifconfig 8 :
52.Bl -tag -width -link0
53.It Cm link0
54Use the round-robin distribution algorithm.
55Don't use it unless you're really sure,
56because it violates the frame ordering rule.
57.It Cm -link0
58Use the default distribution algorithm, which is based on the hash
59of DA/SA, TCI, and, if available, some upper layer protocol
60information like
61.Xr ip 4
62DA/SA.
63.It Cm link1
64Disable LACP.
65Prevents any LACP or Marker messaging which leaves
66the ports in the default static configuration.
67Set this prior to adding ports.
68.El
69.\" ------------------------------------------------------------
70.Sh EXAMPLES
71Create an
72.Nm
73interface,
74.Sy agr0 ,
75and attach
76.Sy re0
77and
78.Sy re1
79to it.
80In other words, aggregate
81.Sy re0
82and
83.Sy re1
84so that they can be used as a single interface,
85.Sy agr0 .
86The physical interfaces which are attached to the
87.Nm
88interface must not have any IP addresses, neither IPv4 nor IPv6.
89.Bd -literal -offset indent
90	ifconfig re0 inet xxx.xxx.xxx.xxx delete
91	ifconfig re0 inet6 fe80::xxxx:xxxx:xxxx:xxxx delete
92	ifconfig re1 inet xxx.xxx.xxx.xxx delete
93	ifconfig re1 inet6 fe80::xxxx:xxxx:xxxx:xxxx delete
94
95	ifconfig agr0 create
96	ifconfig agr0 agrport re0
97	ifconfig agr0 agrport re1
98.Ed
99.Pp
100Destroy an interface created in the above example.
101.Bd -literal -offset indent
102	ifconfig agr0 -agrport re0
103	ifconfig agr0 -agrport re1
104	ifconfig agr0 destroy
105.Ed
106.\" ------------------------------------------------------------
107.Sh SEE ALSO
108.Xr ifconfig 8
109.\" ------------------------------------------------------------
110.Sh STANDARDS
111IEEE 802.3ad Aggregation of Multiple Link Segments
112.\" ------------------------------------------------------------
113.Sh HISTORY
114The
115.Nm
116driver first appeared in
117.Nx 4.0 .
118.\" ------------------------------------------------------------
119.Sh AUTHORS
120The
121.Nm
122driver was written by
123.An YAMAMOTO Takashi .
124.\" ------------------------------------------------------------
125.Sh BUGS
126There is no way to configure LACP administrative variables, including
127system and port priorities.
128The current implementation of the
129.Nm
130driver always performs active-mode LACP and
131uses 0x8000 as system and port priorities.
132.Pp
133The
134.Nm
135driver uses the MAC address of the first-added physical
136interface as the MAC address of the
137.Nm
138interface itself.
139Thus, removing the physical interface and using it for another purpose
140can result in non-unique MAC addresses.
141.Pp
142The current implementation of the
143.Nm
144driver doesn't prevent unsafe operations like some ioctls against
145underlying physical interfaces.
146Such operations can result in unexpected behaviors, and are strongly
147discouraged.
148.Pp
149There is no way to configure
150.Nm
151interfaces without attaching physical interfaces.
152.Pp
153Physical interfaces being added to the
154.Nm
155interface shouldn't have any addresses except for link level address.
156Otherwise, the attempt will fail with
157.Dv EBUSY .
158Note that it includes an automatically assigned IPv6 link-local address.
159