Changeset View
Changeset View
Standalone View
Standalone View
share/man/man4/lagg.4
Show All 10 Lines | |||||
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||||
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||||
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||||
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd October 21, 2020 | .Dd January 16, 2023 | ||||
.Dt LAGG 4 | .Dt LAGG 4 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm lagg | .Nm lagg | ||||
.Nd link aggregation and link failover interface | .Nd link aggregation and link failover interface | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
To compile this driver into the kernel, | To compile this driver into the kernel, | ||||
place the following line in your | place the following line in your | ||||
Show All 10 Lines | |||||
.Ed | .Ed | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm | .Nm | ||||
interface allows aggregation of multiple network interfaces as one virtual | interface allows aggregation of multiple network interfaces as one virtual | ||||
.Nm | .Nm | ||||
interface for the purpose of providing fault-tolerance and high-speed links. | interface for the purpose of providing fault-tolerance and high-speed links. | ||||
.Pp | .Pp | ||||
Each | |||||
.Nm | |||||
interface is created at runtime using interface cloning. | |||||
This is | |||||
most easily done with the | |||||
.Xr ifconfig 8 | |||||
.Cm create | |||||
command or using the | |||||
.Va cloned_interfaces | |||||
variable in | |||||
.Xr rc.conf 5 . | |||||
.Pp | |||||
A | A | ||||
.Nm | .Nm | ||||
interface can be created using the | interface can be created using the | ||||
.Ic ifconfig lagg Ns Ar N Ic create | .Ic ifconfig lagg Ns Ar N Ic create | ||||
command. | command. | ||||
It can use different link aggregation protocols specified | It can use different link aggregation protocols specified | ||||
using the | using the | ||||
.Ic laggproto Ar proto | .Ic laggproto Ar proto | ||||
Show All 20 Lines | |||||
.Bl -tag -width loadbalance | .Bl -tag -width loadbalance | ||||
.It Ic failover | .It Ic failover | ||||
Sends traffic only through the active port. | Sends traffic only through the active port. | ||||
If the master port becomes unavailable, | If the master port becomes unavailable, | ||||
the next active port is used. | the next active port is used. | ||||
The first interface added is the master port; | The first interface added is the master port; | ||||
any interfaces added after that are used as failover devices. | any interfaces added after that are used as failover devices. | ||||
.Pp | .Pp | ||||
By default, received traffic is only accepted when they are received | By default, received traffic is only accepted when it is received | ||||
through the active port. | through the active port. | ||||
This constraint can be relaxed by setting the | This constraint can be relaxed by setting the | ||||
.Va net.link.lagg.failover_rx_all | .Va net.link.lagg.failover_rx_all | ||||
.Xr sysctl 8 | .Xr sysctl 8 | ||||
variable to a nonzero value, | variable to a nonzero value, | ||||
which is useful for certain bridged network setups. | which is useful for certain bridged network setups. | ||||
.It Ic lacp | .It Ic lacp | ||||
Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol | Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol | ||||
Show All 27 Lines | |||||
any port of the LAG. | any port of the LAG. | ||||
.It Ic none | .It Ic none | ||||
This protocol is intended to do nothing: it disables any traffic without | This protocol is intended to do nothing: it disables any traffic without | ||||
disabling the | disabling the | ||||
.Nm | .Nm | ||||
interface itself. | interface itself. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
Each | |||||
.Nm | |||||
interface is created at runtime using interface cloning. | |||||
This is | |||||
most easily done with the | |||||
.Xr ifconfig 8 | |||||
.Cm create | |||||
command or using the | |||||
.Va cloned_interfaces | |||||
variable in | |||||
.Xr rc.conf 5 . | |||||
.Pp | |||||
The MTU of the first interface to be added is used as the lagg MTU. | 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. | All additional interfaces are required to have exactly the same value. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Ic loadbalance | .Ic loadbalance | ||||
and | and | ||||
.Ic lacp | .Ic lacp | ||||
modes will use the RSS hash from the network card if available to avoid | modes will use the RSS hash from the network card if available to avoid | ||||
computing one, this may give poor traffic distribution if the hash is invalid | computing one, this may give poor traffic distribution if the hash is invalid | ||||
or uses less of the protocol header information. | or uses less of the protocol header information. | ||||
Local hash computation can be forced per interface by setting the | Local hash computation can be forced per interface by setting the | ||||
.Cm -use_flowid | .Cm -use_flowid | ||||
.Xr ifconfig 8 | .Xr ifconfig 8 | ||||
flag. | flag. | ||||
The default for new interfaces is set via the | The default for new interfaces is set via the | ||||
.Va net.link.lagg.default_use_flowid | .Va net.link.lagg.default_use_flowid | ||||
.Xr sysctl 8 . | .Xr sysctl 8 . | ||||
.Pp | |||||
When creating a | |||||
.Nm | |||||
interface, the | |||||
.Ic laggtype | |||||
can be specified as either | |||||
.Cm ethernet | |||||
or | |||||
.Cm infiniband . | |||||
If neither is specified then the default is | |||||
.Cm ethernet . | |||||
.Sh EXAMPLES | .Sh EXAMPLES | ||||
Create a link aggregation using LACP with two | Create a link aggregation using LACP with two | ||||
.Xr bge 4 | .Xr bge 4 | ||||
Gigabit Ethernet interfaces: | Gigabit Ethernet interfaces: | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
# ifconfig bge0 up | # ifconfig bge0 up | ||||
# ifconfig bge1 up | # ifconfig bge1 up | ||||
# ifconfig lagg0 create | # ifconfig lagg0 create | ||||
Show All 14 Lines | |||||
# ifconfig lagg0 rr_limit 500 | # ifconfig lagg0 rr_limit 500 | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
The following example uses an active failover interface to set up roaming | The following example uses an active failover interface to set up roaming | ||||
between wired and wireless networks using two network devices. | between wired and wireless networks using two network devices. | ||||
Whenever the wired master interface is unplugged, the wireless failover | Whenever the wired master interface is unplugged, the wireless failover | ||||
device will be used: | device will be used: | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
# ifconfig em0 up | # ifconfig em0 ether 00:11:22:33:44:55 up | ||||
# ifconfig ath0 ether 00:11:22:33:44:55 | # ifconfig wlan0 create wlandev ath0 ssid my_net up | ||||
rgrimes: I would move the "up" to the line setting the ethernet MAC, just slightly cleaner to have the… | |||||
Done Inline ActionsI wouldn't, because (as I mentioned below) wlan0's MAC address needs to be left unchanged and em0's needs to be adjused instead. The other way stopped working with 11.x, IIRC. pauamma_gundo.com: I wouldn't, because (as I mentioned below) wlan0's MAC address needs to be left unchanged and… | |||||
# ifconfig create wlan0 wlandev ath0 ssid my_net up | |||||
# ifconfig lagg0 create | # ifconfig lagg0 create | ||||
Done Inline ActionsBecause some WiFi interfaces won't allow setting the MAC address, the recommended procedure is now to set the Ethernet interface's address to the WiFi's. See example 3 in https://docs.freebsd.org/en/books/handbook/advanced-networking/#network-aggregation. pauamma_gundo.com: Because some WiFi interfaces won't allow setting the MAC address, the recommended procedure is… | |||||
# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e | # ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e | ||||
192.168.1.1 netmask 255.255.255.0 | 192.168.1.1 netmask 255.255.255.0 | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
(Note the mac address of the wireless device is forced to match the wired | (Note the MAC address of the wired device is forced to match that of the | ||||
device as a workaround.) | wireless device, | ||||
.Sq 00:11:22:33:44:55 | |||||
in this example, as some common wireless devices will not allow MAC | |||||
addresses to be changed.) | |||||
.Pp | .Pp | ||||
The following example shows how to create an infiniband failover interface. | The following example shows how to create an infiniband failover interface. | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
# ifconfig ib0 up | # ifconfig ib0 up | ||||
# ifconfig ib1 up | # ifconfig ib1 up | ||||
# ifconfig lagg0 create laggtype infiniband | # ifconfig lagg0 create laggtype infiniband | ||||
# ifconfig lagg0 laggproto failover laggport ib0 laggport ib1 \e | # ifconfig lagg0 laggproto failover laggport ib0 laggport ib1 \e | ||||
1.1.1.1 netmask 255.255.255.0 | 1.1.1.1 netmask 255.255.255.0 | ||||
Show All 27 Lines |
I would move the "up" to the line setting the ethernet MAC, just slightly cleaner to have the MAC set before the interface comes up.