umbrella documentation - media.readthedocs.org · umbrella command line interface provides a set of...

Umbrella DocumentationRelease 1.0

Adib Rastegarnia

Apr 17, 2019

Contents:

1 Overview 11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Umbrella Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Getting Started 32.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Run a Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Umbrella APIs 53.1 Flow Service APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 Topology Service APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Umbrella User Interfaces 74.1 Umbrella Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 How to add new commands? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 Sample Applications 95.1 Forwarding Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.2 Firewall Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6 Indices and tables 17

i

CHAPTER 1

Overview

1.1 Introduction

The Northbound (NB) APIs that SDN controllers provide differ in terms of architecture, syntax, naming convention,data resources, and usage. Using NB APIs to write SDN applications makes each application dependent on the APIof a specific controller. To bring NB APIs from different vendors under one umbrella and make programming of SDNapplications independent of specific controllers, we designed and implemented a unified software defined developmentframework that we call Umbrella. The main design goals are as follows:

• Design and implement a development framework that provides a new set of abstractions for SDN applications,keeping the abstractions independent of the NB APIs used by specific SDN controllers.

• Design and implement a set of modules that use the proposed abstractions to provide information needed bySDN applications, such as topology, network statistics, and real time topology changes.

• Increase portability of SDN applications across SDN controllers, and make it easy for a programmer to evaluatea specific application on multiple SDN controllers (e.g., to compare performance).

• Provide a software defined network programming framework that reduces programming complexity, allows aprogrammer to write SDN applications without requiring a programmer to master low-level details for eachSDN controller, and avoids locking an application to a specific controller.

• Provide a framework uses a hybrid approach that utilizes both of reactive and proactive approach for managingand programming of SDN networks that offers better scalability than a completely reactive network manage-ment.

1.2 Umbrella Architecture

We illustrate Umbrella architecture as follows:

1

Umbrella Documentation, Release 1.0

2 Chapter 1. Overview

CHAPTER 2

Getting Started

2.1 Installation

1. First, clone umbrella repository using the following command:

$ git clone https://github.com/umbrella-project/umbrella

2. Umbrella is a Java based platform. In order to be able to compile the code, you need to install Oracle Java 1.8and Maven using the following commands:

$ sudo apt-get install software-properties-common -y && \$ sudo add-apt-repository ppa:webupd8team/java -y && \$ sudo apt-get update && \$ echo "oracle-java8-installer shared/accepted-oracle-license-v1-1 select true" |→˓sudo debconf-set-selections && \$ sudo apt-get install oracle-java8-installer oracle-java8-set-default -y$ sudo apt-get install maven

3. Finally, compile the project using the following command:

$ cd umbrella$ mvn package

2.2 Run a Sample Application

To run an SDN application that we implemented using Umbrella APIs, we can use the following commands:

$ cd umbrella$ mvn package$ java -cp target/umbrella-[Version]-SNAPSHOT-jar-with-dependencies.jar apps.→˓[Application filename]

3


4 Chapter 2. Getting Started

CHAPTER 3

Umbrella APIs

We provide a short descritpion about Umbrella APIs as follows. For more details, please refer to: https://umbrella-project.github.io/umbrella/

3.1 Flow Service APIs

Flow Service APIs provide high level abstractions that can be used by programmers to define and install flow rules onnetwork devices.

3.2 Topology Service APIs

Topology Service APIs provide high level abstractions that can be used by programmers to retrieve topology informa-tion such as list of hosts, network devices, links. In addition, Topology Service APIs also provide a set of path findingalgorithms that can be used to find end-to-end paths between two end points in a network topology.

5

https://umbrella-project.github.io/umbrella/https://umbrella-project.github.io/umbrella/


6 Chapter 3. Umbrella APIs

CHAPTER 4

Umbrella User Interfaces

We provide a short descritpion Umbrella user interfaces as follows:

4.1 Umbrella Command Line Interface

We equipped Umbrella to a command line interface that can be executed as follows:

$ java -cp target/umbrella-1.0-SNAPSHOT-jar-with-dependencies.jar cli.CliMain

We illustrate Umbrella command line interface as follows:

Umbrella command line interface provides a set of commands that can be used for retrieving topology informationsuch as list of hosts, links, and network devices, set logger options, etc. Current version of Umbrella supports thefollowing commands:

Hosts

DESCRIPTION Displays list of the current hosts in the network topology.

SYNTAX hosts

ARGUMENTS NONE

OPTIONS NONE

Links

DESCRIPTION Displays list of the current links in the network topology.

7


SYNTAX links

ARGUMENTS NONE

OPTIONS NONE

Devices

DESCRIPTION Displays list of the current network devices in the network topology.

SYNTAX devices

ARGUMENTS NONE

OPTIONS NONE

Topo

DESCRIPTION Displays all topology information such as list of hosts, links, and network devices.

SYNTAX topo

ARGUMENTS NONE

OPTIONS NONE

Setlog

DESCRIPTION Sets java log4j logger level (e.g. DEBUG, INFO, WARN, . . . )

SYNTAX setlog

ARGUMENTS NONE

OPTIONS

-l –level set log level

4.2 How to add new commands?

To add a new command, we need to define a java class under cli package which implements a Runnable as follows:

@CommandLine.Command(name = "commandName", header = "%n@|color Command Description|@")class newCommand implements Runnable {

// Command Line options and arguments (For more information, please refer to http://→˓picocli.info/)

public void run() {

// Logic behind the new command.

}}

8 Chapter 4. Umbrella User Interfaces

CHAPTER 5

Sample Applications

5.1 Forwarding Application

Suppose we would like to write an application to route traffic between all of the hosts that belong to the same subnet.To achieve this goal, we implement an application using Umbrella APIs to generate and install appropriate forwardingrules on the switches between each two hosts. We explain step by step how to write the mentioned application:

1. First, we need to create an instance of the controller that we would like to execute our application on. Weassume that the name of controller is stored in a config file (i.e. config.properties) and we use it to initialize thecontroller.

String controllerName;Controller controller = null;ConfigService configService = new ConfigService();controllerName = configService.getControllerName();controller = configService.init(controllerName);

2. Second, we need to get the list of current hosts that have been detected by the controller.

Set srchosts = controller.getHosts();Set dsthosts = controller.getHosts();

3. Third, we need to do the following steps:

• We compute shortest path between each two hosts to determine which network switches should be config-ured between the given hosts.

• We generate flow rules based on source and destination MAC addresses, source and destination IP ad-dresses, and Ethernet type (IPv4 in this example).

• Finally, we install generated flow rules on determined network switches.

for(TopoHost srcHost: srchosts){

for(TopoHost dstHost: dsthosts)(continues on next page)

9


(continued from previous page)

{if(!srcHost.equals(dstHost)){

String srcMac = srcHost.getHostMac();String dstMac = dstHost.getHostMac();

path = controller.getShortestPath(srcHost.getHostID(),dstHost.getHostID());

controller.printPath(path);

for(TopoEdge edge : path) {

if(edge.getType() == TopoEdgeType.HOST_SWITCH) {continue;

}

FlowMatch flowMatch = FlowMatch.builder().ethSrc(srcMac).ethDst(dstMac).ipv4Src(srcHost.getHostIPAddresses().get(0)).ipv4Dst(dstHost.getHostIPAddresses().get(0)).ethType(2048).build();

FlowAction flowAction = new FlowAction(FlowActionType.OUTPUT,Integer.parseInt(edge.getSrcPort()));

ArrayList flowActions = new ArrayList();flowActions.add(flowAction);

Flow flow = Flow.builder().deviceID(edge.getSrc()).tableID(0).flowMatch(flowMatch).flowActions(flowActions).priority(1000).appId("TestForwarding").timeOut(300).build();

controller.flowService.addFlow(flow);}

}}

}

5.1.1 Testing the Forwarding Application on ONOS controller

• In this section, we explain a Mininet simulation scenario that can be used to test the forwarding application onONOS controller:

1. First, you need to install and run ONOS on your local machine using the guidelines that have been posted onONOS website: ONOS GUIDES

10 Chapter 5. Sample Applications

https://wiki.onosproject.org/display/ONOS/Guides


2. Second, you need to download and install Mininet using the guidelines that have been posted on Mininet website:Mininet

3. Third, execute the following commands to run a Mininet simulation scenario that simulates tree topology with8 hosts:

$ sudo mn --topo tree,depth=2,fanout=2 --controller=remote,ip=127.0.0.1,port=6653

4. Forth, run pingall to detect all of the hosts in the network topology. ONOS runs a reactive forwarding applicationby default.

4. Fifth, package umbrella source codes using the following command:

$ mvn package

5. Finally, execute the application using the following command to install rules on network switches:

$java -cp target/umbrella-1.0-SNAPSHOT-jar-with-dependencies.jar apps.Forwarding

5.1.2 Testing the Forwarding Application on OpenDayLight controller

1. First, you need to install and run ONOS on your local machine using the guidelines that have been posted onONOS website: ODL GUIDES


3. Third, execute the following commands to run a Mininet simulation scenario that simulates a tree topology with8 hosts:

$ sudo mn --topo tree,depth=2,fanout=2 --controller=remote,ip=127.0.0.1



$ mvn package


$java -cp target/umbrella-1.0-SNAPSHOT-jar-with-dependencies.jar apps.Forwarding

5.2 Firewall Application

• Suppose we would like to implement a simple firewall application to enforce the following access control policyfor a network topology that all of the hosts belong to the same subnet.

H1 (10.0.0.1) (H2) 10.0.0.2 (H3) 10.0.0.3 H4(10.0.0.4)H1(10.0.0.1) NONE DENY WEB DENYH2(10.0.0.2) DENY NONE DENY PINGH3(10.0.0.3) WEB DENY NONE DENYH4(10.0.0.4) DENY PING NONE NONE

5.2. Firewall Application 11

http://mininet.org/download/http://docs.opendaylight.org/en/stable-oxygen/getting-started-guide/installing_opendaylight.htmlhttp://mininet.org/download/


• To achieve that goal, we implement an application using Umbrella APIs to generate and install appropriateforwarding rules on the switches between each pair of hosts: (h1,h3) and (h2, h4). We explain step by step howto write the mentioned application:

First, we need to create an instance of the controller that we would like to execute our application on. We assume thatthe name of controller is stored in a config file (i.e. config.properties) and we use it to initialize the controller.

String controllerName;Controller controller = null;ConfigService configService = new ConfigService();controllerName = configService.getControllerName();controller = configService.init(controllerName);

2. Second, we need to get the list of currents hosts and find a shortest path for each pair of hosts: (h1, h3) and(h2,h4).

3. Third, we generate appropriate match-action fields for each pair of hosts based on the type of traffic which isspecified in the table above. For the pair (h1, h3), we should use source and destination TCP ports (i.e. port 80for web traffic) to route web traffic and for the pair (h2, h4) we should use ICMP type and code match fields(i.e. type=8 (echo request), type=0 (echo reply) and code=0) to route ICMP traffic. Note that for both types oftraffic, we also use source and destination MAC addresses, source and destination IP addresses, Ethernet type,and IP protocol number as the match fields.

Set srchosts = controller.topoStore.getHosts();

ArrayList hosts = new ArrayList(srchosts);

List fwPath = null;List rvPath = null;

for (TopoHost srcHost: hosts) {for (TopoHost dstHost: hosts) {

if(!srcHost.equals(dstHost)){

String srcMac = srcHost.getHostMac();String dstMac = dstHost.getHostMac();

String srcIP = srcHost.getHostIPAddresses().get(0);String dstIP = dstHost.getHostIPAddresses().get(0);

fwPath = controller.topoStore.getShortestPath(srcHost.getHostID(), dstHost.→˓getHostID());

rvPath = controller.topoStore.getShortestPath(dstHost.getHostID(), srcHost.→˓getHostID());

if ((srcIP.equals("10.0.0.1") && dstIP.equals("10.0.0.3"))|| (srcIP.equals("10.0.0.3") && dstIP.equals("10.0.0.1"))) {

FlowMatch flowMatch = null;

for (TopoEdge edge : fwPath) {

if (edge.getType() == TopoEdgeType.HOST_SWITCH) {continue;

}

(continues on next page)




flowMatch = FlowMatch.builder().ethSrc(srcMac).ethDst(dstMac).ipv4Src(srcHost.getHostIPAddresses().get(0) + "/32").ipv4Dst(dstHost.getHostIPAddresses().get(0) + "/32").ethType(2048).ipProto(6).tcpDst(80).build();



Flow flow = Flow.builder().deviceID(edge.getSrc()).tableID(0).flowMatch(flowMatch).flowActions(flowActions).priority(100).appId("Firewall").timeOut(100).build();

controller.flowService.addFlow(flow);

}

// Reverse Path

for (TopoEdge edge : rvPath) {


}

flowMatch = FlowMatch.builder().ethSrc(dstMac).ethDst(srcMac).ipv4Src(dstHost.getHostIPAddresses().get(0) + "/32").ipv4Dst(srcHost.getHostIPAddresses().get(0) + "/32").ethType(2048).ipProto(6).tcpSrc(80).build();



Flow flow = Flow.builder()(continues on next page)




.deviceID(edge.getSrc())

.tableID(0)

.flowMatch(flowMatch)

.flowActions(flowActions)

.priority(100)

.appId("Firewall")

.timeOut(100)

.build();


}

}

if ((srcIP.equals("10.0.0.2") && dstIP.equals("10.0.0.4"))|| (srcIP.equals("10.0.0.4") && dstIP.equals("10.0.0.2"))) {

FlowMatch flowMatch = null;

for (TopoEdge edge : fwPath) {


}

flowMatch = FlowMatch.builder().ethSrc(srcMac).ethDst(dstMac).ipv4Src(srcHost.getHostIPAddresses().get(0) + "/32").ipv4Dst(dstHost.getHostIPAddresses().get(0) + "/32").ipProto(0x01).ethType(2048).icmpv4_code(0x0).icmpv4_type(0x08).build();




(continues on next page)





}// Reverse Path

for (TopoEdge edge : rvPath) {


}

flowMatch = FlowMatch.builder().ethSrc(dstMac).ethDst(srcMac).ipv4Src(dstHost.getHostIPAddresses().get(0) + "/32").ipv4Dst(srcHost.getHostIPAddresses().get(0) + "/32").ipProto(0x01).ethType(2048).icmpv4_code(0x0).icmpv4_type(0x0).build();





}

}

}}



5.2.1 Testing the Forwarding Application on ONOS controller

• In this section, we explain a Mininet simulation scenario that can be used to test the forwarding application onONOS controller:

1. First, you need to install and run ONOS on your local machine using the guidelines that have been posted onONOS website: ONOS GUIDES


3. Third, execute the following commands to run a Mininet simulation scenario that simulates a leaf-spine networktopology with 6 hosts:

$ cd mininet_examples$ sudo mn --topo tree,depth=2,fanout=2 --controller=remote,ip=127.0.0.1,port=6653



$ mvn package


$java -cp target/umbrella-1.0-SNAPSHOT-jar-with-dependencies.jar apps.Firewall

5.2.2 Testing the Forwarding Application on OpenDayLight controller

1. First, you need to install and run ONOS on your local machine using the guidelines that have been posted onONOS website: ODL GUIDES


3. Third, execute the following commands to run a Mininet simulation scenario that simulates a leaf-spine networktopology with 6 hosts:

$ cd mininet_examples$ sudo mn --topo tree,depth=2,fanout=2 --controller=remote,ip=127.0.0.1,port=6653



$ mvn package


$java -cp target/umbrella-1.0-SNAPSHOT-jar-with-dependencies.jar apps.Firewall


https://wiki.onosproject.org/display/ONOS/Guideshttp://mininet.org/download/http://docs.opendaylight.org/en/stable-oxygen/getting-started-guide/installing_opendaylight.htmlhttp://mininet.org/download/

CHAPTER 6

Indices and tables

• genindex

• modindex

• search

17

OverviewIntroductionUmbrella Architecture

Getting StartedInstallationRun a Sample Application

Umbrella APIsFlow Service APIsTopology Service APIs

Umbrella User InterfacesUmbrella Command Line InterfaceHow to add new commands?

Sample ApplicationsForwarding ApplicationFirewall Application

Indices and tables

umbrella documentation - media.readthedocs.org · umbrella command line interface provides a set of...

Documents