Merge pull request #25 from netgroup/documentation

Improve project documentation and add docs to the topologies

Author: cscarpitta

README.md

@@ -1,5 +1,41 @@
 # SRv6 tutorial
 
+> Mininet topologies for SRv6
+
+![Python Linter](https://github.com/netgroup/rose-srv6-tutorial/workflows/Python%20Linter/badge.svg)
+![Shell Linter](https://github.com/netgroup/rose-srv6-tutorial/workflows/Shell%20Linter/badge.svg)
+![Python package](https://github.com/netgroup/rose-srv6-tutorial/workflows/Python%20package/badge.svg)
+![GitHub](https://img.shields.io/github/license/netgroup/rose-srv6-control-plane)
+
+## Table of Contents
+* [Overview](#overview)
+* [Installation](#installation)
+    * [Installation of Mininet](#installation-of-mininet)
+    * [Installation of FRRouting suite (FRR)](#installation-of-frrouting-suite-frr)
+    * [Installation of Python dependencies](#installation-of-python-dependencies)
+* [Starting a topology](#starting-a-topology)
+* [Requirements](#requirements)
+* [Links](#links)
+* [Issues](#issues)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Overview
+
+This project contains several Mininet topologies:
+
+    .
+    ├── nets
+    |   ├── 8routers-isis-ipv6
+    |   └── 8r-1c-in-band-isis
+    ├── nets-in-progress
+    |   └── 8r-1c-srv6-pm
+    ├── nets-unmantained
+    |   ├── 3routers
+    |   ├── 8routers
+    |   └── 8r-1c-out-band-isis
+    └── README.md
+
 In the nets folder there are different projects:
 
 ```
@@ -18,9 +54,31 @@ reference IPv6 topology with IS-IS / FRR and out-of-band controller
 - 8r-1c-in-band-isis
 reference IPv6 topology with IS-IS / FRR and in-band controller
 
+- 8r-1c-srv6-pm
+reference IPv6 topology with IS-IS / FRR and out-of-band controller, used for SRv6 Performance Measurement experiments
+
 ```
 
-## Installation of FRRouting suite (FRR)
+## Installation
+
+This project depends on:
+  * Mininet
+  * FRRouting suite
+  * Other Python packages listed in requirements.txt
+
+### Installation of Mininet
+
+Check if Mininet is installed by running:
+```
+$ /usr/bin/mn --version
+```
+
+If Mininet is not installed, run the install command (for Ubuntu/Debian):
+```
+$ sudo apt-get install mininet
+```
+
+### Installation of FRRouting suite (FRR)
 
 You need to have FRR installed in order to run the mininet labs.
 Check if FRR is installed by running:
@@ -50,4 +108,44 @@ replacing <release> with the output of lsb_release -s -c
 
 7) sudo apt -y install frr frr-pythontools
 
+### Installation of Python dependencies
+
+The Python packages required to run the Mininet labs are listed in *requirements.txt*. You can install them with the following command:
+```
+$ pip install -r requirements.txt
+```
+
+
+## Starting a topology
+
+In order to start a Mininet topology `cd` to the topology folder and run the Python script.
+
+For instance,
+```
+$ cd nets/8routers-isis-ipv6/
+$ python isis8d.py
+```
+
+For more information, check the documentation contained in the topology folders.
+
+
+## Requirements
+Python >= 3.6
+
+
+## Links
+* Research on Open SRv6 Ecosystem (ROSE): https://netgroup.github.io/rose/
+* Source code: https://github.com/netgroup/rose-srv6-tutorial
+* Report a bug: https://github.com/netgroup/rose-srv6-tutorial/issues
+
+
+## Issues
+You are welcome to open github issues for bug reports and feature requests, in [this repository](https://github.com/netgroup/rose-srv6-tutorial/issues) or in the [ROSE repository](https://github.com/netgroup/rose/issues).
+
+
+## Contributing
+If you want to contribute to the ecosystem, provide feedback or get in touch with us, see our contact page: https://netgroup.github.io/rose/rose-contacts.html.
+
 
+## License
+This project is licensed under the [Apache License, Version 2.0](https://github.com/netgroup/rose-srv6-tutorial/blob/master/LICENSE).

nets-in-progress/8r-1c-srv6-pm/README.md

@@ -1,15 +1,32 @@
-# 1920-srv6-tutorial
+# 8r-1c-srv6-pm Topology
 
-SMART INTRODUCTION LINK ---> https://drive.google.com/file/d/18PumHFw6o3df5-_yPtOVw4Zem8RDEjTr/view?usp=sharing
+A Mininet topology with 8 routers running IS-IS routing protocol, 12 hosts, 3 datacenters and a controller connected out-band to all the routers and hosts of the network.
 
+This topology is the same as 8r-1c-out-band, but same nodes are configured to run Performance Measurement experiments.
+
+## Topology overview
+
+![Alt Topology](docs/images/topology.png)
+
+## Start the topology
+
+To start the topology:
+```
+python isis8d.py
+```
+
+## Description
 
 ```text
 
 In folder nodeconf/ 
-	- for each host and router one folder
+	- for each host, datacenter, router and  controller one folder
 	- host folders contain start.sh for each host
 		- sets IPv6 address for hosts
 		- adds IPv6 routing to gateway
+	- datacenter folders contain start.sh for each datacenter
+		- sets IPv6 address for datecenters
+		- adds IPv6 routing to gateway
 	- router folders contain 
 		- zebra.conf
 			- sets for each interface the IPv6 address
@@ -18,16 +35,16 @@ In folder nodeconf/
 		- start.sh
 			- enables IPv6 forwarding
 			- executes zebra.conf and isisd.conf
+	- the controller folder contains start.sh
+		- sets IPv6 address for the controller
+	- some routers are configured to run Performance Measurement experiments
 
 
 
 
 network:
 the network is shown in this link
-https://docs.google.com/presentation/d/15w14n_Nf5rE560FluMnw4Wq51pYLvDqG1kEwDvmEHE0/edit#slide=id.g76160fda07_0_0
-
-and also in this link
-https://drive.google.com/file/d/1yzyfgvgWbzPjTttcqA4G41gEGM87tHC5/view?usp=sharing
+https://docs.google.com/presentation/d/15w14n_Nf5rE560FluMnw4Wq51pYLvDqG1kEwDvmEHE0/edit#slide=id.g7752c9e8cd_5_88
 
 
 
@@ -49,6 +66,12 @@ host - router links:
 	h82 - r8: fd00:0:82::2/64	r8 - h82: fd00:0:82::1/64
 	h83 - r8: fd00:0:83::2/64	r8 - h83: fd00:0:83::1/64
 
+datacenter - router links:
+
+	hdc1 - r2: fcff:2:1::2/48	r2 - hdc1: fcff:2:1::1/48
+	hdc2 - r8: fcff:8:1::2/48	r8 - hdc2: fcff:8:1::1/48
+	hdc3 - r5: fcff:5:1::2/48	r5 - hdc3: fcff:5:1::1/48
+
 router - router links:
 	
 	r1 -r2: fcf0:0:1:2::1/64	r2 - r1: fcf0:0:1:2::2/64
@@ -61,6 +84,21 @@ router - router links:
 	r6 -r7: fcf0:0:6:7::1/64	r7 - r6: fcf0:0:6:7::2/64
 	r6 -r8: fcf0:0:6:8::1/64	r8 - r6: fcf0:0:6:8::2/64
 	r7 -r8: fcf0:0:7:8::1/64	r8 - r7: fcf0:0:7:8::2/64
+
+controller - switch links:
+
+	controller - sw: fcfd:0:0:fd::1/48	sw - controller: fcfd:0:0:fd::2/48
+
+router - switch links:
+
+	r1 - sw: fcfd:0:0:1::1/48	sw - r1: fcfd:0:0:1::2/48
+	r2 - sw: fcfd:0:0:2::1/48	sw - r1: fcfd:0:0:2::2/48
+	r3 - sw: fcfd:0:0:3::1/48	sw - r1: fcfd:0:0:3::2/48
+	r4 - sw: fcfd:0:0:4::1/48	sw - r1: fcfd:0:0:4::2/48
+	r5 - sw: fcfd:0:0:5::1/48	sw - r1: fcfd:0:0:5::2/48
+	r6 - sw: fcfd:0:0:6::1/48	sw - r1: fcfd:0:0:6::2/48
+	r7 - sw: fcfd:0:0:7::1/48	sw - r1: fcfd:0:0:7::2/48
+	r8 - sw: fcfd:0:0:8::1/48	sw - r1: fcfd:0:0:8::2/48
 	
 router localhost
 
@@ -75,6 +113,27 @@ router localhost
 
 ( The addressing plan is explained in https://docs.google.com/document/d/15giV53fH_eDuWadOxzjPVzlr-a7Rn65MpCbz9QKs7JI/edit )
 
+Note that datacenters are special hosts, which have a public address.
+
+
+The file etc-hosts in the topology folder maps each IP address to its hostname.
+
+For example,
+fcff:1::1       r1
+fd00:0:11::2    h11
+fcff:2:1::2     hdc1
+fcfd:0:0:fd::1	controller.m		# .m suffix is used for the management addresses
+...
+
+When you start the topology, the entries defined in this file are loaded and added to the system /etc/hosts file.
+
+This allows you to ping the nodes using their hostnames instead of the IP addresses:
+h11# ping6 h83
+h83# ping6 h11
+
+The entries are automatically removed from the /etc/hosts file when the emulation is stopped.
+
+
 ------Tunnel examples -------------
 1) Create a bidirectional tunnel between h11 and h83, passing through router r4
 
@@ -277,6 +336,17 @@ GW_ADDR=fd00:0:11::1
 ip -6 addr add $IP_ADDR dev $IF_NAME 
 ip -6 route add default via $GW_ADDR dev $IF_NAME
 
+----Configuration of the Controller----
+
+The controller has a configuration file called start.sh in which we set the IP address. Since the controller is connected to the other nodes through a switch, the gateway is not required.
+
+NODE_NAME=controller
+SW_NAME=sw
+IF_NAME=$NODE_NAME-$SW_NAME
+IP_ADDR=fcfd:0:0:fd::1/48
+
+ip -6 addr add $IP_ADDR dev $IF_NAME
+
 ----Addressing----
 
 the addressing on the links between the hosts hxy and the router x can be

nets-in-progress/8r-1c-srv6-pm/docs/images/topology.png

@@ -1,16 +1,30 @@
-# 1920-srv6-tutorial
+# 8r-1c-out-band-isis Topology
 
-SMART INTRODUCTION LINK ---> https://drive.google.com/file/d/18PumHFw6o3df5-_yPtOVw4Zem8RDEjTr/view?usp=sharing
+A Mininet topology with 8 routers running IS-IS routing protocol, 12 hosts, 3 datacenters and a controller connected out-band to all the routers and hosts of the network.
 
+## Topology overview
+
+![Alt Topology](docs/images/topology.png)
+
+## Start the topology
+
+To start the topology:
+```
+python isis8d.py
+```
+
+## Description
 
 ```text
 
 In folder nodeconf/ 
-	- for each host and router one folder
-	- one folder for the controller
+	- for each host, datacenter, router and  controller one folder
 	- host folders contain start.sh for each host
 		- sets IPv6 address for hosts
 		- adds IPv6 routing to gateway
+	- datacenter folders contain start.sh for each datacenter
+		- sets IPv6 address for datecenters
+		- adds IPv6 routing to gateway
 	- router folders contain 
 		- zebra.conf
 			- sets for each interface the IPv6 address
@@ -19,7 +33,7 @@ In folder nodeconf/
 		- start.sh
 			- enables IPv6 forwarding
 			- executes zebra.conf and isisd.conf
-	- controller folder contains start.sh
+	- the controller folder contains start.sh
 		- sets IPv6 address for the controller
 
 
@@ -49,6 +63,12 @@ host - router links:
 	h82 - r8: fd00:0:82::2/64	r8 - h82: fd00:0:82::1/64
 	h83 - r8: fd00:0:83::2/64	r8 - h83: fd00:0:83::1/64
 
+datacenter - router links:
+
+	hdc1 - r2: fcff:2:1::2/48	r2 - hdc1: fcff:2:1::1/48
+	hdc2 - r8: fcff:8:1::2/48	r8 - hdc2: fcff:8:1::1/48
+	hdc3 - r5: fcff:5:1::2/48	r5 - hdc3: fcff:5:1::1/48
+
 router - router links:
 	
 	r1 -r2: fcf0:0:1:2::1/64	r2 - r1: fcf0:0:1:2::2/64
@@ -64,18 +84,18 @@ router - router links:
 
 controller - switch links:
 
-	controller - sw: fcfd:0:0:fd::1/48
+	controller - sw: fcfd:0:0:fd::1/48	sw - controller: fcfd:0:0:fd::2/48
 
 router - switch links:
 
-	r1 - sw: fcfd:0:0:1::1/48
-	r2 - sw: fcfd:0:0:2::1/48
-	r3 - sw: fcfd:0:0:3::1/48
-	r4 - sw: fcfd:0:0:4::1/48
-	r5 - sw: fcfd:0:0:5::1/48
-	r6 - sw: fcfd:0:0:6::1/48
-	r7 - sw: fcfd:0:0:7::1/48
-	r8 - sw: fcfd:0:0:8::1/48
+	r1 - sw: fcfd:0:0:1::1/48	sw - r1: fcfd:0:0:1::2/48
+	r2 - sw: fcfd:0:0:2::1/48	sw - r1: fcfd:0:0:2::2/48
+	r3 - sw: fcfd:0:0:3::1/48	sw - r1: fcfd:0:0:3::2/48
+	r4 - sw: fcfd:0:0:4::1/48	sw - r1: fcfd:0:0:4::2/48
+	r5 - sw: fcfd:0:0:5::1/48	sw - r1: fcfd:0:0:5::2/48
+	r6 - sw: fcfd:0:0:6::1/48	sw - r1: fcfd:0:0:6::2/48
+	r7 - sw: fcfd:0:0:7::1/48	sw - r1: fcfd:0:0:7::2/48
+	r8 - sw: fcfd:0:0:8::1/48	sw - r1: fcfd:0:0:8::2/48
 	
 router localhost
 
@@ -90,6 +110,27 @@ router localhost
 
 ( The addressing plan is explained in https://docs.google.com/document/d/15giV53fH_eDuWadOxzjPVzlr-a7Rn65MpCbz9QKs7JI/edit )
 
+Note that datacenters are special hosts, which have a public address.
+
+
+The file etc-hosts in the topology folder maps each node to its hostname.
+
+For example,
+fcff:1::1       r1
+fd00:0:11::2    h11
+fcff:2:1::2     hdc1
+fcfd:0:0:fd::1	controller.m		# .m suffix is used for the management addresses
+...
+
+When you start the topology, the entries defined in this file are loaded and added to the system /etc/hosts file.
+
+This allows you to ping the nodes using their hostnames instead of the IP addresses:
+h11# ping6 h83
+h83# ping6 h11
+
+The entries are automatically removed from the /etc/hosts file when the emulation is stopped.
+
+
 ------Tunnel examples -------------
 1) Create a bidirectional tunnel between h11 and h83, passing through router r4
 
@@ -292,6 +333,17 @@ GW_ADDR=fd00:0:11::1
 ip -6 addr add $IP_ADDR dev $IF_NAME 
 ip -6 route add default via $GW_ADDR dev $IF_NAME
 
+----Configuration of the Controller----
+
+The controller has a configuration file called start.sh in which we set the IP address. Since the controller is connected to the other nodes through a switch, the gateway is not required.
+
+NODE_NAME=controller
+SW_NAME=sw
+IF_NAME=$NODE_NAME-$SW_NAME
+IP_ADDR=fcfd:0:0:fd::1/48
+
+ip -6 addr add $IP_ADDR dev $IF_NAME
+
 ----Addressing----
 
 the addressing on the links between the hosts hxy and the router x can be