Floodlight开发者文档(译文).doc

目录

架构 3
开始 3
安装指导 3
概述 3
准备工作 3
下载编译 3
运行Floodlight 4
Eclipse设置 4
虚拟一个网络 4
下一步 5
可兼容交换机 5
虚拟交换机 5
硬件交换机 5
可支持的拓扑结构 6
发布版 8
发行说明 8
Floodlight v0.9发行说明 8
概述 8
新添加的东西 8
应用 9
用户文档 9
控制器 9
Configuration HOWTO 9
监听地址和端口配置 10
Floodlight REST API 11
应用 18
开发者文档 28
模块描述及javadoc 28
控制器模块 28
FloodLight目前已经实现的控制器模块 28
FloodlightProvider 28
DeviceManagerImpl 30
LinkDiscoveryManager (Dev) 32
TopologyService 33
RestApiServer 34
ThreadPool 35
MemoryStorageSource 36
Flow Cache 36
Packet Streamer 37
应用模块 41
虚拟网络过滤器（Quantum插件） 41
转发 43
防火墙 44
Port Down Reconciliation 49
模块加载系统 50
Javadoc entry 55
添加模块 57
创建一个监听模块 57
Mininet虚拟网络连接floodlight 63
添加模块服务 63
创建类 65
添加rest API 70
Floodlight rest API开发 76
Floodlight-Test 77
Unit测试 85
控制器基准配置 86
基准配置 86
Cbench (New) 87
怎样用floodlight满足服务质量 88

92

架构
Floodlight不仅仅是一个支持OpenFLow协议的控制器（FloodlightCOntroller），也是一个基于Floodlight控制器的应用集。
当用户在OpenFLow网络上运行各种应用程序的时候，Floodlight控制器实现了对OpenFLow网络的监控和查询功能。图0.0显示了Floodlight不同模块之间的关系，这些应用程序构建成java模块，和Floodlight一起编译。同时这些应用程序都是基于REST API的。
开始
安装指导
概述
基于Java的Floodlight可以用标准jak工具或ant编译运行，当然也可以有选择性的在Eclipse上运行。
准备工作
Linux：
l Ubuntu 10.04（Natty）及以上版本（运行Ant1.8.1及以下版本）
l 安装JDK，Ant。（可在eclipse上安装）
$sudo apt-get install build-essential default ant python-dev eclipse
Mac
l Mac系统x10.6及以上版本（低版本未测试）
l Cxode4.1或Xcode4.0.2
l JDK:只需要在终端输入命令：‘javac’便可安装
l Eclipse（非必须 ）

下载编译
从Github下载并比编译Floodlight
$git clone git://
$cd floodlight
$ant

运行Floodlight
如果java运行环境已经安装成功，就可以直接运行：
$java -jar target/floodlight.jar

Floodlight就会开始运行，并在控制台打印debug信息
Eclipse设置
通过Eclipse运行、开发、配置Floodlight：
$ant eclipse
上述命令将创建多个文件：Floodlight.launch,Floodlight_junit.launch,classpath和.project。通过这些设置eclipse工程
l 打开eclipse创建一个新的工程
l 文件->导入->常规->现有项目到工程中->下一步
l 点击“选择根目录”，点击“浏览”。选择之前放置Floodlight的父路径
l 点击Floodlight
l 点击“完成”
现在就产生了一个Floodlight的Eclipse工程。由于我们是使用静态模块加载系统运行Floodlight，我们必须配置eclipse来正确的运行Floodlight。
创建Floodlight目标文件:
l 点击运行->运行配置
l 右击java 应用->新建
l “Name”使用“FloodlightLaunch”
l “Project”使用“Floodlight”
l “Main”使用“net.floodlightcontroller.core.Main”
l 点击“应用”

虚拟一个网络
启动了Floodlight之后，就需要链接到一个OpenFlow的网络。Mininet是最好的网络虚拟工具之一。
l 下载Floodlight-vm机自启动并内嵌Mininet工具。
l 使用Vmware或者virtualbox打开Floodlight-vm，在启动之前，点击网络选项不要从导入虚拟机后的安装目录中运行脚本启动
l 登录（用户名是：floodlight没有密码）
l 既可以在使用Floodlight-vm开机自启动的Floodlight控制器也可以通过命令指定到远程的控制器，输入：
$sudo mn --controller=remote,ip=,port=

可以通过ssh远程登陆到floodlight-vm虚拟机运行wireshark，监听eth0端口并用“of”协议过滤器过滤。
$ssh -X floodlight@
$sudo wireshark

下一步
阅读完getstart文档之后，可以参阅floodlight开发文档，里面有很多实例和代码。

可兼容交换机
下面列出了可以和Floodlight控制器兼容的交换机
虚拟交换机
l Open vSwitch（OVS）
硬件交换机
· Arista 7050
· Brocade MLXe
· Brocade CER
· Brocade CES
· Dell S4810
· Dell Z9000
· Extreme Summit x440, x460, x670
· HP 3500, 3500yl, 5400zl, 6200yl, 6600, and 8200zl (the old-style L3 hardware match platform)
· HP V2 line cards in the 5400zl and 8200zl (the newer L2 hardware match platform)
· Huawei openflow-capable router platforms
· IBM 8264
· Juniper (MX, EX)
· NEC IP8800
· NEC PF5240
· NEC PF5820
· NetGear 7328SO
· NetGear 7352SO
· Pronto (3290, 3295, 3780) - runs the shipping pica8 software

可支持的拓扑结构
Floodlight现在在支持梁中锋不同的包转发应用，这两种应用具有不同的行为，并且向下图的拓扑结构一样运行：
l 在转发方面：在网络中的任意两个终端设备之间进行端到端的数据转发
内含OpenFLow网络孤岛（OpenFlow island）：到同一OpenFlow网络孤岛中的任意一设备A发送数据包到设备B，转发模块会计算出A到B之间的最短路径。
内含非OpenFlow网络孤岛（non-OpenFlow island）的OpenFLow网络孤岛：每一个OpenFlow网络孤岛都可能有一个连接到非OpenFlow孤岛的链接。另外，如图3所示，OpenFlow和非OpenFlow网络孤岛之间不能构成环网

图1：Floodlight接入OpenFlow网络的例网拓扑

图2：Floodlight未接入OpenFlow网络的例网拓扑，OpenFlow网络孤岛1有两个到非OpenFlow网络孤岛的链接

图3：Floodlight未接入OpenFlow网络的例网拓扑，OpenFlow孤岛和非OpenFlow孤岛形成了一个环网，甚至每一个OpenFlow孤岛都有唯一一个连接到非OpenFlow孤岛的链接

l 当转发路径中超过指定的时间间隔（默认5秒），通过转发超时安装路径。
l 自我学习的交换机：一个简单的二层自我学习交换机：
①　 在任何数量的OpenFlow网络孤岛中使用，甚至在非OpenFlow的2层网络孤岛中。
②　 不能在环路网路中的网络孤岛中工作，也不能在孤岛形成的环网中工作
③　 数据转发效率远高于其他方法
l 另外，Floodlight也提供一个Static Flow Entry Pusher应用和一个Circuit Pusher应用，允许用户主动安装转发路径（proactively install forwarding paths）的行为
①　 Static Flow Entry Pusher允许修改交换机流表项，从而创造由用户根据交换机端口明确选择的转发路径
②　 CircuitPusher是基于Static Flow Entry Pusher，Device Manager，Routing services的RestAPI，在单个OpenFlow孤岛中建立一个最短路径流

*术语“孤岛”和“集群”是可以互换使用的。一个OpenFlow孤岛/集群就是OpenFlow交换机连接到其中任何设备的集合。类似的，非OpenFlow的孤岛/集群就是任何连接到非OpenFlow交换机的设备。

发布版
发行说明
Floodlight v0.9发行说明
发布日期：2012年10月
概述
Floodlighr v0.9包含了控制器新的RestAPI，新的应用，漏洞修复，新框架测试等
新添加的东西
REST APIs
显示如何进行外部连接，通过BDDP发现多跳链路而不是LLDP

由于处理错误的API并不在发布包中，但是可以通过纯净版的Floodlight下载页面或者在github上的Floodlight-master下载获得。
· /wm/topology/external-links/json
显示在LLDP数据包中发现的直连（DIRECT）和隧道链接（TUNNEL）
· /wm/topology/links/json
给OpenStack/quantum插件的虚拟网络过滤器添加新的API，以显示所有的创建的虚拟网络名，Guid，网关和主机
· /quantum/v1.0/tenants//networks
应用
l Circuit Pusher，一个基于Python的REST应用接口，使用RESTAPI来设置两台IP主机的流。包括新的REST APIs
l Firewall，一个java应用模块，提供基于控制器的无状态ACL支持
用户文档
控制器
Floodlight不仅仅是一个支持OpenFLow协议的控制器（FloodlightCOntroller），也是一个基于Floodlight控制器的应用集。
当用户在OpenFLow网络上运行各种应用程序的时候，Floodlight控制器实现了对OpenFLow网络的监控和查询功能。图0.0显示了Floodlight不同模块之间的关系，这些应用程序构建成java模块，和Floodlight一起编译。同时这些应用程序都是基于REST API的。
当运行floodlight时，控制器和一组java应用模块（这些会在floodlight属性文件中载入）开始运行。REST API通过REST端口（默认8080）对所有的运行中的模块开放。
Configuration HOWTO
选择加载模块
Floodlight可以配置载入不同的模块以适应不停地应用。配置不同的载入模块之后必须重启生效。目前对于Floodlight模块的配置都是通过需在启动时加载的一个配置文件的修改实现的。
简单的说，用户可以通过以下步骤，找到或控制Floodlight当前的配置:
l 打开 src/main/resources/META-INF/services/net.floodlightcontroller.core.module.IFloodlightModule文件，就可以查看所有在floodlight.jar二进制编译中的模块编译。
l 打开src/main/resources/floodlightdefault.properties文件或者其他自定义属性文件，查看文件中选择加载/运行模块。这些文件时是配置某些启动时参数的地方，例如：REST API服务和WEB UI端口（8080）、交换机连接OpenFlow端口（6633）、默认的超时值等。
n 如果在Eclipse或命令行（java -jar floodlightjar）运行Floodlight，默认情况下加载默认属性文件。详细情况可以查看程序参数包括 -cf some_properties_file文件。
n 如果在Floodlight-vm上运行的Floodlight，floodlight.jar是按照 /opt/floodlight/floodlight/configuration/floodlight.properties instead of floodlightdefault.properties文件，作为服务载入
n 如果需要修改默认值，停止Floodlight，更新以上所说的属性文件并重启。
l 如果自定义新的模块更新上述的两个文件并重启生效。
虽然大多数的应用都是按照默认属性配置运行，但是下面的应用程序需要一组特定的模块，因此需要一个特定的配置文件（由于某些模块之间不兼容）来运行。
l OpenStack Quantum plugin：需要和src/main/resources/quantum.properties文件一起运行
l Forwarding和StaticFlowEntryPusher：这两个模块都是默认加载的
，但有时你只需要加载其中的一个来实现应用程序的功能。例如，你想要一个完全自动配置的网络并且不会有转发反应，因此只需要StaticFlowEntryPusher模块而禁止Forwarding模块。

控制日志级别
在控制台显示的调试信息有时是很有帮助的，但有时又会显得十分繁杂。Floodlight使用org.slf4j.Logger模块，将日志信息划分不同的等级。同时，日志等级是可控的。在默认情况下，Floodlight显示了所有的日志等级。为了控制日志等级，可以向JVM传递以下参数：
java -Dlogback.configurationFile=logback.xml -jar floodlight.jar
如果实在Eclipse下运行的Floodlight，点击运行->运行/调试配置->参数->VM参数，在这里添加 -Dlogback.configurationFile=logback.xml
Xml文件已经包含在Floodlight根目录中。

%level [%logger:%thread] %msg%n

el="WARN"/>

在这个例子中，net,floodlightcontroller包含了所有的floodlight模块，并且具有日志记录级别的信息，因此调试信息并不会出现在控制台中。你可以在logxml文件中指定INFO，WARN和DEBUG的级别。
监听地址和端口配置
为了改变主机地址或监听特定服务的端口号，可以在属性配置文件中使用以下的配置参数：
net.floodlightcontroller.restserver.RestApiServer.host
net.floodlightcontroller.restserver.RestApiServer.port
net.floodlightcontroller.core.internal.FloodlightProvider.openflowhost
net.floodlightcontroller.core.internal.FloodlightProvider.openflowport
net.floodlightcontroller.jython.JythonDebugInterface.host
net.floodlightcontroller.jython.JythonDebugInterface.port
默认的属性配置文件（例如：floodlightdefault.properties）

Floodlight REST API

虚拟网络过滤器的REST API

URI
方法
URI 参数
数据
数据作用域
描述
/networkService/v1.1/tenants/{tenant}/networks/{network}
PUT/
POST/
DELETE
Tenant:暂时忽略Network:网络ID（非网络名）
{"network": { "gateway": "", "name": "" }}\
IP:点分十进制的网关IP,可以为空
Name:字符串形式的网络名
创建一个新的虚拟网络，ID和name是必须的但是网关是可选的。
/networkService/v1.1/tenants/{tenant}/networks/{network}/ports/{port}/attachment
PUT/
DELETE
Tenant: Currently ignored
Network: The ID (not name) of the network
Port: Logical port name
{"attachment": {"id": "", "mac": ""}}
Network ID: 字符串形式的刚刚创建的网络的ID
MAC:点分十进制的MAC地址
给虚拟网络添加主机
/networkService/v1.1/tenants/{tenant}/networks
GET
Tenant: Currently ignored
None
None
以json形式显示所有的网络的网络名、ID、网关，所有主机的MAC地址

Curl使用样例
创建一个名字是“VirtualNetwork1”的虚拟网络，ID是“Networkid1”，网关是“10.0.0.7”，tenant是“默认”（目前是忽略的）：
curl -X PUT -d '{ "network": { "gateway": "10.0.0.7", "name": "virtualNetwork1" } }' http://localhost:8080/networkService/v1.1/tenants/default/networks/NetworkId1

添加一个主机到VirtualNetwork1，MAC地址为“00:00:00:00:00:08”端口为“port1”
curl -X PUT -d '{"attachment": {"id": "NetworkId1", "mac": "00:00:00:00:00:08"}}' http://localhost:8080/networkService/v1.1/tenants/default/networks/NetworkId1/ports/port1/attachment

StaticFlow Pusher API（新）

什么是Static Flow Pusher？
Static Flow Pusher是Floodlight的一个模块，通过REST API形式向外曝露，这个接口允许用户手动向OpenFlow网络中插入流表。

主动和被动流插入
OpenFlow支持两种流插入方式：主动式和被动式。当数据包到达OpenFlow交换机但未成功匹配流表时发生被动式流表插入。这个数据包将会被发送到控制器，控制器对数据包进行分析评估，添加相应的流表并允许交换机继续该数据包的转发。另外，也可以在数据包到达交换机之前，控制器可以主动地插入相应流表。
Floodlight支持这两种的流表插入方式。Static Flow Pusher对于主动插入流表的方式很有帮助。
注意，在默认情况下，Floodlight载入的转发模块是被动插入流表模式的。如果只使用静态流表，就必须将Forwarding模块从floodlight.properties文件中删除。

使用方法

API总结
URI
Description
Arguments
/wm/staticflowentrypusher/json
Add/Delete static flow
HTTP POST data (add flow), HTTP DELETE (for deletion)
/wm/staticflowentrypusher/list//json
List static flows for a switch or all switches
switch: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX) or "all"
/wm/staticflowentrypusher/clear//json
Clear static flows for a switch or all switches
switch: Valid Switch DPID (XX:XX:XX:XX:XX:XXXX:XX) or "all"

添加一个静态流表
Static Flow Pusher是通过REST API方式接入，所以有很多访问方式。例如：要在switch1中插入一个流表，使得port1进入的数据包从port2转发出去。这一操作可以通过使用简单的curl命令实现。第二个命令将显示流表设置。
curl -d '{"switch": "00:00:00:00:00:00:00:01", "name":"flow-mod-1", "priority":"32768", "ingress-port":"1","active":"true","actions":"output=2"}' http://:8080/wm/staticflowentrypusher/json
curl http://:8080/wm/core/switch/1/flow/json;

删除静态流表
通过发送包含流表名称的HTTP DELETE来删除静态流表
curl -X DELETE -d '{"name":"flow-mod-1"}' http://:8080/wm/staticflowentrypusher/json

流表项属性
Key
Value
Notes
switch

ID of the switch (data path) that this rule should be added to
xx:xx:xx:xx:xx:xx:xx:xx
name

Name of the flow entry, this is the primary key, it MUST be unique
actions
=
See table of actions below
Specify multiple actions using a comma-separated list
Specifying no actions will cause the packets to be dropped
priority

D默认值为 32767
最大值为 32767
active

wildcards

ingress-port

switch port on which the packet is received
Can be hexadecimal (with leading 0x) or decimal
src-mac
ess>
xx:xx:xx:xx:xx:xx
dst-mac

xx:xx:xx:xx:xx:xx
vlan-id

可以使16进制（以0X开头）或者是10进制
vlan-priority

可以使16进制（以0X开头）或者是10进制
ether-type

可以使16进制（以0X开头）或者是10进制
tos-bits

可以使16进制（以0X开头）或者是10进制
protocol

可以使16进制（以0X开头）或者是10进制
src-ip
address>
xx.xx.xx.xx
dst-ip

xx.xx.xx.xx
src-port

可以使16进制（以0X开头）或者是10进制
dst-port

可以使16进制（以0X开头）或者是10进制

操作域的操作选项
Key
Value
Notes
output
all controller local
ingress-port normal flood
没有丢弃选项
(但可以不指定操作从而丢弃数据包)
enqueue
:>
第一个数字是端口号，第二个是队列ID
可以是16进制（0x开头）或者10进制
strip-vlan

set-vlan-id

可以是16进制（0x开头）或者10进制
set-vlan-priority

可以是16进制（0x开头）或者10进制
set-src-mac

xx:xx:xx:xx:xx:xx
set-dst-mac

xx:xx:xx:xx:xx:xx
set-tos-bits

set-src-ip
>
xx.xx.xx.xx
set-dst-ip

xx.xx.xx.xx
set-src-port

可以是16进制（0x开头）或者10进制
set-dst-port

可以是16进制（0x开头）或者10进制

在主动插入方式中使用Static Flow Pusher
Static Flow Pusher可以通过编写简单的python代码脚本来控制。例如，在运行floodlight之后配置mininet虚拟机。默认的拓扑结构式一个交换机（s1）和两个连接到交换机的主机（h2，h3）。
sudo mn --controller=remote --ip= --port=6633
以下代码是插入从h2发送到h3和h3发送到h2的流表
import httplib
import json

class StaticFlowPusher(object):

def __init__(self, server):
self.server = server

def get(self, data):
ret = self.rest_call({}, 'GET')
return json.loads(ret[2])

def set(self, data):
ret = self.rest_call(data, 'POST')
return ret[0] == 200

def remove(self, objtype, data):
ret = self.rest_call(data, 'DELETE')
return ret[0] == 200

def rest_call(self, data, action):
path = '/wm/staticflowentrypusher/json'
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
}
body = json.dumps(data)
conn = httplib.HTTPConnection(self.server, 8080)
conn.request(action, path, body, headers)
response = conn.getresponse()
ret = (response.status, response.reason, response.read())
print ret
conn.close()
return ret

pusher = StaticFlowPusher('kie":"0",
"priority":"32768",
"ingress-port":"1",
"active":"true",
"actions":"output=flood"
}

flow2 = {
'switch':"00:00:00:00:00:00:00:01",
"name":"flow-mod-2",
"cookie":"0",
"priority":"32768",
"ingress-port":"2",
"active":"true",
"actions":"output=flood"
}

pusher.set(flow1)
pusher.set(flow2)
为了测试这个例子，可以再mininet虚拟机上运行pingall（注意：必须禁用交换机的学习功能和其他路由代码以确保交换机按照静态流表工作）
Mininet> h2 ping h3

Firewall REST API

Firewall REST接口
防火墙模块提供REST接口服务，该接口实现了采用REST API服务形式的RestletRoutable接口。以下是REST方法的列表：
URI
Method
URI Arguments
Data
Data Fields
Description
/wm/firewall/module//json
GET
选项：
status,enable,disable
存储规则，子网掩码
None
None
查询防火墙状态，启用、停止防火墙
/wm/firewall/rules/json
GET
None
None
None
以json格式理出所有的规则

POST
None
{"":"", "":"", ...}
"field":"value" 所有的序列组合
"switchid":"", "src-inport":"",
"src-mac": "", "dst-mac": "",
"dl-type": "", "src-ip": "", "dst-ip": "",
"nw-proto": "", "tp-src": "", "tp-dst": "",
"priority": "", "action": ""

Note: specifying src-ip/dst-ip without specifying dl-type as ARP, or specifying any IP-based nw-proto will automatically set dl-type to match IPv4.
创建新的防火墙规则

DELETE
None
{"":""}
"ruleid"