share/man/man4/agr.4

   1 .\"     $NetBSD: agr.4,v 1.6 2009/06/07 23:06:48 darran 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 June 7, 2009
  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
  40 The
  41 .Nm
  42 driver provides link aggregation functionality (a.k.a. L2 trunking
  43 or bonding).
  44 .Pp
  45 It supports the IEEE 802.3ad Link Aggregation Control Protocol
  46 (LACP) and the Marker Protocol.
  47 .Pp
  48 The
  49 .Nm
  50 driver supports the following link specific flags for
  51 .Xr ifconfig 8 :
  52 .Bl -tag -width -link0
  53 .It Cm link0
  54 Use the round-robin distribution algorithm.
  55 Don't use it unless you're really sure,
  56 because it violates the frame ordering rule.
  57 .It Cm -link0
  58 Use the default distribution algorithm, which is based on the hash
  59 of DA/SA, TCI, and, if available, some upper layer protocol
  60 information like
  61 .Xr ip 4
  62 DA/SA.
  63 .It Cm link1
  64 Disable LACP.
  65 Prevents any LACP or Marker messaging which leaves
  66 the ports in the default static configuration.
  67 Set this prior to adding ports.
  68 .El
  69 .\" ------------------------------------------------------------
  70 .Sh EXAMPLES
  71 Create an
  72 .Nm
  73 interface,
  74 .Sy agr0 ,
  75 and attach
  76 .Sy re0
  77 and
  78 .Sy re1
  79 to it.
  80 (In other words, aggregate
  81 .Sy re0
  82 and
  83 .Sy re1
  84 so that they can be used as a single interface,
  85 .Sy agr0 )
  86 .Bd -literal -offset indent
  87         ifconfig agr0 create
  88         ifconfig agr0 agrport re0
  89         ifconfig agr0 agrport re1
  90 .Ed
  91 .Pp
  92 Destroy an interface created in the above example.
  93 .Bd -literal -offset indent
  94         ifconfig agr0 -agrport re0
  95         ifconfig agr0 -agrport re1
  96         ifconfig agr0 destroy
  97 .Ed
  98 .\" ------------------------------------------------------------
  99 .Sh SEE ALSO
 100 .Xr ifconfig 8
 101 .\" ------------------------------------------------------------
 102 .Sh STANDARDS
 103 IEEE 802.3ad Aggregation of Multiple Link Segments
 104 .\" ------------------------------------------------------------
 105 .Sh HISTORY
 106 The
 107 .Nm
 108 driver first appeared in
 109 .Nx 4.0 .
 110 .\" ------------------------------------------------------------
 111 .Sh AUTHORS
 112 The
 113 .Nm
 114 driver was written by
 115 .An YAMAMOTO Takashi .
 116 .\" ------------------------------------------------------------
 117 .Sh BUGS
 118 There is no way to configure LACP administrative variables, including
 119 system and port priorities.
 120 The current implementation of the
 121 .Nm
 122 driver always performs active-mode LACP and
 123 uses 0x8000 as system and port priorities.
 124 .Pp
 125 The
 126 .Nm
 127 driver uses the MAC address of the first-added physical
 128 interface as the MAC address of the
 129 .Nm
 130 interface itself.
 131 Thus, removing the physical interface and using it for another purpose
 132 can result in non-unique MAC addresses.
 133 .Pp
 134 The current implementation of the
 135 .Nm
 136 driver doesn't prevent unsafe operations like some ioctls against
 137 underlying physical interfaces.
 138 Such operations can result in unexpected behaviors, and are strongly
 139 discouraged.
 140 .Pp
 141 There is no way to configure
 142 .Nm
 143 interfaces without attaching physical interfaces.
 144 .Pp
 145 Physical interfaces being added to the
 146 .Nm
 147 interface shouldn't have any addresses except for link level address.
 148 Otherwise, the attempt will fail with
 149 .Dv EBUSY .
 150 Note that it includes an automatically assigned IPv6 link-local address.