#############################################################################
###
### SDNS: a prototype SDN controller to interact with the DNS in order to set 
### up communication in federated networks using any IP addresses plan.
###
### This software has been developed by Habib Mostafaei, Andrea Brandimarte,
### and Roberto di Lallo, within the research line described at
### http://www.dia.uniroma3.it/~compunet/www/view/topic.php?id=sdn
###
### Last update: 9 January 2017
###
#############################################################################

This file describes how to run our controller. Netkit includes all required 
pieces of software to carry out such experiments, including: OpenVSwitch, Ryu, 
and Bind. We provide the backbone configuration to run SDNS controller, as well 
as two scripts to execute the simulations. The first script allows the user to 
create topologies with a custom number of end-hosts (sources and destinarions). 
The second script allows the user to send traffic in the network and tests the 
behavior of our controller.

=== GETTING STARTED ===
To run SDNS, you must download the SDNS controller from this link:

http://www.dia.uniroma3.it/~compunet/sdn/sdns/SDNS-controller.zip

Unzip the file into a folder and then move into that folder (SDNSlab). Now you 
can run the lab by running the following command:

$ lstart -p4 --pass=--append=root=98:0

** NOTE: in order to be able to run all machines correctly with NetKit it is 
suggested to set "VM_MEMORY=128" in $NETKIT_HOME/netkit.conf file. Generally, 
we suggest to run the lab on a machine with at least  6GB of RAM, especially to 
run lab with more than 20 hosts per customer.

To run a simulation, the following steps are needed:

1. Adding hosts to the lab. You can do by running the command

   $ ./createHosts.sh

   The execution of this script creates two customers (each connected to an 
   ISP's network) with 2 hosts inside each customers (instructions on how to 
   create larger topologies are inside README-customizations.txt file). Also, 
   this script takes care to suitable configure the BIND instance of the name 
   servers.

2. Run the lab

   Now, the lab is ready to run in NetKit. To do that, run the command:

   $ lstart --pass=--append=root=98:0

   Alternatively, if you want to run the lab in parallel, you can use -p4 
   option privided by NetKit.

   $ lstart -p4 --pass=--append=root=98:0

3. After running the lab, you have to do a manual setting on ce1 and ce2, in 
   order to populate the ARP cache of those machines with the correct 
   association between the IP and MAC addresses of sw1 and sw2 respectively 
   (our controller does not handle ARP traffic in this prototype version).
   To do that, the following steps are needed:

  3.1 Inside sw1 Netkit virtual machine, run the command:

      sw1@ ip a s

      This command prints information about the interfaces of the machines. We 
      are interested to the MAC addresses.

  3.2 Inside ce1 Netkit virtual machine, run the command:

      ce1@ arp -s 10.1.0.2 "MAC address of eth0 of sw1"

  3.3 Inside sw2 Netkit virtual machine, run the command:

      sw2@ ip a s

      This command prints information about the interfaces of the machines. We 
      are interested to the MAC addresses.

  3.4 Inside ce2 Netkit virtual machine, run the command:

      ce2@ arp -s 20.1.0.13 "MAC address of eth1 of sw2"

4. Configure Ryu to run our controllers:

   To run SDNS you have to modify a little bit the Ryu source code. Inside 
   each virtual machine running an instance of SDNS controller (controller1 and 
   controller2 Netkit virtual machines), you have to modify the file  
   /opt/ryu/flags.py. To do that, the following steps are needed:

   4.1 Inside controller1 Netkit virtual machine, run the command:

       controller1@ vi /opt/ryu/flags.py

   4.2 Press the "i" button to enter the VIM's insertion mode and add the 
       line (without quotas)

       "cfg.StrOpt(‘federated’),"

       immediately below the line 

       "CONF.register_cli_opts(["

   4.3 Exit from VIM's insertion mode by pressing "ESC" button followed by 
       the sequence ":wq"

   4.4 Press "Enter" to save.

   4.5 Inside controller2 Netkit virtual machine, run the command:

       controller2@ vi /opt/ryu/flags.py

   4.6 Press the "i" button to enter the VIM's insertion mode and add the 
       line (without quotas)

       "cfg.StrOpt(‘federated’),"

       immediately below the line 

       "CONF.register_cli_opts(["

   4.7 Exit from VIM's insertion mode by pressing "ESC" button followed by 
       the sequence ":wq"

   4.8 Press "Enter" to save.

5. Collecting traffic to the OpenFlow devices.
   As said in the paper, our controller only interacts with the DNS. The 
   experiments carried out in the paper are based on collecting traffic at the 
   OpenFlow switches. To do that, the following steps are needed (we exploit 
   the screen software to open multiple terminals inside the same Netkit 
   virtual machine).

   5.1 Inside sw1 Netkit virtual machine, run the commands:

       sw1@ screen

       sw1@ tcpdump -nli eth0 -w /hosthome/sw1-eth0.pcap

   5.2 Open a new screen inside the Netkit virtual machine by pressing 
       the combination of buttons "CTRL+a c"

   5.3 Inside the new opened terminal, run the command:

       sw1@ tcpdump -nli eth1 -w /hosthome/sw1-eth1.pcap

   5.4 Open a new screen inside the Netkit virtual machine by pressing 
       the combination of buttons "CTRL+a c"

   5.5 Inside the new opened terminal, run the command:

       sw1@ tcpdump -nli eth2 -w /hosthome/sw1-eth2.pcap

   5.6 Repeat the above steps inside sw2 Netkit virtual machine, suitably 
       changing the names of the pcap files in the tcpdump command line.

6. Run the controllers.

   5.1 Inside controller1 Netkit virtual machine, run the commands:

       controller1@ cd /hostlab/controllers/SDNS/

       controller1@ ryu-manager --federated conf/system_dns_c1_alg1.conf main.py

   5.2 Inside controller2 Netkit virtual machine, run the commands:

       controller2@ cd /hostlab/controllers/SDNS/

       controller2@ ryu-manager --federated conf/system_dns_c2_alg1.conf main.py

   The controllers are now running and you can do the tests. The instructions 
   reported above will start "Full configuration" approach. If you want to run 
   the "Partial configuration" approach, you can change the configuration files 
   provided as input for the controllers with system_dns_c1_alg2.conf and 
   system_dns_c2_alg2.conf.

   ** NOTE: in this prototype version of SDNS, we used a configuration language 
            that is slightly different from that described in the paper. 
            Nevertheless, the semantic is exactly the same.

6. Test our controllers:

   To test our controllers you can start to perform queries from one end-host 
   in a customer to an end host residing in the other customer. For example, 
   if you want to query h2.c2.isp2.it from h1, you can type inside h1 the 
   following command:

   h1@ ping -c1 h2.c2.isp2.it.

   If you want to print all end hosts in the destination customer, you can 
   exploit the "generatePing.sh" script. Before runnig this script you have to 
   customize one parameter. In this file the variable "HostCount" determines 
   how many end-hosts you want to ping inside the destination customer. 
   The variable "C" determines which is the target customer to run the DNS 
   queries. For instance, you want to query the end hosts of customer 2 from 
   customer one, you have to set "C=2".

   To query all end hosts with this script you have to enter the console of end-
   hosts on each customer and type the following command. Suppose that from h1 
   of customer 1, we want to query all end hosts of customer 2. The command is:

   h1@ cd /hostlab

   Now, you are in the lab directory of NetKit and you have access to all files 
   inside this directory. To execute the DNS queries type;

   h1@ ./generatePing.sh

   It starts to query the end hosts of customer 2 and provides the proper DNS 
   answer for each end host.

7. You can see relevant results by inspecting the content of the pcap files 
   issued by tcpdump and by checking the console of the two controllers.

8. Before stopping the lab, you have to stop all tcpdump instances running on 
   sw1 and sw2. To do that:

   8.1 Inside sw1 Netkit virtual machine, kill the first running tcpdump 
       instance by pressing "CRTL+c".

   8.2 Move through the opened screen by pressing the combination of button
       "CTRL+a p" (p stands for previous) or "CTRL+a n" (n stands for next)
       and kill all other tcpdump instances as described in 8.1.

   Do the same for sw2 Netkit virtual machine.

9. Now, you can stop the lab by running the command:

   $ lcrash (or lhalt).

====IMPORTANT NOTE======
Note that if you want to run the two approaches without stopping the lab, you 
have to restart the bind daemon inside ns1 and ns2. Indeed, after running one 
of the two approaches the DNS cache prevents further DNS requests towards the 
same destinations to be processed by the SDN controllers. To avoid this 
situation, run the following commands:

1. Inside ns1

   ns1@ /etc/init.d/bind restart

2. Inside ns2

   ns2@ /etc/init.d/bind restart

Also, if you destroy the lab (by using the lcrash or lhalt Netkit commands), 
before running a new one you have to:

1. clean part of the lab.conf file, by removing all lines below the 
   line "ns2[0]=P", namely the lines referring to hosts configuration;

2. clean the BIND configuration files of ns1 and ns2:

   2.1 move into SDNSlab/ns1/etc/bind/ and open the file db.it.isp1.ns1

   2.2 remove all lines below the line "ns1		IN	A	10.0.0.3", namely all 
       lines referring to the association among hosts domain names and their 
       IP addresses

   2.1 move into SDNSlab/ns2/etc/bind/ and open the file db.it.isp2.ns2

   2.2 remove all lines below the line "ns2		IN	A	10.0.0.3", namely all 
       lines referring to the association among hosts domain names and their 
       IP addresses