demos/gbpsfc-env/README.md

   1 #SETUP
   2
   3 This is a demonstration/development environment for show-casing OpenDaylight GroupBasedPolicy (GBP) with ServiceFunctionChaining (SFC)
   4
   5 This version is using a vagrant box: alagalah/gbpsfc-trusty64 v1.0.1
   6
   7 It is important to ./cleandemo.sh before using. A demo.lock file will be added to repo so that first run will fail unless you ./cleandemo.sh
   8
   9 This is to ensure that each OVS gets a unique UUID as the Box file will re-use the same UUID for each OVS.
  10
  11 After the first time it is very quick.
  12
  13 1. Set up Vagrant.
  14   * Edit env.sh for NUM_NODES. (Keep all other vars the same for this version)
  15   * Each VM takes approximately 1G RAM, 2GB used HDD (40GB)
  16   * demo-gbp1: 3 VMs.
  17   * demo-symmetric-chain: 6 VMs.
  18   * demo-asymmetric-chain: 6 VMs.
  19 2. From the directory you cloned into:
  20 ```
  21 source ./env.sh
  22 vagrant up
  23 ```
  24   * If the starting process fail with '/sbin/mount.vboxsf: mounting failed with the error: No such device' line
  25     (usually occur after first halt) run 'vagrant plugin install vagrant-vbguest' command on host. It should solve the problem.
  26
  27 3. Start controller.
  28   * Currently it is expected that that controller runs on the host hosting the VMs.
  29   * Tested using groupbasedpolicy beryllium
  30                 If you are building and get 'illegal unicode escape' error,
  31                 you have to rename two yang files in 'groupbasedpolicy\ui-backend\src\main\yang'.
  32                 These files have to start with a character other than 'u'.
  33                 E.g. rename 'ui-backend.yang' to 'aui-backend.yang' and 'ui-backend-impl.yang' to 'aui-backend-impl.yang'.
  34   * Start controller by running bin/karaf and install following features in karaf:
  35
  36 ```
  37  feature:install odl-groupbasedpolicy-ofoverlay odl-groupbasedpolicy-ui odl-restconf
  38 ```
  39
  40   * Run `log:tail | grep renderer` and wait until the following message appears in the log:
  41 ```
  42 INFO - OFOverlayRenderer - org.opendaylight.groupbasedpolicy.ofoverlay-renderer - Initialized OFOverlay renderer
  43 ```
  44   * Now you can ^C the log:tail if you wish
  45
  46 #Demos:
  47 * demo-gbp1:
  48   * 8 docker containers in 2 x EPGs (web, client)
  49   * contract with ICMP and HTTP
  50 * demo-symmetry:
  51   * 2 docker containers in 2 x EPGs (web, client)
  52   * contract with ICMP (ALLOW) and HTTP (CHAIN, where Client request is chained, Web reverse path is reverse path of chain)
  53 * demo-asymmetry:
  54   * 2 docker containers in 2 x EPGs (web, client)
  55   * contract with ICMP (ALLOW) and HTTP (CHAIN, where Client request is chained, Web reverse path is ALLOW)
  56
  57 ##demo-gbp1
  58
  59 ###Setup
  60
  61 VMs:
  62 * gbpsfc1: gbp
  63 * gbpsfc2: gbp
  64 * gbpsfc3: gbp
  65
  66 Containers:
  67 * h35_{x} are in EPG:client
  68 * h36_{x} are in EPG:web
  69
  70 To run, from host folder where Vagrantfile located do:
  71
  72 ` ./startdemo.sh demo-gbp1`
  73
  74 After this, `infrastructure_config.py` will be copied from `/demo-gbp1`, and you are ready to start testing.
  75
  76 ###To test:
  77
  78 SSH to test VM (may take some seconds):
  79 ```bash
  80 vagrant ssh gbpsfc1
  81 ```
  82
  83 Get root rights:
  84 ```bash
  85 sudo -E bash
  86 ```
  87
  88 Check docker containers running on your VM:
  89 ```bash
  90 docker ps
  91 ```
  92
  93 Notice there are containers from two different endpoint groups, "h35" and "h36".
  94 Enter into the shell on one of "h36" (web) container (on `gbpsfc1` it will be `h36_4`, its IP is `10.0.36.4`,
  95 you will need it later).
  96 *(You need double ENTER after `docker attach`)*
  97 ```bash
  98 docker attach h36_4
  99 ```
 100
 101 Start a HTTP server:
 102 ```bash
 103 python -m SimpleHTTPServer 80
 104 ```
 105
 106 Press `Ctrl-P-Q` to return to your root shell on `gbpsfc1`
 107
 108 Enter into one of "h35" (client) container,
 109 ping the container where HTTP server runs,
 110 and connect to index page:
 111
 112 *We use eternal loop here to imitate web activity.
 113 After finishing your test, you might want to stop the loop with `Ctrl-C`*
 114 ```
 115 docker attach h35_{x}
 116 ping 10.0.36.4
 117 while true; do curl 10.0.36.4; done
 118 ```
 119
 120 You may `ping` and `curl` to the web-server from any test VM.
 121
 122 `Ctrl-P-Q` to leave back to root shell on VM.
 123
 124 Now watch the packets flow:
 125 ```
 126 ovs-dpctl dump-flows
 127 ```
 128
 129 Leave to main shell:
 130 ```bash
 131 exit #leave root shell
 132 exit #close ssh session
 133 ```
 134 Repeat `vagrant ssh` etc. for each of gbpsfc2, gbpsfc3.
 135
 136 ###After testing
 137
 138 When finished from host folder where Vagrantfile located do:
 139
 140 `./cleandemo.sh`
 141
 142 If you like `vagrant destroy` will remove all VMs.
 143
 144 ##demo-symmetric-chain / demo-asymmetric-chain
 145
 146 VMs:
 147 * gbpsfc1: gbp (client initiates transactions from here)
 148 * gbpsfc2: sff
 149 * gbpsfc3: "sf"
 150 * gbpsfc4: sff
 151 * gbpsfc5: "sf"
 152 * gbpsfc6: gbp (run a server here)
 153
 154 Containers:
 155 * h35_2 is in EPG:client on gbpsfc1
 156 * h36_4 is in EPG:web on gbpsfc6
 157
 158 To run, from host folder where Vagrantfile located do:
 159
 160 ` ./startdemo.sh demo-symmetric-chain` | `demo-asymmetric-chain`
 161
 162 ### To test by sending traffic:
 163 Start a test HTTP server on h36_4 in VM 6.
 164
 165 *(don't) forget double ENTER after `docker attach`*
 166 ```bash
 167 vagrant ssh gbpsfc6
 168 sudo -E docker ps
 169 sudo -E docker attach h36_4
 170 python -m SimpleHTTPServer 80
 171 ```
 172
 173 Ctrl-P-Q to detach from docker without stopping the SimpleHTTPServer, and logoff gbpsfc6.
 174
 175 Now start client traffic, either ping or make HTTP requests to the server on h36_4.
 176
 177 ```bash
 178 vagrant ssh gbpsfc1
 179 sudo -E docker ps
 180 sudo -E docker attach h35_2
 181 ping 10.0.36.4
 182 curl 10.0.36.4
 183 while true; do curl 10.0.36.4; sleep 1; done
 184 ```
 185
 186 Ctrl-P-Q to detach from docker, leaving the client making HTTP requests, and logoff gbpsfc1.
 187
 188
 189 Look around: use "vagrant ssh" to the various machines
 190  * take packet captures on eth1.
 191  * sudo ovs-dpctl dump-flows`
 192
 193 ### When finished from host folder where Vagrantfile located do:
 194
 195 `./cleandemo.sh`
 196
 197 If you like `vagrant destroy` will remove all VMs
 198
 199 ##Preparing to run another demo
 200 1. In the vagrant directory, run cleandemo.sh
 201 2. stop controller (logout of karaf)
 202 3. Remove journal and snapshot directories from controller directory.
 203 4. Restart the controller, install features, wait, as above.
 204
 205
 206 # Useful vagrant plugins
 207
 208 You can install plugins using
 209
 210 ```bash
 211 vagrant plugin install <plugin>
 212 ```
 213
 214 Useful ones are:
 215 vagrant-cachier - faster build times as APT repos cached
 216 vagrant-vbguest - updates VirtualBox Guest Additions versions (if possible)
 217