README.md 5.4 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_routable_ipv6_addrs.py
35 36 37 38 39 40
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
41 42
 - 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
43
 - Use the result of construct_ULAs and the network graph to call add_ULAs_to_hosts
44 45
 - 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
46
 - Use ssh_helper to log out of each host in the network
47

48 49
 Additionally, this library has a method `add_default_routes` which is useful for assigning default routes to edge devices

50
#### 3. frr_configurator.py
51 52 53 54 55 56 57 58 59
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

60 61 62 63 64 65 66 67 68 69
#### 4. osfp_sniffer_configurator.py
Support installing and controlling the OSPF sniffer

The most useful methods are:
  - clone_repo_on_network:    Download a repo, presumably the one which contains the OSPF sniffer code
  - start_sniffer_on_network: Run the OSPF sniffer in the background
    - Starting two sniffers is likely to cause problems, chief among which being the original PID file being overwritten
  - stop_sniffer_on_network:  Kill the OSPF sniffer running in the background
    - If stop is run multiple times, the PID file will be invalid, so there is the unlikely event of another process being assigned the same PID and killed

70 71 72 73 74 75 76 77
#### 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
78 79 80
## TODO
Once this codebase is finished, this section should go away. But great works are never finished, merely abandoned.

81
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
82

83 84
2. Replace `start_all_ovs.sh`
3. Replace `start_all_ospf_monitor.sh`
85 86 87 88 89 90 91 92 93 94 95 96

## 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