Digital Mages

Digital Mages - bondctl(8)


NAME

bondctl - Linux Bonded Interface Utility


VERSION

$Id: bondctl.pod,v 1.3 2012/01/13 01:06:47 acorliss Exp $


USAGE

        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}


DESCRIPTION

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.

BACKGROUND

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.


REQUIRED EXTERNAL PROGRAMS

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


REQUIRED ARGUMENTS

All invocations of bondctl require an action argument to set the appropriate working mode of the utility. The following actions are available:

show

    bondctl show

Displays a list of current bonding masters, one per line. No additional arguments are required.

detail

    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.

add

        bondctl add {master}

This creates a new bonding master with the specified name.

del

        bondctl del {master}

This removes an existing bonding master with the specified name. This will down all interfaces and remove all slaves.

attach

        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.

detach

        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.

enable

        bondctl enable {master}

This brings up the bonding master and all slaves.

disable

        bondctl disable {master}

This downs the bonding master and all slaves.

params

        bondctl params {master}

This displays a list of all configurable parameters exposed by the sysfs interface along with their current values.

set

        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.

laddress

        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.

ipaddress

        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.

help

        bondctl help
        bondctl --help

This displays the option help text for this program.

version

        bondctl version
        bondctl --version

This displays the version of bondctl.

-f

        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.


DIAGNOSTICS

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.


EXIT STATUS

    0   if all operations were successful
    1   on any error


BUGS AND LIMITATIONS

I'm sure they're there. Report them when you find them: corliss@digitalmages.com with a subject line of "BUG: bondctl".


AUTHOR

Arthur Corliss (corliss@digitalmages.com)


LICENSE AND COPYRIGHT

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)