README.md 5.04 KB
Newer Older
Simon Redman's avatar
Simon Redman committed
1
This repository contains everything needed to run the segment routing demo on Emulab. More details to come as code is actually written.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

## Setup
Since the code in this repository is written in Python, there is no need to compile anything, but the environment must first be setup. This only needs to be done once.

1. First, make sure you have the Python 3 virtualenv command installed. In Ubuntu 16.04 and Fedora, the package is called python3-virtualenv.
2. Set up the virtual environment by running the command `virtualenv-3 env` from within the folder containing this repository
3. Populate the virtual environment using the provided list of requirements:
```
source env/bin/activate # Activate the environment
pip install -r requirements.txt # Use pip to install required packages
```
You are now set up!

## Usage
These instructions will be updated as the code is actually written

Before you will be able to run any commands, activate the virtual environment by running `source env/bin/activate`
19

20 21 22 23 24
`orchestrator.py` automatically does everything required, and can be run directly on an Emulab node to parse
the on-node net information or can be fed a NetJSON NetGraph to configure. Please refer to `orchestrator --help`

## Library Documentation

25
#### 1. topomap_parser.py
26
This is both a program which can be run on its own, mostly for testing purposes, and a library which is used by the following programs to parse emulab's topology into [NetJSON](netjson.org) NetworkGraph for usage with the NetworkX network graph library.
27 28 29 30

When used as a library, the most interesting method is `parse_topomap_to_netjson`, which returns a NetJSON-formatted dictionary. When run standalone, the program has built-in help by passing the `--help` flag.

The topology is parsed using the information in `/var/emulab/boot/topomap` to get basic information, and management IP addresses are found using DNS records. In many situations, topomap_parser will only properly work if run on one of the nodes of an experiment.
Simon Redman's avatar
Simon Redman committed
31

32 33
For description of the non-standard fields used, see the NetworkGraph section of this document

34
#### 2. add_quagga_user.py
35
This is an executable library which has a single method: `add_quagga_user_to_network`, which SSHes to every requested host and adds a user named `quagga`.
36 37

This script is useless in the current configuration since the proper user (actually `frr`) is baked into the Emulab disk image and comes from installing the frr package
38 39 40 41 42 43 44 45

#### 3. add_routable_ipv6_addrs.py
This is an executable library which provides several methods for gathering the necessary information to construct IPv6 Unique Local Addresses, construct them, and push them to the hosts

The suggested usage is:

 - Construct a NetJSON NetworkGraph using topomap_parser
 - Use the [netdiff](https://github.com/ninuxorg/netdiff) library to convert the NetJSON to a networkx graph
46 47
 - Use ssh_helper to log in to each host in the network and annotate the graph with logged-in sessions
 - Use the netgraph to call construct_ULAs
48
 - Use the result of construct_ULAs and the network graph to call add_ULAs_to_hosts
49 50
 - Use the result of construct_ULAs to call add_interfaces_to_netgraph to add the interfaces and the associated IPv6 addresses to the NetGraph
    - This adds an `interfaces` property to the nodes in the graph which maps the (Linux) interface name to the ULA IPv6 address
51
 - Use ssh_helper to log out of each host in the network
52

53 54 55 56 57 58 59 60 61 62
#### 4. frr_configurator.py
This is an executable library which supports configuring and managing FRR (Free Range Routing)

All methods in this library expect to be run on a NetGraph which has been annotated with the `interfaces` field by `add_routable_ipv6_addrs`

The most useful methods are:
  - configure_nodes: Configure and enable zebra and ospf6d
  - start_frr_on_network: Start frr on all nodes in the network
  - stop_frr_on_network: Stop frr on all nodes in the network

63 64 65 66 67 68 69 70
#### 5. sysctl_configurator.py
This is an executable library which supports running sysctl commands

The only currently required command enables IPv6 segment routing

Everything can be automatically accomplished by the configure_nodes method


Simon Redman's avatar
Simon Redman committed
71 72 73
## TODO
Once this codebase is finished, this section should go away. But great works are never finished, merely abandoned.

74
The basic goal is to take all the scripts from <https://gitlab.flux.utah.edu/safeedge/sripv6-linux> and convert them to not assume anything about the experiment topology
Simon Redman's avatar
Simon Redman committed
75

76 77 78
1. Replace `install_default_route_on_hosts.sh`
2. Replace `start_all_ovs.sh`
3. Replace `start_all_ospf_monitor.sh`
79 80 81 82 83 84 85 86 87 88 89 90

## NetworkGraph
For the most part, standard NetJSON NetworkGraph fields are used, and those are documented [here](http://netjson.org/rfc.html#rfc.section.4)

At the top-level, no optional fields are defined. This may change in the future to add human-relevant information

Each Node defines the following properties:
 - 'lans': A mapping of Emulab LANs a Node is connected to and its IP address on that lan
 - 'management-ip': A single remote-accessible IP or hostname

Each Link defines the following properties:
 - 'netmask': The netmask of the Emulab LAN which corresponds to this link