==========
Leg hooks
==========

Leg hooks are run with the "start" argument after a leg is added and
with the "stop" argument before it is removed.

After a leg hook has been added, you must restart the bond from the
management server or from the host command line to execute the hook the
first time.

Hook locations:

-  ``/etc/bonding/leg.d/all``: hooks to be run for all legs
-  ``/etc/bonding/leg.d/<leg ID>``: hooks for individual legs
-  ``/etc/bonding/leg.d/default``: hooks for legs with no individual
   hook folder

An example leg hook is available at
``/usr/share/doc/bonding/examples/leg-hook``.

Environment variables
----------------------

.. warning::
    In bonding 6.4, a number of variables were removed from the environment.
    The following variables are present only in bonding 6.3 and prior:

    -  INTERFACE: the raw interface (i.e. eth3 or eth3.3, even for PPP legs)
    -  INTERFACE_BASE: the raw interface excluding any VLAN
    -  INTERFACE_MAC: the MAC of the interface raw, if specified
    -  INTERFACE_MTU: the MTU of the interface, if specified
    -  INTERFACE_MODE: the Ethernet mode of the interface, if applicable to the leg
    -  IP: the leg IP address
    -  NETMASK: the assigned netmask, for static legs only
    -  GATEWAY: the assigned gateway, for static legs only

    If your leg hooks make use of those values, you will need to modify your leg
    hooks to be either `addressing <./addressing.html>`__ or
    `interface <./interface.html>`__ hooks. DO NOT UPGRADE
    these nodes to 6.4 without first modifying the leg hooks. Otherwise, the hooks
    will not run properly after the upgrade.

    After testing new addressing or interface hooks on a 6.4 node, we advise you
    to follow these steps when performing the upgrade to 6.4 on affected nodes:

    #. Disable leg hooks by removing them
    #. `Upgrade node to 6.4 <../../nodes/upgrading-and-replacing-a-node/upgrading-a-node.html#upgrading-6-1-and-newer-nodes>`__
    #. Add modified leg hooks, along with any necessary addressing or interface hooks
    #. Restart bonding

Leg hooks are run with the following environment variables:

-  ID: the leg ID
-  BOND_ID: the ID of the leg's bond
-  LINK_MODE: the mode of the leg: "idle" or "active" ("offline" legs
   are never started)
-  FAILOVER: "True" for failover legs, otherwise "False"
-  TUNNEL_PORT: the tunnel UDP port number
-  UP_SPEED: the upload speed (CPE to agg) in Mbps
-  DOWN_SPEED: the download speed (agg to CPE) in Mbps
-  BANDWIDTH_ADAPTATION: "True" if bandwidth adaptation is enabled for
   this leg, otherwise "False"

-  MINIMUM_MTU: The minimum possible MTU of the leg, if MTU detection
   is enabled

The following fields are mobile broadband leg-specific:

-  IMEI: the unique 15-digit identifier for the mobile network device

-  SIM_PIN: the PIN required to access the SIM card

-  ROAMING: whether the leg is constrained to its home network or not

-  ACCESS_MODES: list of access modes that the modem can use to connect
   to the mobile network

-  RADIO_BANDS: list of radio bands that the modem can use to connect
   to the mobile network
