=========================================================
AN-002 Implementing dynamic routing with quagga
=========================================================

.. warning::

    Support for Quagga will be deprecated in SD-WAN 6.9. If Quagga is
    enabled on nodes running 6.9, dynamic routing will not work. Please see
    `Configuring dynamic routing in bonding
    <../dynamic-routing/configuring-dynamic-routing-in-bonding.html>`__ for
    instructions on how to configure dynamic routing protocols directly on
    bonders and aggregators.

.. tip::

    As of 6.5, dynamic routing protocols can be configured directly on bonders
    and aggregators in their networking configuration. This method is significantly
    more integerated into bonding and adds support for more protocols.

.. warning::

    If you ever restart the quagga service the bonding service MUST be
    restarted otherwise it is possible you will be missing route entries and
    as a result bonding will not properly function.

Dynamic routing is an integral part of modern networking and is widely used
across many organizations and applications. In the case of bonding, it is a
common scenario where you want to communicate to an external host from a node
(or vice-versa) and dynamic routing makes for a powerful solution.

All of the options listed assume that any necessary setup on the other side
of a protocol have already been handled. For example, if OSPF does not have the
expected neighbor their won't be anything to route to. These implementations
are also minimal for the sake of simplicity. To get the most out of dynamic
routing for your use case be sure to read the linked documentation.

Quagga is an open-source routing suite that allows for the creation of
routing protocols as daemons. These daemons communicate with the `Zebra`
daemon, which acts as the layer between the user and the kernel. For our
purposes Quagga supports OSPF and BGP in both IPv4 and IPV6.

SD-WAN integrates with the Quagga routing service for
publishing routes into OSPF or BGP networks. This document describes how
to configure Quagga. Since each partner's network is unique, Quagga must
be manually configured on each aggregator using the unique settings for
each network.

Further reading
================

More information about Quagga is available at:

-  http://www.nongnu.org/quagga/
-  http://openmaniak.com/quagga_tutorial.php

Configuring Quagga via ``vtysh``
=================================

Quagga is configured though a Cisco-like console called ``vtysh``. Like
Cisco, ``vtysh`` has three modes:

#. View mode, similar to user exec mode in Cisco, used for read-only
   access to Quagga
#. Enable mode, similar to privileged exec mode in Cisco, used for
   read-write access to Quagga
#. Configuration mode, similar to global configuration mode in Cisco,
   used to modify Quagga's running configuration

The initial ``vtysh`` mode is enable mode.

To start the console, log in as root and run ``vtysh``. You will be
presented with the standard login banner and prompt:

::

    root@host:~# vtysh
    Hello, this is Quagga (version 0.99.22.4).
    Copyright 1996-2005 Kunihiro Ishiguro, et al.
    host#

To see the list of available commands, type ? at the prompt. To show
valid arguments for a command, type the command name and then type ?.

``vtysh`` understands abbreviated commands. For example,
``configure terminal`` can be abbreviated as ``conf t``.

Changing modes
+++++++++++++++

The following commands change modes in ``vtysh``:

+-----------------+-----------------+--------------------------+--------------+
| Current mode    | New mode        | Command                  | Shortcut     |
+=================+=================+==========================+==============+
| View            | Enable          | ``enable``               | ``en``       |
+-----------------+-----------------+--------------------------+--------------+
| Enable          | View            | ``disable``              | ``dis``      |
+-----------------+-----------------+--------------------------+--------------+
| Enable          | Configuration   | ``configure terminal``   | ``conf t``   |
+-----------------+-----------------+--------------------------+--------------+
| Configuration   | Enable          | ``end``                  |              |
+-----------------+-----------------+--------------------------+--------------+


Common enable mode commands
++++++++++++++++++++++++++++

+------------------------------------------+------------------------------------------+----------------------+
| Action                                   | Command                                  | Shortcut             |
+==========================================+==========================================+======================+
| Show complete configuration              | ``show running-config``                  | ``show run``         |
+------------------------------------------+------------------------------------------+----------------------+
| Enter configuration mode                 | ``configure terminal``                   | ``conf t``           |
+------------------------------------------+------------------------------------------+----------------------+
| Save the updated configuration to disk   | ``copy running-config startup-config``   | ``copy run start``   |
+------------------------------------------+------------------------------------------+----------------------+
| Show routing table                       | ``show ip route``                        | ``sh ip ro``         |
+------------------------------------------+------------------------------------------+----------------------+
| Show OSPF neighbors                      | ``show ip ospf neighbor``                | ``sh ip os ne``      |
+------------------------------------------+------------------------------------------+----------------------+
| Show BGP neighbors                       | ``show ip bgp neighbors``                | ``sh ip bgp ne``     |
+------------------------------------------+------------------------------------------+----------------------+


Common configure mode commands
+++++++++++++++++++++++++++++++

In configure mode, prepend ``no`` to a command to reset that
configuration to its default or to remove the configuration. For
example, if OSPF was enabled, you could disabled it by running
``no router ospf``.

+----------------------------------------------------------------+----------------------------------+----------------------------+
| Action                                                         | Command                          | Shortcut                   |
+================================================================+==================================+============================+
| Exit current configuration mode and go down to previous mode   | ``exit``                         | ``ex``                     |
+----------------------------------------------------------------+----------------------------------+----------------------------+
| Exit configuration mode and return to enable mode              | end                              |                            |
+----------------------------------------------------------------+----------------------------------+----------------------------+
| Configure OSPF routing                                         | ``router ospf``                  |                            |
+----------------------------------------------------------------+----------------------------------+----------------------------+
| Configure BGP routing                                          | ``router bgp``                   |                            |
+----------------------------------------------------------------+----------------------------------+----------------------------+
| Configure interface                                            | ``interface <interface name>``   | ``int <interface name>``   |
+----------------------------------------------------------------+----------------------------------+----------------------------+


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

To use OSPF in Quagga, first enable the protocol. Run the following
commands from a Linux shell (not ``vtysh``):

::

    sed -i 's/ospfd=no/ospfd=yes/' /etc/quagga/daemons
    touch /etc/quagga/ospfd.conf
    chmod 640 /etc/quagga/ospfd.conf
    chown quagga:quagga /etc/quagga/ospfd.conf
    service quagga restart

Then run ``vtysh``.

Enter configuration mode:

::

    configure terminal

You are now in configuration mode, indicated by the ``(config)#``
prompt.

To enable and configure OSPF, run:

::

    router ospf

You are now in OSPF configuration mode, indicated by the
``(config-router)#`` prompt.

Run commands to configure OSPF. At the minimum, you must provide a
router ID (typically the node's IPv4 address is used), redistribute
static routes, and specify a network and area (if unsure, the area can
be 0.0.0.0):

::

    ospf router-id <router ID or IPv4>
    redistribute static
    network <network/subnet> area <area, or just 0.0.0.0>

To see all the available OSPF settings, type ? at the prompt or review
the Quagga documentation.

A number of OSPF-related settings are available under the interface
configuration mode. To enter this mode, run
``interface <interface name>``. For example, to configure OSPF settings
for the network on eth0, run ``interface eth0``. The prompt will change
to ``(config-if)#``, indicating you are in interface configuration
mode. Type ``ospf ?`` to list the available OSPF configuration options.

When OSPF is configured, type ``end`` to leave configuration mode.
Verify that neighbor routers have been found by running
``show ip ospf neighbor`` and that OSPF routes are being received by
running ``show ip ospf route``. To save the configuration to disk, run
``copy run start``.

.. note::
    For a node to discover neighbors via OSPF, the OSPF protocol must be accepted
    by the firewall. If a node does not have an iptables rule to accept neighbor traffic
    using protocol 89, it will not be able to discover neighbors via OSPF.

OSPF6 configuration
====================

To use OSPF6 in Quagga, first enable the protocol. Run the following
commands from a Linux shell (not ``vtysh``):

::

    sed -i 's/ospf6d=no/ospf6d=yes/' /etc/quagga/daemons
    touch /etc/quagga/ospf6d.conf
    chmod 640 /etc/quagga/ospf6d.conf
    chown quagga:quagga /etc/quagga/ospf6d.conf
    service quagga restart

.. note::
    These commands are different than as they appear for OSPF in the previous section.
    You must run each set of commands to use the corresponding protocol.

Then run ``vtysh``.

Enter configuration mode:

::

    configure terminal

You are now in configuration mode, indicated by the ``(config)#``
prompt.

To enable and configure OSPF6, run:

::

    router ospf6

You are now in OSPF6 configuration mode, indicated by the
``(config-ospf6)#`` prompt.

Run commands to configure OSPF6. At the minimum, you must provide a
router ID (like for OSPF, typically the node's IPv4 address is used),
redistribute static routes, an area with a range of IPv6 addresses,
and an interface belonging to that area.

::

    router-id <router ID or IPv4>
    redistribute static
    area <area, or just 0.0.0.0> range <IPv6 network/subnet>
    interface <ifname> area <area, or just 0.0.0.0>

To see all the available OSPF6 settings, type ? at the prompt or review
the Quagga documentation.

Like for OSPF, many OSPF6 settings can be configured on an interface level
from the interface configuration terminal.

When OSPF6 is configured, type ``end`` to leave configuration mode.
Verify that neighbor routers have been found by running
``show ipv6 ospf6 neighbor`` and that OSPF6 routes are being received by
running ``show ipv6 ospf6 route``. To save the configuration to disk, run
``copy run start``.

.. note::
    For a node to discover neighbors via OSPF6, the OSPF protocol must be accepted
    by the firewall. If a node does not have an ip6tables rule to accept neighbor traffic
    using protocol 89, it will not be able to discover neighbors via OSPF6.

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

To use BGP in Quagga, first enable the protocol. Run the following
commands from a Linux shell (not ``vtysh``):


::

    sed -i 's/bgpd=no/bgpd=yes/' /etc/quagga/daemons
    touch /etc/quagga/bgpd.conf
    chmod 640 /etc/quagga/bgpd.conf
    chown quagga:quagga /etc/quagga/bgpd.conf
    service quagga restart


Then run ``vtysh``.

Enter configuration mode:

::

    configure terminal

You are now in configuration mode, indicated by the ``(config)#``
prompt.

To enable and configure BGP, run:

::

    router bgp <your AS number>

You are now in BGP configuration mode, indicated by the
``(config-router)#`` prompt.

Run commands to configure BGP. At the minimum, you must provide a router
ID (for example, the IP address of the aggregator), redistribute static
routes, and specify a neighbor:

::

    bgp router-id <router ID>
    redistribute static
    neighbor <neighbor IP> remote-as <neighbor's AS number>

To export IPv6 routes as well, you will also need to set the following under
the bgp configuration::

    address-family ipv6
    redistribute static
    neighbor <neighbor IP> activate
    exit-address-family

To see all the available BGP settings, type ? at the prompt or review
the Quagga documentation.

When BGP is configured, type ``end`` to leave configuration mode. Verify
that neighbor routers have been found by running
``show ip bgp neighbors``. To save the configuration to disk, run
``copy run start``.

.. _`Configuring Dynamic Routing with Quagga`: ../dynamic-routing/aggregators/configuring-dynamic-routing-in-quagga.html
