======================
Traffic shaping hooks
======================

Shaping hooks are run with the "start" argument when the tunnel is
started, "stop" when the tunnel is stopped, and "update-rates" when the
available sending rate changes. This occurs, for example, when a leg
goes down and its bandwidth is no longer available to the bond. Hooks
are called at most once every five seconds.

After a shaping hook has been added, you can execute it by killing the
tunnel process. The hook will be run when the tunnel process is
restarted. You can also restart the bond from the management server or
from the host command line to execute the hook.

Shaping hooks are only called if the bond's QoS profile setting is not
blank. If a bond has an individual shaping hook folder (see below), the
bond's selected QoS profile will not take effect unless the default QoS
hook has been linked into the bond's individual hook folder. For
example, to keep the behaviour of a bond's selected QoS profile while
also using a shaping hook for the bond, run the following command on the
bonder or aggregator:

::

    ln -s /etc/bonding/shaping.d/default/20_qos /etc/bonding/shaping.d/<bond ID>/20_qos

Hooks are stopped before a leg speed test and started again when the
test is completed.

Hook locations:

-  ``/etc/bonding/shaping.d/all``: hooks to be run on all traffic
   shaping events
-  ``/etc/bonding/shaping.d/<bond ID>``: hooks for individual bond
   traffic shaping events
-  ``/etc/bonding/shaping.d/default``: hooks for bonds with no
   individual shaping folder

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

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

Tunnel hooks are run with the following environment variables:

-  ID: bond ID
-  INTERFACE: tunnel interface name (i.e. tun1)
-  SPEED: available sending speed in kilobits per second
