bondctl - Linux Bonded Interface Utility
$Id: bondctl.pod,v 1.3 2012/01/13 01:06:47 acorliss Exp $
bondctl show
bondctl detail {master|all}
bondctl add {master}
bondctl del {master}
bondctl attach {master} {slave} [{slave2} ...]
bondctl detach {master} {slave} [{slave2} ...]
bondctl enable {master}
bondctl disable {master}
bondctl params {master}
bondctl set {master} {param} {value}
bondctl laddress {master} {MAC address}
bondctl ipaddress {master} flush
bondctl ipaddress {master} {IPv4/IPv6 CIDR address}
bondctl help
bondctl version
bondctl -f {file}
bondctl is a simple script for creating, removing, configuring, and querying bonded interfaces on the Linux platform. It works strictly off of the sysfs interface.
This script is designed to be compatible with both the BASH and ASH shells. For initramfs environments designed around busybox this means that this script will run unaltered.
From bonding.txt from the Linux kernel source tree (found in ./Documentation/networking/):
The Linux bonding driver provides a method for aggregating
multiple network interfaces into a single logical "bonded"
interface. The behavior of the bonded interfaces depends upon
the mode; generally speaking, modes provide either hot standby
or load balancing services. Additionally, link integrity
monitoring may be performed.
Additional details (including the use of the sysfs interface) can be found there.
This script relies a few external programs which need to be in the path in order to execute (all of which busybox can emulate, if needed):
cat used for extracting config values
echo used for program output/setting config values
ip used for changing the link state of interfaces
ls used to get a list of config parameters
test/[ used for various conditional tests
wc used for program output formatting
sed used for extracting text from command files
grep used for checking for existing addresses on slaves
awk used for checking for assigned MAC on master
All invocations of bondctl require an action argument to set the appropriate working mode of the utility. The following actions are available:
bondctl show
Displays a list of current bonding masters, one per line. No additional arguments are required.
bondctl detail {master|all}
Displays additional information on the named master. An alias of all exists to display information on all bonding masters. The additional information displayed includes the operational state, the list of slaves, the active slave (mode dependent), the bonding mode, and the monitoring mode.
bondctl add {master}
This creates a new bonding master with the specified name.
bondctl del {master}
This removes an existing bonding master with the specified name. This will down all interfaces and remove all slaves.
bondctl attach {master} {slave} [{slave2} ...]
This attaches a physical interface to the bonding master as a slave. This will fail if the physical interface is already up and has addresses assigned. If not, then all addresses are flushed and the device is attached. If the master is already up and running the slave will be brought up as well.
More than one slave can be attached at a time.
bondctl detach {master} {slave} [{slave2} ...]
This downs and detaches the named physical interface(s) from the specified bonding master. This will not down the master interface itself.
bondctl enable {master}
This brings up the bonding master and all slaves.
bondctl disable {master}
This downs the bonding master and all slaves.
bondctl params {master}
This displays a list of all configurable parameters exposed by the sysfs interface along with their current values.
bondctl set {master} {param} {value}
This sets the specified parameter to the desired value on the designated bonding master.
NOTE: some parameters, such as arp_ip_target operate as an array. In order to add or purge entries in the array you must prefix the value with a +/-, respectively. You can only operate on one array element at a time with this utility.
NOTE: some parameters, such as xmit_hash_policy will display both a string label and an ordinal value when queried with the params action. Setting the parameter should only be done with one or the other, not both.
bondctl laddress {master} {MAC address}
This sets the desired link address to the bonding master.
NOTE: the bonding driver defaults to taking the MAC address of the first slave assigned. If there's any inconsistency in how the master is brought up or the availability of interfaces this could cause some temporary ARP issues on other hosts. It's a good practice to assign a locally administered MAC address to your bonding master to avoid these kind of issues.
bondctl ipaddress {master} flush
bondctl ipaddress {master} {IPv4/IPv6 CIDR address}
This adds the specified IPv4/IPv6 address to the interface. The flush command is specifically supported to allow you to flush old addresses from the interface before assigning the new addresses. Otherwise, repeated use of this functionality will essentially configure your interface to use IP aliasing.
bondctl help
bondctl --help
This displays the option help text for this program.
bondctl version
bondctl --version
This displays the version of bondctl.
bondctl -f bond0.cmds
This instructs bondctl to take all of its commands from the specified text file. This file can have blank lines as well as comments and trailing comments. The following is a valid example of a command file:
# bond0 configuration
#
# Create the bonding master
add bond0
# Add slaves
attach bond0 eth0 eth1 # eth2/eth3 belongs to bond1
# Use ARP validation
set bond0 arp_ip_target +192.168.0.1
set bond0 arp_interval 100
# Set 802.3ad mode and hashing
set bond0 mode 802.3ad
set bond0 xmit_hash_policy layer3+4
# Set link address
laddress bond0 2e:b0:02:a8:00:01
# Set the IP address
ipaddress bond0 flush
ipaddress bond0 192.168.0.5/24
ipaddress bond0 192.168.0.10/24
ipaddress bond0 ff::ff/64
# Bring the interface up
enable bond0
In a nutshell, it's exactly like writing a script using bondctl to apply multiple settings at once, only you save a little typing by being able to omit the bondctl command itself.
If this script runs into any errors, permissions or otherwise, it will immediately exit with a non-zero return value and (hopefully) an intelligible error message.
0 if all operations were successful
1 on any error
I'm sure they're there. Report them when you find them: corliss@digitalmages.com with a subject line of "BUG: bondctl".
Arthur Corliss (corliss@digitalmages.com)
This software is licensed under the same terms as Perl, itself. Please see http://dev.perl.org/licenses/ for more information.
(c) 2009, Arthur Corliss (corliss@digitalmages.com)
Copyright © 1997 - 2016, Arthur Corliss, all rights reserved.