Route 0
Route 0 is a suite for learning about and experimenting with routing protocols.
It uses the Free Range Routing (FRR) protocol
implementations running on top of a network setup locally using
Mininet.
This project was inspired by Vimal Kumar's BGP hijacking
demo from the Mininet
Wiki.
Introduction
Motivation
Mininet is a great tool for teaching, learning, and
experimenting
with networking. However, there was no coherent framework to use which would
let one use Mininet to setup a network running an entire set of routing
protocols. A small example that demonstrated BGP
hijacking
has existed for a while and showed that this is possible, but there isn't much
more beyond that on case.
The FRR project actually uses Mininet for running topology
tests, but that
makes them difficult to learn from and experiment with. As somebody looking
for resources to learn about configuring networks to play with on my own
computer that seemed like a big gap.
Finally, there are lots of resources online for learning the theory of how
networks are connected to each other and how routing works on the Internet, but
very few of them come with any practical examples. It is one thing to learn
the concepts and a completely different thing to apply them in a practical real
world scenario. Route 0 was made to address this issue as well.
Purpose
The primary purpose of Route 0 is to provide a framework for learning how
routing works all the way from setting up IP addresses on individual interfaces
up to setting up BGP peering sessions between multiple autonomous systems and
setting up VPN tunnels. Therefore, the primary audience are people new to
networking. However, even if you already know some routing basics you might
still find some of the examples valuable. The repository is structured such
that you can start from any point you like.
A secondary purpose is to provide an experimental testbed in which a network
running a whole stack of routing protocols can be quickly designed,
provisioned, and brought up on a single computer (mostly thanks to Mininet).
Getting Started
Platform
For the best experience it is recommended to run Route 0 experiments using the
Virtual Machine (VM) image developed specifically for this project.
- Download the ova file.
- In VirtualBox select
File->Import Appliance, select the downloaded ova
file and then confirm all the settings. You may adjust the settings, but
the defaults will work just fine. - Start the Virtual Machine.
- (Optional) For a better experience install the VirtualBox Guest Additions.
Instructions on how to do that can be found
here.
The account user name is route0 and the password (needed for sudo commands)
is also route0.
If you would prefer to set up your own environment, you can follow these
instructions. They describe the steps needed to produce the
exact same VM image available above.
Note that the VM does not come with the route0 repository. This is because
the repository will be updated much more frequently than the VM image. You
will still need to clone route0 into an appropriate directory on the VM. To
do so run the following command in a terminal in the VM
git clone https://github.com/Wojtek242/route0.git
Note that both Mininet and FRR are developed primarily for Linux so if you have
a different operating system you will have to use some form of virtualisation.
With some effort (and limitations) you might be able to get things running on
other Unix-like systems, but that is undocumented.
Lessons
The lessons in this repository are aimed to take somebody who knows nothing
about IP routing all the way to setting up networks with multiple autonomous
systems and VPN tunnels. The lessons are structured in such a way that the
reader must first manually setup and configure the network before moving on to
the next step. Each stage starts at a point that can be automatically
provisioned by Route 0 and the purpose of each lesson is to explain how this
automation is achieved through network configuration. This particular
structure also means that it is possible to dive in at any point making it
suitable for people with more experience as well.
The table of contents with links to all the lessons can be found in the
lessons directory.
Running an experiment
If you just want to get started, choose a topology from the topology
directory, and a scenario from the scenario directory within. Note that all
topologies support plain and basic in addition to the explicitly defined
scenarios. The meaning of these special scenarios is explained in the section
on scenarios.
Once you have chosen <topology_name> and <scenario_name> you can run an
experiment with the following command from the project directory
sudo python route0.py --topology <topology_name> --scenario <scenario_name>
Connecting to an FRR daemon
To connect to an FRR daamon, you can either run the following command inside
the Mininet CLI
noecho <node_name> telnet localhost <daemon_name>
You can also connect to an FRR daemon from a different terminal than the one in
which the Mininet CLI is running. To do this run
sudo python attach.py --node <node_name> --daemon <daemon_name>
The password for all daemons is route0.
Mininet Concepts
This section will introduce some basic Mininet concepts that are in particular
useful for Route 0. For more information, please refer to the Mininet
documentation.
Mininet is a framework for creating virtual networks running real kernel,
switch, and application code. In Route 0 it is used to provide the
virtualisation necessary to run multiple routing nodes on a single computer.
Mininet handles the topology setup before dropping the user in its own special
CLI.
The CLI is self-documented and help can be accessed by running help. To
investigate the current topology, you can run net. To visualise the output
of this command, you can copy and paste it into this web
tool.
A particularly useful feature of the CLI is the ability to run shell commands
on any of the nodes in the network. To do this, simply run
<node_name> <shell_command>
such as R1 ip address. This is particularly useful in Route 0 for commands
like ip address or ip route. Additionally, it is possible to use this
feature to send pings between nodes, for example, R1 ping 10.0.0.1.
Normally, in Mininet the destination can also be specified using its name. It
is possible to do so in Route 0, but this is often ambiguous as routers will
have multiple IP addresses associated with their interfaces.
It is also possible to launch a shell or run a command in a Mininet node from a
different terminal than the one in which the Mininet CLI is being run. A
convenience script has been provided for this purpose, attach.py. To launch
a shell on a particular node run
sudo python attach.py --node <node_name>
You can also directly specify the daemon to connect to with --daemon or a
shell command to run with --cmd.
The password for all daemons is route0.
FRR Concepts
This section will introduce some basic FRR concepts that are in particular
useful to understand for Route 0. For more information, please refer to the
FRR documentation.
FRR is a set of routing protocols with each running in its own daemon. In
addition, there is a central IP routing manager, zebra, which must be run
before any other routing daemon is started. All other routing protocols talk
to zebra which in turn will talk to the operating system kernel to install
routes as appropriate.
FRR routing protocols are configured using configuration files. The details of
how to write these configurations are on the FRR documentation
website. It is also possible to connect
to a shell on running instances of the protocols and configure it from there.
See the Mininet and Getting Started sections on how this can be done.
Structure
There are three key concepts in the Route 0 framework: topology, scenario, and
experiment.
Topology
A topology defines the nodes and links that form the network. Additionally it
also determines the default IP address assignments and any static routes which
are initialised using the zebra and staticd daemons.
Each topology has its own directory in the topology directory. Every
topology directory must contain a topo.py file which defines a NetTopo
class. The topology itself is defined in the constructor of this class using
the Mininet API.
A README.md should be provided with each topology that has a schematic
diagram of the topology and lists all the default IP address assignments. It
is assumed that hosts have a default route setup to the router they connect to
and that routers do not have default routes.
Scenario
A scenario is a particular configuration of FRR protocols on the provided
topology. While the topology defines which nodes and links form the network,
the scenario determines which protocols get started on which nodes and their
configuration.
There are two special scenarios: plain and basic. The plain scenario
starts the network without any daemons so only the Mininet topology is set up,
but no IP addresses or default routes are created. The basic scenario
additionally starts up zebra and staticd to configure addresses and default
routes.
Scenarios are defined for a particular topology and thus they can be found in
the scenario directory within the topology directories. Each scenario
(excluding the special ones) should have a directory in the scenario
directory. Within the particular scenario directory, each daemon that is to be
run must have a its own directory. The configuration files should be created
in the appropriate daemon directory with the name <node_name>.conf.
Scenarios may also have an optional scenario.py file for a given scenario in
which a script function should be defined. This function is then run after
Mininet and FRR are started and just before handing control over to the user.
The zebra and staticd daemons are special and have their own directories
directly in the topology directory. If a scenario has its own zebra and/or
staticd directory, these will be used preferentially, but otherwise the
topology's ones will be used. Note that if no zebra and/or staticd daemon
is to be run then the scenario must have empty zebra and/or staticd
directories within its scenario directory. Note all FRR protocols rely on
zebra to function correctly.
Experiment
An experiment is simply a particular topology and scenario combination.
Technically this is redundant since scenarios are strictly associated with only
one topology, but using different terminology avoids confusion.
Configuration files
The official FRR documentation recommends using only a single configuration
file frr.conf per router. This makes sense if we are only running a single
instance of each protocol on the device as then all the configuration is in one
place. Route 0 does not do that. Using a single configuration file would mean
that a lot of options would need to be repeated between different scenarios,
especially for zebra and staticd.
Furthermore, separating the config files makes it easier for the python scripts
to know which daemons to start (though of course it could just start all of
them every time or use some additional configuration file).
Finally, one last advantage of the Route 0 configuration model for our use case
is that the we group configurations per protocol, not per device. This makes
no sense if you're running only one instance of a protocol on a given device,
but since we are running multiple instances on multiple virtual nodes on a
single physical device, it makes it easier to inspect and compare the
configurations on a protocol level.
End-host configuration files
It's not entirely normal to run FRR daemons on end-hosts. However, they still
need their IP address and default route configured and the options are to do it
either from a Python script or use FRR daemons. Using the FRR zebra and
staticd daemons makes it easier to configure the end-hosts together with the
actual routers. However, they should not be running any daemon other than
zebra and staticd.
A note on VTY shell
The recommended way of connecting to daemons by FRR is to use the VTY
shell which can connect to all
the daemons simultaneously. Unfortunately, in our configuration where multiple
instances of the same daemon run on the same machine in Mininet, it gets
confused and it doesn't connect as expected. Therefore, you can't use the VTY
shell with Route 0.
Contributing
For information on how to contribute see CONTRIBUTING.
Name
I am terrible at coming up with names so I'll at least explain myself. The
word "Route" was chosen due to its dual meaning. A route is naturally a
central concept in networking, but in every day English it simply means a path,
a track, a road. This repository is a tutorial, a road to learning about
routing protocols, hence it is a "Route". The number 0 is used to indicate
that this is the first route one would take in their networking education.