#summary Overview of quagga routing

= Introduction =

CORE is a great tool for building large network emulation topologies to experiment with quagga routing.  This guide is for users who want to play with possibly multiple or non-default versions of [http://www.quagga.net quagga routing] using CORE.

_*This page is specific to the OpenVZ version of CORE.*_

= Default settings =

quagga binaries and libraries come with the default templated OpenVZ container.  They are installed in `/usr/sbin/` and `/usr/bin/` directories.  rip, ripng, ospf6, ospf, and bgp are installed in `/usr/sbin/` and vtysh is in `/usr/bin/`.

All containers use the same binaries.  What differs from node to node is the configuration.  Here, CORE uses the unified quagga configuration file `/etc/quagga/Quagga.conf`.

When you lay down a router configuration in the GUI and the "model" selected in the configuration window is "quagga" (this is the default), what will occur when you start the emulation is that CORE will start zebra, ospf6d, and ospfd.   On the container file system, the file `/etc/quagga/Quagga.conf` will be used to start up the containers.  This file is symlinked to the file `/root/boot.conf` on the container.  On the host file system, each node's `/root` directory is actually stored in `/tmp/n#` directory.

Where does the file `/tmp/n0/boot.conf` come from, you may ask?  It is generated by CORE on the basis of the GUI configuration or on the basis of any saved .imn configuration files.  For instance, consider a node n0 that has two interfaces.  This is the type of configuration in the GUI that is saved to a .imn file:

{{{
node n0 {
    type router
    model quagga
    network-config {
        hostname n0
        !
        interface eth1
         ip address 10.0.1.1/24
         ipv6 address a:1::1/64
        !
        interface eth0
         ip address 10.0.0.1/24
         ipv6 address a:0::1/64
        !
        router ospf
         router-id 10.0.0.1
         network 10.0.0.0/24 area 0
         network 10.0.1.0/24 area 0
        !
        router ospf6
         router-id 10.0.0.1
         interface eth0 area 0.0.0.0
         interface eth1 area 0.0.0.0
        !
    }
}}}

When CORE starts the emulation, it takes the above .imn configuration and generates a file at `/tmp/n0/boot.conf` that looks like this:

{{{
interface eth0
 ip address 10.0.0.1/24
 ipv6 address a:0::1/64
!
interface eth1
 ip address 10.0.1.1/24
 ipv6 address a:1::1/64
!
router ospf
 router-id 10.0.0.1
 network 10.0.0.0/24 area 0
 network 10.0.1.0/24 area 0
!
router ospf6
 router-id 10.0.0.1
 interface eth0 area 0.0.0.0
 interface eth1 area 0.0.0.0
!
}}}

This is just a stripped down Quagga.conf file.  Then, CORE will execute the (`/root/quagga-startup-openvz.sh`) which does something like this

{{{
CONF=/root/boot.conf
#
# launch Quagga processes
#
zebra -d

vtysh -b

for f in rip ripng ospf6 ospf bgp; do
    grep -q "router ${f}$" $CONF && ${f}d -d
done

vtysh -b

sysctl -w net.ipv4.ip_forward=1

}}}

At this point, the default quagga (0.99.9 version with [http://hipserver.mct.phantomworks.org/ietf/ospf RFC 5614 OSPF MANET extensions] shipped with CORE-3.5) is running in each node.

= Saving existing configuration =

Please be aware that any changes you do to the `/etc/quagga/Quagga.conf` file of a running container, or to the routing daemons via the vtysh interface itself at runtime, will be purged when you stop the emulation.  Please read the next section to learn how to configure changes and make them persistent across execution runs.

= Generating and saving non-default configuration =

To save any configuration state that should persist across configuration runs, you should either edit the .imn file directly, or enter a "Custom startup config" via the router configuration dialog box at configuration time (not at runtime).  For instance, let's suppose that you wanted to change the hello interval on one of the interfaces.  You could click on *Custom startup config* and select *Edit*.  Here, you would see a dialog such as:

{{{
interface eth0
 ip address 10.0.0.1/24
 ipv6 address a:0::1/64
!
interface eth1
 ip address 10.0.1.1/24
 ipv6 address a:1::1/64
!
router ospf
 router-id 10.0.0.1
 network 10.0.0.0/24 area 0
 network 10.0.1.0/24 area 0
!
router ospf6
 router-id 10.0.0.1
 interface eth0 area 0.0.0.0
 interface eth1 area 0.0.0.0
!
}}}

You can add any statements to these interface or router configuration blocks, and then select *Apply changes*.  For instance: 

{{{
 interface eth0
 ip address 10.0.0.1/24
 ip ospf hello-interval 7
 ipv6 address a:0::1/64
}}}

Now, when you start the emulation, you will see that eth0 has a different hello interval, and no adjacency will be formed (unless the peer router is also changed).

If you save your overall CORE config, you will see this in the .imn file:

{{{
    custom-config {
        custom-config-id generic
        custom-command /usr/lib/core/quaggaboot.sh
        config {
        interface eth0
         ip address 10.0.0.1/24 
         ip ospf hello-interval 7
         ipv6 address a:0::1/64
        !
        interface eth1
         ip address 10.0.1.1/24
         ipv6 address a:1::1/64
        !
        router ospf
         router-id 10.0.0.1
         network 10.0.0.0/24 area 0
         network 10.0.1.0/24 area 0
        !
        router ospf6
         router-id 10.0.0.1
         interface eth0 area 0.0.0.0
         interface eth1 area 0.0.0.0
        !
        }
    }
    custom-enabled true
}}}

Note that the whole Quagga.conf file is replicated, and it essentially overwrites anything that was autogenerated in the `network {}` statement block above.  So, either editing the .imn custom-config or using the GUI to do so is the main way to change routing configuration that persists across CORE emulation runs.

= Where are the ripd, ripngd, bgpd configurations? =

By default, CORE does not enable these protocols.  To enable these... *`[`TO BE COMPLETED]*

= Automatically adding default configuration = 

*`[`TO BE COMPLETED]*

= Building a new quagga =

You may want to replace altogether the quagga implementation.  Here is one way to do it.

First, make sure that your host CentOS system has an adequate build environment.  Try building the new version of quagga in a scratch directory on the host OS.

If that succeeds, you will want to build quagga from a directory *within* the container while the container is running.  For instance `/usr/local/src` from within the container.  It is important to configure and build this from within the running context of the container so that paths are not messed up.

The shared filesystem of the containers is found in `/vz/private/core-root`.  Here is one way to do it.  Assume that the quagga you want to build is in `/home/core/quagga` directory on the host machine.

  # `sudo cp /home/core/quagga /vz/private/core-root/usr/local/src/`
  # Start CORE (note, you can also `sudo vzctl start 1000` and `sudo vzctl enter 1000` to enter a running container without starting CORE), and enter the container.  The rest of these commands are executed from within the container.
  # `cd /usr/local/src/quagga`
  # `./update-autotools`
  # `./configure --prefix=/usr --enable-user=root --enable-group=wheel --enable-vtysh --sysconfdir=/etc/quagga --localstatedir=/var/run/quagga --with-cflags=-ggdb --disable-capabilities`
  # `make`
  # `make install`
  # At this point, you should have new binaries/libraries installed in /usr/lib and /usr/sbin.  You can stop and restart your emulation, or manually restart the routing daemons.
 
See also the manual section entitled *Compiling Quagga for CORE*

You can install multiple quagga source trees (for testing purposes) into `/usr/local/src/`.  Then, you can switch between them by just cding into the directory and running `make install` (to overwrite the binaries in /usr/lib and /usr/sbin) and restarting the emulation.  To keep track of which quagga is which, I often edit the `AC_INIT` string in `configure.ac` prior to running `update-autotools` and configure, so that this string shows up in the vtysh output.

= Troubleshooting =

*Problem:* quagga is running, and I can ping across the link, but no neighbor adjacencies are formed.  I see the OSPF hellos in the tcpdump in the sending, but not receiving direction.

*Solution:* Likely, there are default CentOS firewall rules that are blocking the OSPF hellos from reaching the receivers.  Try flushing the firewall rules (e.g., `iptables -F` and `ip6tables -F`.  If turning off all of the firewall rule settings for the host machine is something that bothers you, then you will need to edit the firewall rulesets to add rule(s) to accept packets from all of the CORE virtual interfaces (you will need to consult RH/CentOS documentation on that), and perhaps the physical interfaces if bound to a CORE tap interface, without disturbing the rules for the other host interfaces.