LAGG(4)

💖 LAGG(4) — link aggregation and link failover interface 💖

okay bestie, sit down, hydrate, and let me tell you about lagg — the Kernel Interfaces Manual entry that's about to become your whole personality 🫶

---

✨ NAME ✨

lagg — link aggregation and link failover interface

---

🌸 SYNOPSIS 🌸

so if you wanna bake this driver directly into the kernel, you drop this line into your kernel configuration file:

device lagg

OR, if you'd rather load it as a module at boot time (which, honestly, slay), you put this line in loader.conf(5):

if_lagg_load="YES"

---

🦋 DESCRIPTION 🦋

The lagg interface lets you aggregate multiple network interfaces into one virtual lagg interface, and the whole point is fault-tolerance and high-speed links. it's giving "many hands make light work" ✨

You can create a lagg interface with the ifconfig laggN create command. It can use different link aggregation protocols, which you specify with the laggproto proto option. Child interfaces get added with the laggport child-iface option and removed with the -laggport child-iface option. no cap 💅

The driver currently supports these aggregation protocols: failover (the default), lacp, loadbalance, roundrobin, broadcast, and none. The protocols decide which ports get used for outgoing traffic and whether a specific port accepts incoming traffic. The interface link state is what validates whether a port is active or not. vibe check, basically 👑

• failover — Sends traffic only through the active port. If the master port becomes unavailable, the next active port is used. The first interface added is the master port; any interfaces added after that are used as failover devices.

By default, received traffic is only accepted when it's received through the active port. You can relax that constraint by setting the net.link.lagg.failover_rx_all sysctl(8) variable to a nonzero value, which is useful for certain bridged network setups. lowkey a lifesaver for that specific scenario 🫶

• lacp — Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol (LACP) and the Marker Protocol. LACP will negotiate a set of aggregable links with the peer into one or more Link Aggregated Groups. Each LAG is composed of ports of the same speed, set to full-duplex operation. The traffic will be balanced across the ports in the LAG with the greatest total speed — in most cases there'll only be one LAG, and it contains all ports. In the event of changes in physical connectivity, Link Aggregation will quickly converge to a new configuration. iconic behavior, honestly 💅
• loadbalance — Balances outgoing traffic across the active ports based on hashed protocol header information, and accepts incoming traffic from any active port. This is a static setup — it does not negotiate aggregation with the peer or exchange frames to monitor the link. The hash includes the Ethernet source and destination address, and, if available, the VLAN tag, and the IP source and destination address.
• roundrobin — Distributes outgoing traffic using a round-robin scheduler through all active ports and accepts incoming traffic from any active port. Heads up bestie: using roundrobin mode can cause unordered packet arrival at the client. Throughput might be limited because the client performs CPU-intensive packet reordering. 😭
• broadcast — Sends frames to all ports of the LAG and receives frames on any port of the LAG. it's giving "tell everyone" 📣
• none — This protocol is intended to do nothing: it disables any traffic without disabling the lagg interface itself. main character energy of doing absolutely nothing ✨

---

Each lagg interface is created at runtime using interface cloning. The easiest way to do this is with the ifconfig(8) create command, or by using the cloned_interfaces variable in rc.conf(5).

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. don't be out here mixing MTUs, fr fr 🙈

---

The loadbalance and lacp modes will use the RSS hash from the network card if it's available, so they can avoid computing one. This may give poor traffic distribution if the hash is invalid or uses less of the protocol header information. You can force local hash computation per interface by setting the -use_flowid ifconfig(8) flag. The default for new interfaces is set via the net.link.lagg.default_use_flowid sysctl(8). noted 📝

---

🎀 EXAMPLES 🎀

Example 1: create a link aggregation using LACP with two bge(4) Gigabit Ethernet interfaces:

# ifconfig bge0 up
# ifconfig bge1 up
# ifconfig lagg0 create
# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \
        192.168.1.1 netmask 255.255.255.0

---

Example 2: create a link aggregation using ROUNDROBIN with two bge(4) Gigabit Ethernet interfaces and set a stride of 500 packets per interface:

# ifconfig bge0 up
# ifconfig bge1 up
# ifconfig lagg0 create
# ifconfig lagg0 laggproto roundrobin laggport bge0 laggport bge1 \
        192.168.1.1 netmask 255.255.255.0
# ifconfig lagg0 rr_limit 500

---

Example 3: the following example uses an active failover interface to set up roaming between wired and wireless networks using two network devices. Whenever the wired master interface is unplugged, the wireless failover device will be used:

# ifconfig em0 up
# ifconfig ath0 ether 00:11:22:33:44:55
# ifconfig create wlan0 wlandev ath0 ssid my_net up
# ifconfig lagg0 create
# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \
        192.168.1.1 netmask 255.255.255.0

(Note the mac address of the wireless device is forced to match the wired device as a workaround.) sneaky but necessary 🧚

---

🌈 SEE ALSO 🌈

ng_one2many(4), ifconfig(8), sysctl(8)

---

💜 HISTORY 💜

The lagg device first appeared in FreeBSD 6.3. a legend since day one ⭐

---

👑 AUTHORS 👑

The lagg driver was written under the name trunk by Reyk Floeter <reyk@openbsd.org>. The LACP implementation was written by YAMAMOTO Takashi for NetBSD. giving credit where credit is due 🫶

---

💀 BUGS 💀

There is no way to configure LACP administrative variables, including system and port priorities. The current implementation always performs active-mode LACP and uses 0x8000 as system and port priorities. so that's just... the way it is 😭

---

okay that's the whole page bestie, you're officially a lagg girlie now 💅✨

Dearest reader, this lil masterpiece hails from the Debian manual, dated November 18, 2017 — mwah, xoxo 💖🌸