OS-Ken application API¶

OS-Ken application programming model¶

Create a OS-Ken application¶

A OS-Ken application is a python module which defines a subclass of os_ken.base.app_manager.OSKenApp. If two or more such classes are defined in a module, the first one (by name order) will be picked by app_manager. An OS-Ken application is singleton: only a single instance of a given OS-Ken application is supported.

Observe events¶

A OS-Ken application can register itself to listen for specific events using os_ken.controller.handler.set_ev_cls decorator.

Generate events¶

A OS-Ken application can raise events by calling appropriate os_ken.base.app_manager.OSKenApp's methods like send_event or send_event_to_observers.

Event classes¶

An event class describes a OS-Ken event generated in the system. By convention, event class names are prefixed by "Event". Events are generated either by the core part of OS-Ken or OS-Ken applications. A OS-Ken application can register its interest for a specific type of event by providing a handler method using the os_ken.controller.handler.set_ev_cls decorator.

os_ken.base.app_manager.OSKenApp¶

See OS-Ken API Reference.

os_ken.controller.handler.set_ev_cls¶

os_ken.controller.handler.set_ev_cls(ev_cls, dispatchers=None)¶

A decorator for OSKen application to declare an event handler.

Decorated method will become an event handler. ev_cls is an event class whose instances this OSKenApp wants to receive. dispatchers argument specifies one of the following negotiation phases (or a list of them) for which events should be generated for this handler. Note that, in case an event changes the phase, the phase before the change is used to check the interest.

Negotiation phase	Description
os_ken.controller.handler.HANDSHAKE_DISPATCHER	Sending and waiting for hello message
os_ken.controller.handler.CONFIG_DISPATCHER	Version negotiated and sent features-request message
os_ken.controller.handler.MAIN_DISPATCHER	Switch-features message received and sent set-config message
os_ken.controller.handler.DEAD_DISPATCHER	Disconnect from the peer. Or disconnecting due to some unrecoverable errors.

os_ken.controller.controller.Datapath¶

class os_ken.controller.controller.Datapath(socket, address)¶

A class to describe an OpenFlow switch connected to this controller.

An instance has the following attributes.

Attribute	Description
id	64-bit OpenFlow Datapath ID. Only available for os_ken.controller.handler.MAIN_DISPATCHER phase.
ofproto	A module which exports OpenFlow definitions, mainly constants appeared in the specification, for the negotiated OpenFlow version. For example, os_ken.ofproto.ofproto_v1_0 for OpenFlow 1.0.
ofproto_parser	A module which exports OpenFlow wire message encoder and decoder for the negotiated OpenFlow version. For example, os_ken.ofproto.ofproto_v1_0_parser for OpenFlow 1.0.
ofproto_parser.OFPxxxx(datapath,...)	A callable to prepare an OpenFlow message for the given switch. It can be sent with Datapath.send_msg later. xxxx is a name of the message. For example OFPFlowMod for flow-mod message. Arguemnts depend on the message.
set_xid(self, msg)	Generate an OpenFlow XID and put it in msg.xid.
send_msg(self, msg)	Queue an OpenFlow message to send to the corresponding switch. If msg.xid is None, set_xid is automatically called on the message before queueing.
send_packet_out	deprecated
send_flow_mod	deprecated
send_flow_del	deprecated
send_delete_all_flows	deprecated
send_barrier	Queue an OpenFlow barrier message to send to the switch.
send_nxt_set_flow_format	deprecated
is_reserved_port	deprecated

os_ken.controller.event.EventBase¶

class os_ken.controller.event.EventBase¶

The base of all event classes.

A OSKen application can define its own event type by creating a subclass.

os_ken.controller.event.EventRequestBase¶

class os_ken.controller.event.EventRequestBase¶

The base class for synchronous request for OSKenApp.send_request.

os_ken.controller.event.EventReplyBase¶

class os_ken.controller.event.EventReplyBase(dst)¶

The base class for synchronous request reply for OSKenApp.send_reply.

os_ken.controller.ofp_event.EventOFPStateChange¶

class os_ken.controller.ofp_event.EventOFPStateChange(dp)¶

An event class for negotiation phase change notification.

An instance of this class is sent to observer after changing the negotiation phase. An instance has at least the following attributes.

Attribute	Description
datapath	os_ken.controller.controller.Datapath instance of the switch

os_ken.controller.ofp_event.EventOFPPortStateChange¶

class os_ken.controller.ofp_event.EventOFPPortStateChange(dp, reason, port_no)¶

An event class to notify the port state changes of Dtatapath instance.

This event performs like EventOFPPortStatus, but OSKen will send this event after updating ports dict of Datapath instances. An instance has at least the following attributes.

Attribute	Description
datapath	os_ken.controller.controller.Datapath instance of the switch
reason	one of OFPPR_*
port_no	Port number which state was changed

os_ken.controller.dpset.EventDP¶

class os_ken.controller.dpset.EventDP(dp, enter_leave)¶

An event class to notify connect/disconnect of a switch.

For OpenFlow switches, one can get the same notification by observing os_ken.controller.ofp_event.EventOFPStateChange. An instance has at least the following attributes.

Attribute	Description
dp	A os_ken.controller.controller.Datapath instance of the switch
enter	True when the switch connected to our controller. False for disconnect.
ports	A list of port instances.

os_ken.controller.dpset.EventPortAdd¶

class os_ken.controller.dpset.EventPortAdd(dp, port)¶

An event class for switch port status "ADD" notification.

This event is generated when a new port is added to a switch. For OpenFlow switches, one can get the same notification by observing os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

Attribute	Description
dp	A os_ken.controller.controller.Datapath instance of the switch
port	port number

os_ken.controller.dpset.EventPortDelete¶

class os_ken.controller.dpset.EventPortDelete(dp, port)¶

An event class for switch port status "DELETE" notification.

This event is generated when a port is removed from a switch. For OpenFlow switches, one can get the same notification by observing os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

Attribute	Description
dp	A os_ken.controller.controller.Datapath instance of the switch
port	port number

os_ken.controller.dpset.EventPortModify¶

class os_ken.controller.dpset.EventPortModify(dp, new_port)¶

An event class for switch port status "MODIFY" notification.

This event is generated when some attribute of a port is changed. For OpenFlow switches, one can get the same notification by observing os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

Attribute	Description
dp	A os_ken.controller.controller.Datapath instance of the switch
port	port number

os_ken.controller.network.EventNetworkPort¶

class os_ken.controller.network.EventNetworkPort(network_id, dpid, port_no, add_del)¶

An event class for notification of port arrival and deperture.

This event is generated when a port is introduced to or removed from a network by the REST API. An instance has at least the following attributes.

Attribute	Description
network_id	Network ID
dpid	OpenFlow Datapath ID of the switch to which the port belongs.
port_no	OpenFlow port number of the port
add_del	True for adding a port. False for removing a port.

os_ken.controller.network.EventNetworkDel¶

class os_ken.controller.network.EventNetworkDel(network_id)¶

An event class for network deletion.

This event is generated when a network is deleted by the REST API. An instance has at least the following attributes.

Attribute	Description
network_id	Network ID

os_ken.controller.network.EventMacAddress¶

class os_ken.controller.network.EventMacAddress(dpid, port_no, network_id, mac_address, add_del)¶

An event class for end-point MAC address registration.

This event is generated when a end-point MAC address is updated by the REST API. An instance has at least the following attributes.

Attribute	Description
network_id	Network ID
dpid	OpenFlow Datapath ID of the switch to which the port belongs.
port_no	OpenFlow port number of the port
mac_address	The old MAC address of the port if add_del is False. Otherwise the new MAC address.
add_del	False if this event is a result of a port removal. Otherwise True.

os_ken.controller.tunnels.EventTunnelKeyAdd¶

class os_ken.controller.tunnels.EventTunnelKeyAdd(network_id, tunnel_key)¶

An event class for tunnel key registration.

This event is generated when a tunnel key is registered or updated by the REST API. An instance has at least the following attributes.

Attribute	Description
network_id	Network ID
tunnel_key	Tunnel Key

os_ken.controller.tunnels.EventTunnelKeyDel¶

class os_ken.controller.tunnels.EventTunnelKeyDel(network_id, tunnel_key)¶

An event class for tunnel key registration.

This event is generated when a tunnel key is removed by the REST API. An instance has at least the following attributes.

Attribute	Description
network_id	Network ID
tunnel_key	Tunnel Key

os_ken.controller.tunnels.EventTunnelPort¶

class os_ken.controller.tunnels.EventTunnelPort(dpid, port_no, remote_dpid, add_del)¶

An event class for tunnel port registration.

This event is generated when a tunnel port is added or removed by the REST API. An instance has at least the following attributes.

Attribute	Description
dpid	OpenFlow Datapath ID
port_no	OpenFlow port number
remote_dpid	OpenFlow port number of the tunnel peer
add_del	True for adding a tunnel. False for removal.