tutorials/l2switch/README.md

   1 # Vagrant Tutorial Environment
   2
   3 Vagrant is a tool for managing virtual machines. As compared to binary VM blobs, Vagrant has the
   4 advantage that all configuration is clearly defined in a lightweight Vagrantfile. Feel encouraged to
   5 browse the included L2Switch tutorial Vagrantfile to understand the tutorial environment.
   6
   7 To use Vagrant to stand up the tutorial environment, you'll need to install a virtualization
   8 provider like [VirtualBox][1] or [LibVirt][2], and then [install Vagrant][3].
   9
  10 Once you have Vagrant installed, clone the tutorials:
  11
  12 ```
  13 git clone https://git.opendaylight.org/gerrit/integration/packaging
  14 cd packaging/tutorials/l2switch
  15 ```
  16
  17 From the directory with the tutorial Vagrantfile, start the VM and do all provisioning:
  18
  19 ```
  20 vagrant up
  21 ```
  22
  23 After the VM boots, you can optionally connect via SSH and explore:
  24
  25 ```
  26 vagrant ssh
  27 sudo dnf info opendaylight
  28 sudo systemctl status opendaylight
  29 ssh -p 8101 karaf@localhost
  30 ```
  31
  32 You can always destroy the VM and start again:
  33
  34 ```
  35 vagrant destroy -f
  36 vagrant up
  37 ```
  38
  39 # Accessing the DLUX GUI
  40
  41 All OpenDaylight configuration is handled by the tutorial's Vagrantfile, so after starting
  42 the tutorial VM with `vagrant up` you can access ODL's web GUI, called DLUX.
  43
  44 Open `http://127.0.0.1:8181/index.html` in a browser on your host machine to access DLUX.
  45
  46 Login to DLUX with username `admin` and password `admin`.
  47
  48 ![DLUX GUI login page][4]
  49
  50 Note that after starting ODL via `vagrant up`, it may take a few minutes for the DLUX Karaf
  51 features to load and start serving up the GUI.
  52
  53 # Mininet
  54
  55 Mininet is a network testing tool that is often used by network architects to emulate network
  56 topologies and test them virtually before real-world deployment.
  57
  58 ## Sample Mininet Topology
  59
  60 By default, the Vagrantfile builds a sample topology consisting of 4 switches, each connected to
  61 a single host.
  62
  63 ```
  64 sudo mn --mac --topo=linear,4 --controller=remote,ip=127.0.0.1 --switch=ovsk,protocols=OpenFlow13
  65 ```
  66
  67 ![Linear Topology][5]
  68
  69 ## Custom Mininet Topologies
  70
  71 Mininet supports the creation of Single, Tree and 2-D Torus topologies.
  72
  73 Let us take a look at some examples of mininet topologies built using basic mininet topology commands:
  74
  75 - Single Topology
  76
  77 A single topology consists of a single switch connected to a number of hosts as specified in the
  78 topology build command. Here, we are using a single topology with 3 hosts connected to the switch.
  79
  80 ```
  81 sudo mn --mac --topo=single,3 --controller=remote,ip=127.0.0.1 --switch=ovsk,protocols=OpenFlow13
  82 ```
  83
  84 ![Single Topology][6]
  85
  86 - Tree Topology
  87
  88 Let us take a look at the DLUX UI page using a tree topology with depth=2 and fanout=3. In a tree
  89 topology, a fanout value corresponds to the number of switches the central switch gets connected to.
  90 The fanout value also determines the number of hosts that get connected to every other edge switch.
  91 The depth parameter allows the edge switches to further branch out with the same fanout value
  92 as specified.
  93
  94 ```
  95 sudo mn --mac --topo=tree,depth=2,fanout=3 --controller=remote,ip=127.0.0.1 --switch=ovsk,protocols=OpenFlow13
  96 ```
  97
  98 ![Tree Topology][7]
  99
 100 - Torus Topology
 101
 102 The Torus topology is a network topology used for connecting nodes in a parallel computer system.
 103 This topology is used in supercomputers to decrease communication latency. The additional ‘3’ settings
 104 in the Torus topology syntax refer to the size of the topology namely the size of the rectilinear
 105 array with 3, 3 analogous to 3 rows and 3 columns.
 106
 107 ```
 108 sudo mn --mac --topo=torus,3,3 --controller=remote,ip=127.0.0.1 --switch=ovsk,protocols=OpenFlow13
 109 ```
 110
 111 ![Torus Topology][8]
 112
 113 The parameters mentioned in the above commands are used for the following functions:
 114
 115 - `sudo mn`: Initializes the Mininet console.
 116 - `--mac`: Allocates host MAC addresses equivalent to their IP addresses.
 117 - `--topo`: Tells Mininet to start using the specified topology.
 118 - `--controller`: Specifies that each switch must talk to the controller that is located at a remote location.
 119 - `--switch`: Tells Mininet that the switches are of type OVSK.
 120 - `protocols`: Defines the protocol version for the switch to use.
 121
 122 ## Basic Mininet CLI Operations
 123
 124 One you build the topology, you will gain access into the Mininet CLI.
 125
 126 To Display Mininet CLI commands:
 127
 128 ```
 129 mininet> help
 130 ```
 131
 132 To Display all elements in the network:
 133
 134 ```
 135 mininet> nodes
 136 ```
 137
 138 To Display a list of links:
 139
 140 ```
 141 mininet> net
 142 ```
 143
 144 To dump information about all nodes:
 145
 146 ```
 147 mininet> dump
 148 ```
 149
 150 # OpenDaylight DLUX GUI
 151
 152 The Open**D**ay**l**ight **U**ser **E**xperience (DLUX) project provides a web-based GUI for
 153 OpenDaylight, including the ability to visualize network typologies managed by the L2Switch
 154 project.
 155
 156 As with all OpenDaylight projects, DLUX is installed by loading its Karaf feature. In the tutorial
 157 Vagrantfile, note the line that connects to ODL's Karaf shell and runs:
 158
 159 ```
 160 feature:install odl-l2switch-switch-ui
 161 ```
 162
 163 This installs DLUX, as well as the Karaf bundles required by L2Switch.
 164
 165 DLUX uses ODL's northbound REST API to pull and display information from ODL's MD-SAL database,
 166 which is populated by southbound protocol plugins like OpenFlow.
 167
 168 [1]: https://www.virtualbox.org/wiki/Downloads "VirtualBox downloads page"
 169
 170 [2]: https://github.com/vagrant-libvirt/vagrant-libvirt "Vagrant LibVirt plugin GitHub"
 171
 172 [3]: https://www.vagrantup.com/downloads.html "Vagrant downloads page"
 173
 174 [4]: https://s31.postimg.org/6gdu7vnq3/imageedit_4_7787538837.png "ODL DLUX GUI login page screenshot"
 175
 176 [5]: https://s32.postimg.org/jlw4hphzp/imageedit_2_3952319201.png "ODL DLUX GUI showing Mininet linear topo"
 177
 178 [6]: https://s32.postimg.org/w1subgbbp/imageedit_4_2391309779.png "ODL DLUX GUI showing Mininet single topo"
 179
 180 [7]: https://s32.postimg.org/kt33ock8l/imageedit_2_5298056244.png "ODL DLUX GUI showing Mininet tree topo"
 181
 182 [8]: https://s32.postimg.org/bvpcckfo5/imageedit_6_6305541411.png "ODL DLUX GUI showing Mininet torus topo"