SDN Series Part Four: Ryu, a Rich-Featured Open Source SDN Controller Supported by NTT Labs

23 Dec 2014 1:13pm, by

Editor’s note: This is part four of a multi-part series about software defined networking.  Other posts in the series can be found here.

Ryū (竜 ) in Japanese stands for dragon, flow and a school of thought. In this article, we will discuss an SDN controller, Ryu, with a dragon in its logo, through which operations flow. Ryu is commonly referred to as component-based, open source software defined by a networking framework. It is implemented entirely in Python, and supported by NTT’s labs. Like other SDN controller frameworks, Ryu also provides software components with well-defined APIs that are exposed to allow developers to create new network management and control applications. One of the strengths of Ryu is that it supports multiple southbound protocols for managing devices, such as OpenFlow, Network Configuration Protocol (NETCONF), OpenFlow Management and Configuration Protocol (OF-Config), and others.

Ryu’s Architecture

Just like any SDN controller, Ryu can also create and send an OpenFlow message, listen to asynchronous events such as flow_removed, and parse and handle incoming packets. Figure 1 below depicts the architecture of the Ryu controller framework:


Figure 1: RYU Architecture

Let us look at some of the important components of the architecture.

Ryu Libraries

Ryu has an impressive collection of libraries, ranging from support for multiple southbound protocols to various network packet processing operations. With respect to southbound protocols, Ryu supports OF-Config, Open vSwitch Database Management Protocol (OVSDB), NETCONF, XFlow (Netflow and Sflow) and other third-party protocols. Netflow is supported by Cisco and others and is specific to an IP. The Netflow and Sflow protocols support packet sampling and aggregation, which are mainly used for network traffic measurement. The third-party libraries include Open vSwitch Python binding, the Oslo configuration library and a Python library for the NETCONF client. The Ryu packet library helps you to parse and build various protocol packets, such as VLAN, MPLS, GRE, etc. 

OpenFlow Protocol and Controller

Ryu supports the OpenFlow protocol up to the latest version 1.4. It includes an OpenFlow protocol encoder and decoder library. In addition, one of the key components of the Ryu architecture is the OpenFlow controller, which is responsible for managing the OpenFlow switches used to configure flows, manage events, etc. The OpenFlow controller is one of the internal event sources in the Ryu architecture. The table below summarizes the Ryu OpenFlow protocol messages, structures and corresponding API.

Controller to
Switch Messages

Asynchronous Messages

Symmetric Messages


Handshake, switch-config, flow-table-config, modify/read state, queue-config, packet-out, barrier, role-request Packet-in, flow-removed, port-satus, and Error. Hello, Echo-Request & Reply, Error, experimenter Flow-match
send_msg API and packet builder APIs set_ev_cls API and packet parser APIs Both Send and Event APIs

Managers and Core-Processes

The Ryu manager is the main executable. When it is run, it listens to the specified IP address (ex: and the specified port (6633 by default). Following this, any OpenFlow switch (hardware, or Open vSwitch or OVS) can connect to the Ryu manager. The app manager is the foundational component for all Ryu applications. All applications inherit from the app manager’s RyuApp class. The core-process component in the architecture includes event management, messaging, in-memory state management, etc. Interestingly, the Ryu messaging service does support components developed in other languages.

RYU Northbound

At the API layer, Ryu include an Openstack Neutron plug-in that supports both GRE-based overlay and VLAN configurations. Ryu also supports a REST interface to its OpenFlow operations. In addition, using WSGI (a framework for connecting web applications and web servers in Python), one can easily introduce newer REST APIs into an application.

RYU Applications

Ryu is distributed with multiple applications such as a simple_switch, router, isolation, firewall, GRE tunnel, topology, VLAN, etc. Ryu applications are single-threaded entities, which implement various functionalities. Ryu applications send asynchronous events to each other. The functional architecture of a Ryu application is shown in Figure 2.


Figure 2: Functional Architecture of Ryu Application

Each Ryu application has a receive queue for events, which is mainly FIFO to preserve the order of events. In addition, each application includes a thread for processing events from the queue. The thread’s main loop pops out events from the receive queue and calls the appropriate event handler. Hence, the event handler is called within the context of the event-processing thread, which works in a blocking fashion, i.e., when an event handler is given control, no further events for the Ryu application will be processed until control is returned.

Ryu applications can be run and configured by passing a configuration file to the Ryu manager:

One of the important generic options is the app_lists, which includes application module name(s) to run.

Writing Applications in Ryu

In this section, we will write a Ryu application that make OpenFlow switches work as a layer 2 switch. A Ryu application is a Python module that defines a subclass of ryu.base.app_manager.RyuApp. If two or more such classes are defined in a module, the first one (by name order) will be picked by the app manager. A Ryu application is a singleton: only a single instance of a given Ryu application is supported.

In our case, we will call our switch MySwitch. It inherits from the base class app_manager.RyuApp, and is defined as:

A Ryu application can either raise an event or receive an event. To raise events, the Ryu application calls the appropriate ryu.base.app_manager RyuApp methods, like the send_event or send_event_to_observers APIs. A Ryu application can register itself to listen for specific events using ryu.controller.handler.set_ev_cls decorator. This decorator tells Ryu when the decorated function should be called. The first argument for the set_ev_cls decorator indicates the event of interest, which triggers the following function call. The second argument indicates the state of the switch. For example, if the application wants to ignore packet_in messages before the negotiation between the Ryu controller and the switch finishes, it can use MAIN_DISPATCHER as the second argument, which indicates that the following function is called only after the negotiation has been completed.

In our example, our application is interested in packet_in events, and every time the Ryu controller gets a packet_in message, a handler function should be called. In addition, our application is able to send a received packet to all ports. We can define these operations as:

Let’s look at the packet_in_handler function in more detail. Whenever a packet_in message is received, packet_in_handler is called, which is achieved by the set_ev_cls API. The ev.msg is an object that represents a packet_in data structure, whereas msg.datapath represents a data path (switch). Hence, the dp.ofproto represents the OpenFlow protocol negotiated between Ryu and the switch. The ofproto_parser parses the incoming packet_in message.

Once we have received the packet_in message, we need to forward it to all the ports via a packet_out message. The OFPActionOutput class is used with a packet_out message to specify a switch port that you want to send the packet from. As we need to send it to all the ports, OFPP_FLOOD port is used. The OFPPacketOut class is used to build the packet_out message. Finally, we need to call the data path class’s send_msg method with an OpenFlow message class object, which makes the controller build the message and send it to the switch.

Thus, we have finished writing our Ryu application, which is ready to run. As a Ryu application is just a Python script, we can save the file with any name and extension. Assuming that we will put the above code in a file named, this application can be run using the Ryu manager command: % ryu-manager

As a closing note, Ryu is an open source SDN controller with a rich set of features, which is constantly growing. Ryu has also been used by commercial vendors, such as Pica8, in their solutions. Ryu developers are adding more components and providing better abstractions, and it is one of those SDN controllers that we developers should seriously consider contributing to.

Feature image: “Ancient Dragon” by brett jordan is licensed under CC BY 2.0.

A newsletter digest of the week’s most important stories & analyses.

View / Add Comments

Please stay on topic and be respectful of others. Review our Terms of Use.