======================================
Configuring dynamic routing in bonding
======================================

As of 6.5, dynamic routing protocols can be added directly
to aggregators and bonders in their networking configuration.
These can be used in conjuction with space-associated interfaces
to easily manage multi-tenant dynamic routing.

To accomplish this integration bonding uses BIRD to handle protocol
creation and management. All of the following protocol options can be
found in the `BIRD documentation`_.

Protocols
========================================================================================================================

Bonding uses BIRD Internet Routing Daemon (BIRD) to implement dynamic routing protocols.

Refer to the `BIRD documentation`_ for more details.

Adding, editing, & deleting protocols
------------------------------------------------------------------------------------------------------------------------

Protocols are displayed in a table on the details page along with other networking objects (e.g. interfaces).

To add a protocol, click the |node-object-add| button to the upper-left of the protocols table. This will open the "add protocol" modal.

To edit a protocol, click the |node-object-edit| button. This will open the "edit protocol" modal.

To delete a protocol, click the |node-object-delete| button. This will ask for confirmation, and is permanent.

Configuring protocols
---------------------------------

All protocols have four core settings, a set of filters, and protocol-specific configuration.

Name
++++++

A name or description of the protocol (optional).

Protocol
++++++++++

There are four available dynamic routing protocols in bonding:

#. `Static`_
#. `OSPF`_
#. `BGP`_
#. `Babel`_

.. _`Static`: https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.14
.. _`OSPF`: https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.8
.. _`BGP`: https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.3
.. _`Babel`: https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.1


Enabled
++++++++++

If the protocol is enabled or not.

Protocols associated with a space that does not have private WAN enabled will be administratively disabled.


Filters
+++++++++

There are four filters for communicating routes between kernel and BIRD tables:

- **Import IPv4**
- **Export IPv4**
- **Import IPv6**
- **Export IPv6**

Each can be set to one of three values:

- **All**
- **None**
- **Filter**

If Filter is selected, a specific filter must be set (requires having previously created one for the aggregator).
See `configuring filters`_ below for more details.

.. _`configuring filters`: configuring-dynamic-routing-in-bonding.html#adding-editing-deleting-filters


Protocol configuration
+++++++++++++++++++++++++++++++++

Each protocol has its own set of configuration.

Refer to our implementation guide `AN-002 Implementing dynamic routing`_ or the `BIRD documentation`_ for protocol specific details.

.. _`AN-002 Implementing dynamic routing`: ../application-notes/an-002.html

Filters
========================================================================================================================

BIRD uses filters to give granular control over which routes are imported (BIRD to kernel), or exported (kernel to BIRD).

Adding, editing, & deleting filters
------------------------------------------------------------------------------------------------------------------------

This is the same as for `protocols <configuring-dynamic-routing-in-bonding.html#adding-editing-deleting-protocols>`__.


Configuring filters
------------------------------------------------------------------------------------------------------------------------

Filters are lists of **rules**, and rules are combinations of **matches** and **actions**.

Matches define which routes will have actions applied to them, and actions define what to do with matched routes.
Actions can be **Accept**, **Reject**, **Modify**, and **Log**.

Rules are applied in the order they are defined, and actions within a rule are applied in the order they are defined.
Actions can be re-ordered within a rule, but rules cannot be re-ordered within a filter.

OSPF configuration
===================

.. tip::
   To create an OPSF6 protocol simply change the OSPF channel to IPv6.

To create an OSPF protocol first add a new protocol using the add protocol
button under *Networking Details*, then set the protocol to *OSPF*:

|ospf-protocol|

OSPF uses areas as the main structure for management and administration.
Areas can be tuned for it's specific needs. Add an OSPF area object:

|ospf-area|

Give your new OSPF area an ID to differntiate itself. Any 32-bit number
seperated by .'s will work (Ex. An IPv4 address):

|ospf-area-id|

Each OSPF area can include a variety of networks, stubnets, interfaces,
and virtual links. For our simple protocol we are just going to add a
network. Create a network object:

|ospf-network|

OSPF uses link-state advertisements (LSAs) to share routing topologies with
other OSPF routers. By setting the network prefix, our OSPF neighbor will be
able to route to the set network. Set the network prefix:

|ospf-network-prefix|

After saving, you should have a working OSPF connection. If not read
:ref:`debugging-protocols`.

For a complete overview of the OSPF options read `BIRD OSPF documentation`_.

BGP configuration
==================

To create a BGP protocol first add a new protocol using the add protocol
button under *Networking Details*, then set the protocol to *BGP*:

|bgp-protocol|

BGP shares routing information between autonomous systems. For our purposes
that means we have to define our autonomous system number (ASN) to be able
to exchange routing information with another autonomous system. Set the
local router's ASN:

|bgp-local|

Similarily we have to set the ASN for who we are trying to communicate with.
This is the case even if the router is in the same AS. We also have to set
the IP address to confirm which connections to accept. Set the neighbor
router's IP address and ASN:

|bgp-neighbor|

After saving, you should have a working BGP connection. If not read
:ref:`debugging-protocols`.

For a complete overview of the BGP options read `BIRD BGP documentation`_.

Babel configuration
====================

To create a babel protocol first add a new protocol using the add protocol
button under *Networking Details*, then set the protocol to *Babel*:

|babel-protocol|

Babel is quite a simple protocol to configure. All it needs to be up and
running is an interface. Add an interface object:

|babel-interface|

When setting the interface pattern you can either just set the name of
the interface or use wildcard formatting to capture multiple interfaces
using a single pattern. For example ``eth*`` will use any interface that
starts with ``eth``. Set an interface pattern:

|babel-pattern|

After saving, you should have a working babel connection. If not read
:ref:`debugging-protocols`.

For a complete overview of the babel options read `BIRD babel documentation`_.

.. _static-route-configuration:

Static route configuration
===========================

To create a static route first add a new protocol using the add protocol
button under *Networking Details*, then set the protocol to *Static*:

|static-protocol|

Each static protocol can contain many routes, in this example we will only
be creating one. Add a route object:

|static-route|

Set the network you are routing to:

|static-network|

Set the type of destination. For example if you want to route via a certain
address use *Gateway* or if you to block traffic going to the set network
use *Prohibit*:

|static-destination|

After saving, you should have a working static route. If not read
:ref:`debugging-protocols`.

For a complete overview of the static route options read
`BIRD static documentation`_.

Custom configuration
=====================

Custom BIRD configuration files can be placed anywhere matching
`/etc/bonding/bird/*.conf` to inject custom filter and protocol definitions
for private WAN spaces.

Any configuration defined in these files is included in the final BIRD
configuration run by the node (regardless of private WAN mode).

.. _debugging-protocols:

Debugging protocols
====================

Every protocol comes with the option to send debug messages by enabling
the debug field. You can specify the type of debug messages you want to
receive or you can use *All* to receive any debug message relating to the
protocol:

|protocol-debug|

With debug enabled you'll be able to see additional messages in
``journalctl -u bonding-bird`` related to that protocol.

Additionally you can confirm that your protocol is working by using
BIRD's CLI interface ``birdc`` on your aggregator. After running ``birdc``
you will be given an interactive prompt that looks like this:

::

   bird>

To see the protocols bird has setup:

::

   bird> show protocols

Or if you are looking for a specific protocol:

::

   bird> show protocols <protocol>

The listed protocols will give you additional information like state that
can be useful to tell if your protocol is working as intended or why it
might be failing.

To get specific OSPF information use:

::

   bird> show ospf neighbors
   bird> show ospf interface
   bird> show ospf state

To get specific babel information use:

::

   bird> show babel interfaces
   bird> show babel neighbors
   bird> show babel entries
   bird> show babel routes

Use ``?`` to get a list of options:

::

   bird> ?
   bird> show ?
   bird> show ospf ?

To exit:

::

   bird> exit

.. _`BIRD filters documentation`: https://bird.network.cz/?get_doc&v=20&f=bird-5.html

.. |node-object-add| image:: /attachments/bonds/node-object-add.png
.. |node-object-edit| image:: /attachments/bonds/node-object-edit.png
.. |node-object-delete| image:: /attachments/bonds/node-object-delete.png
.. |node-object-caret| image:: /attachments/bonds/node-object-caret.png

.. _`BIRD documentation`: https://bird.network.cz/?get_doc&v=20&f=bird-6.html
.. _`BIRD OSPF documentation`: https://bird.network.cz/?get_doc&v=16&f=bird-6.html#ss6.8
.. _`BIRD BGP documentation`: https://bird.network.cz/?get_doc&v=16&f=bird-6.html#ss6.3
.. _`BIRD babel documentation`: https://bird.network.cz/?get_doc&v=16&f=bird-6.html#ss6.1
.. _`BIRD static documentation`: https://bird.network.cz/?get_doc&v=16&f=bird-6.html#ss6.12

.. |ospf-protocol| image:: /attachments/dynamic-routing/ospf-protocol.png
.. |ospf-area| image:: /attachments/dynamic-routing/ospf-area.png
.. |ospf-area-id| image:: /attachments/dynamic-routing/ospf-area-id.png
.. |ospf-network| image:: /attachments/dynamic-routing/ospf-network.png
.. |ospf-network-prefix| image:: /attachments/dynamic-routing/ospf-network-prefix.png

.. |bgp-protocol| image:: /attachments/dynamic-routing/bgp-protocol.png
.. |bgp-local| image:: /attachments/dynamic-routing/bgp-local.png
.. |bgp-neighbor| image:: /attachments/dynamic-routing/bgp-neighbor.png

.. |babel-protocol| image:: /attachments/dynamic-routing/babel-protocol.png
.. |babel-interface| image:: /attachments/dynamic-routing/babel-interface.png
.. |babel-pattern| image:: /attachments/dynamic-routing/babel-pattern.png

.. |static-protocol| image:: /attachments/dynamic-routing/static-protocol.png
.. |static-route| image:: /attachments/dynamic-routing/static-route.png
.. |static-network| image:: /attachments/dynamic-routing/static-network.png
.. |static-destination| image:: /attachments/dynamic-routing/static-destination.png

.. |protocol-debug| image:: /attachments/dynamic-routing/protocol-debug.png
