Development VM

Topomate Development VM

You can download an archive containing a VirtualBox VM already set up with required tools to try the project at this link. You only need to extract the .ova from the archive and import it to VirtualBox.

If you want to use your own VM, you will find all the requirements at the end of this page.

VM details and basic commands

The configured used in the VM is topomate (which is also the password and the root password). In the home directory, you'll find the repository already cloned. Don't forget to do a git pull to fetch the latest version ! Everything should be ready to use, you'll find some examples in the examples directory.

Go to the project directory

cd topomate && git pull

Build

go build

Start a topology

./topomate start examples/bgp/4as.yml

Topomate automatically pulls the router image used from DockerHub.

The generated configuration files are stored in ~/topomate with the following name : conf_<ASN>_R<router_num> (i.e. conf_2_R1). If you only want to generate configurations without starting containers, run ./topomate generate <path>.

If you want to re-use already generated configurations (or if you modified them manually), you can use the flag --no-generate.

Stop a topology

./topomate stop examples/bgp/4as.yml

/!\ Warning: topomate isn't stateful so any modifications of the configuration file between start and stop might leave some containers or links running. A simple script is included in tools/cleanup.sh that will remove all existing containers (using a topomate image) and OVS bridges (even if they are not related to topomate).

Restart a container

./topomate restart <container_name>

When topomate creates OVS bridges and veth pairs, it saves the informations in ~/topomate/links.json (it will be overridden if you start multiple topologies at the same time, will be corrected later). These informations are used to recreate the links if you need to restart a container.

Access a running container

You can access a router using the docker exec -it command.

# start a shell in the container (ash, bash, ..)
docker exec -it AS2-R1 bash

# start directly the FRR vtysh
docker exec -it AS2-R1 vtysh

To exit the shell, simply run exit.

Requirements

The following requirements must be met to use topomate :

• Docker and Open vSwitch must be installed
• A working distribution of Golang must be installed (with the GOAPTH correctly setup)
• The user must belong to the sudo and docker groups
• If you want to use MPLS, the required kernel modules must be enabled (see below)

VM modifications

The following modifications were done on the VM (starting from a clean Ubuntu 20.04 install) :

• installation of Docker and Open vSwitch with apt
• installation of Golang using snap
• export of GOPATH and PATH in .bashrc
• enable MPLS kernel modules on startup
• topomate user added to docker group
• repository cloning

Sample script :

#!/bin/bash

apt-get update && apt-get upgrade -y
apt-get install -y docker.io && apt-get install -y openvswitch-switch
snap install --classic --channel=1.14/stable go

echo 'export GOPATH=$HOME/go' >> .bashrc
echo 'export PATH=/snap/bin:$GOPATH/bin:$PATH' >> .bashrc

echo "mpls_router" >> /etc/modules-load.d/modules.conf
echo "mpls_iptunnel" >> /etc/modules-load.d/modules.conf 

usermod -aG docker topomate