==================
Node applications
==================

bonding-setup
----------

``bonding-setup`` gets configuration from ``nodeconfig``, and updates node
configuration. It performs setup required after installing or upgrading the
bonding software.

nodeconfig
-----------

``nodeconfig`` downloads the latest configuration file from the server
and saves it to the file ``/var/lib/bonding/configuration.json``. It
requires a valid ``/etc/bonding/bonding.conf`` file, or the server name
and node's key specified on the command line.

.. note::
    Prior to 2013.4, ``nodeconfig`` was called ``getconfig``. ``getconfig``
    still works—it is a symlink to ``nodeconfig``.

.. warning::
    As of 6.4, node configurations are versioned.
    Legacy nodes (6.3 and earlier) continue to use what is now version one,
    while newer nodes use the new version two.

    Manually requesting a node's configuration from the dedicated nodeconfig API endpoint

    ::

        /nodes/config?key=<node key>&version=<configuration version>

    will set a new precedent for which configuration version that node should use for updates.
    Doing so with the wrong configuration version will set a bad precedent and break the node.

    **Don't do that**.

    Instead, the following read-only endpoint should be used to manually request the
    management server's version of a node's configuration.

    ::

        /nodes/<node ID>/configuration/<configuration version>/


Bonding updates its cached configuration file when it receives updates
from the management server, so ``nodeconfig`` should usually be used
only in two circumstances:

#. When a node key or server has been changed in
   ``/etc/bonding/bonding.conf``, and the the cached config file needs
   to be updated to match the new node. For details, see `Changing a
   bonder key <upgrading-and-replacing-a-node/changing-a-bonder-key.html>`__.
#. If ``/var/cache/bonding`` becomes out-of-date. This could occur if
   config updates are deleted in the management server, or if config
   updates cannot be sent from the management server to the node due to
   a network problem.

``nodeconfig`` has no output unless an error occurs or the ``--verbose``
flag is used. After running ``nodeconfig``, you must restart Bonding to
apply the updated configuration.

If the node ID in the downloaded configuration file doesn't match the ID
in the node's SSL certificate, it runs ``nodeconfig`` to get a new
certificate.

Type

::

    nodeconfig –h

for usage information. It can be run on both bonders and aggregators.

bondlog
--------

``bondlog`` displays log messages from various Bonding processes. It can
display messages in a scrollable window or by writing new messages to
the terminal when a message appears in a log file. Bondlog also filters
messages from certain tunnel or TCP proxy processes and colours output
to make it easier to identify warning and error messages in the log.

In scrolling mode, use the following commands to navigate the log:

-  Arrow keys to scroll one line at a time
-  Page up/page down keys to scroll one screen at a time
-  Press Shift-g to go to the bottom of the file
-  Press g to return to the top of the file
-  Press :<number><enter> (colon, a number, followed by enter) to
   navigate to that numbered line in the file.
-  Press /<search term><enter> (forward slash, a search term, followed
   by enter) to search for and highlight that term in the file.
-  Press q to quit.

In follow mode, Ctrl-C quits the application.

Bondlog supports the following options and arguments:

``-v``
+++++++

Show verbose output.

``-f``
+++++++

Follow the log file, showing new messages as they appear in the file.

``--disable-colour``
+++++++++++++++++++++

Don't show message severity in colour.

``-n <number of lines>``
+++++++++++++++++++++++++

Show the given number of messages.

``tun``
++++++++

Show messages from all tunnel processes.

``tun<bond ID>``
+++++++++++++++++

Show messages only from the tunnel process identified by the given ID.

``br``
+++++++

Show messages from all TCP proxy processes. The TCP proxy is known as a
bridge (hence the argument "br") because it bridges data streams from
one host to another, hiding the effects of the bonded connection from
the end hosts.

``br<bond ID>``
++++++++++++++++

Show messages only from the TCP proxy process identified by the given
ID.

``sub``
++++++++

Show messages only from the subprocess service, which is responsible for
executing programs (i.e. iptables, ip addr, udhcpc, tunnel) for other
bonding services.

``conf``
+++++++++

Show messages only from the configuration service, which sends updates
to and receives updates from the management server and updates the
cached configuration file.

``cell``
++++++++

Show messages only from the cell service, which coordinates the
configuration of mobile broadband modems.

``web``
+++++++

Show messages only from the web service, which is used for initial
bonder configuration.

``bird``
++++++++

Show messages from all BIRD processes. BIRD is a routing daemon used in
private WAN.

``bird <space key>``
++++++++++++++++++++

Show messages from the bird process for an individual space.

``space``
+++++++++

Show messages from all private WAN aggregator and router agent processes.
These processes are responsible for maintaining the network configuration of
private WAN spaces.

``space <space key>``
+++++++++++++++++++++

Show messages from the privatewan aggregator and router agent processes for an
individual space.

bondlog examples
-----------------

The following examples show how to use bondlog.

``bondlog``
++++++++++++

Shows the last 100 messages in node.log.

``bonding -n 20``
++++++++++++++++++

Shows the last 20 messages in node.log.

``bondlog -f``
+++++++++++++++

Shows the last 10 messages in node.log, then shows new messages as they
appear in the log.

``bondlog tun``
++++++++++++++++

Shows the last 100 messages in tunnel.log.

``bondlog tun10``
++++++++++++++++++

Shows the last 100 messages in tunnel.log from the tunnel of bond 10.

``bondlog -f -n 100 tun10``
++++++++++++++++++++++++++++

Shows the last 100 messages from the tunnel of bond 10 and then shows
new messages from tunnel 10 as they appear in the log.

``bondlog br3``
++++++++++++++++

Shows the last 100 messages in bridge.log from the bridge of bond 3.

``bondlog -v``
+++++++++++++++

Shows the last 100 message in node.log without filtering any
information.

bondctl
--------

.. NOTE::
    The bondctl command was removed in version 6.5.

bondctl controls individual services on each node. It takes two
arguments: (1) the action to take (restart or status) and (2) the
service to act upon (config, node, subprocess, etc.)

For a complete list of available actions and services, just run bondctl.
To control services together instead of individually, see `Controlling
node services <controlling-node-services.html>`__.

.. warning::

    Restarting the ``node`` or ``subprocess`` services will interrupt
    customer traffic.

bondctl examples
-----------------

``bondctl restart config``
+++++++++++++++++++++++++++

Restarts the configuration service.

``bondctl restart node``
+++++++++++++++++++++++++

Restart the node service.

``bondctl status subprocess``
++++++++++++++++++++++++++++++

Shows the status of the subprocess service—its current state (running
or not running), process ID, and time since it was started or stopped.

legids
-------

``legids`` displays a variety of information about the legs on a bonder
or aggregator. By default, it shows the leg ID, type, link mode,
interface, state, speed, and information about the leg IP address. The
``--verbose`` or ``-v`` flag can be used to show additional information
about the leg's tunnel state and port number, as well as whether or not
the management server can be contacted through the leg (on bonders
only).

On aggregators, a bond ID can be used as an argument to only show legs
for the given bond. For example, ``legids 2`` would show only legs for
bond 2.

Example output on a bonder:

::

    3: 10.100.42.30<->10.100.10.3; mode active; iface eth1; state up; speed 10.00/10.00 Mbps
        link up; link state changed 2018-01-03 19:28:16; link port 2002
        band. adapt. disabled; sending speed 10.000 Mbps
        latency 0.020s; std. deviation 0.000s; path MTU 1492
        ping time 0.200s; fail time 0.300s
        packet loss 0.00%
        flap state: healthy
    5: 2602::8000:a<->2602::3; mode active; iface eth2; state up; speed 10.00/10.00 Mbps
        link up; link state changed 2018-01-03 19:28:32; link port 2772
        band. adapt. disabled; sending speed 10.000 Mbps
        latency 0.021s; std. deviation 0.004s; path MTU 1500
        ping time 0.200s; fail time 0.300s
        packet loss 0.60%
        flap state: recovering
    7: unknown address; mode offline; iface eth3; state down; speed 10.00/10.00 Mbps
        link down; link state changed 2018-01-03 19:28:17; link port 2773

legping
--------

``legping`` shows the last tunnel ping latency for each leg in a bond.
Each second, it displays the leg ID and the last RTT in milliseconds.

On bonders, no argument is needed. On aggregators, a bond ID is required
as an argument. To quit, press Ctrl-C.

Example output on an aggregator:

::

    root@prodagg02:~# legping 1
       1 273: 44.524   423: 99.672
       2 273: 44.737   423: 37.448
       3 273: 45.260   423: 38.999

nodessl
--------

Various services on the management server and nodes use SSL certificates
to authenticate each other and to encrypt traffic between
hosts.``nodessl`` creates a RSA key, if it doesn't already exist, and
downloads certificates for the node management VPN client. ``nodessl``
is called automatically as part of the Bonding installation and upgrade
procedure, so this script need only be run manually if the key or
certificate needs to be updated.

``nodessl`` also downloads the bonding root CA certificate, certificate
revocation list, and a key used for connecting to the management VPN
server.

To force ``nodessl`` to create a new RSA key and download a new
certificate even if a key and certificate already exist, use the
``--force`` option.

bgpenable
----------

.. note::

    The `bgpenable` script is only avaliable before version 6.5 of bonding.

``bgpenable`` modifies the configuration of the Quagga routing daemon to
allow BGP configuration. To configure BGP after enabling it, use the
``vtysh`` console. ``bgpenable`` restarts the Quagga routing daemon,
which temporarily interrupts routing capabilities on the host.
