ryu/doc/source/writing_ryu_app.rst

   1 *********************
   2 The First Application
   3 *********************
   4
   5 Whetting Your Appetite
   6 ======================
   7
   8 If you want to manage network gear (switches, routers, etc) your
   9 own way, you just need to write your own Ryu application. Your application
  10 tells Ryu how you want to manage the gear. Then Ryu configures the
  11 gear by using OpenFlow protocol, etc.
  12
  13 Writing Ryu applications is easy. They're just Python scripts.
  14
  15
  16 Start Writing
  17 =============
  18
  19 Here we show a Ryu application that makes an OpenFlow switch work as a dumb
  20 layer 2 switch.
  21
  22 Open a text editor and create a new file with the following content:
  23
  24 .. code-block:: python
  25
  26    from ryu.base import app_manager
  27
  28    class L2Switch(app_manager.RyuApp):
  29        def __init__(self, *args, **kwargs):
  30            super(L2Switch, self).__init__(*args, **kwargs)
  31
  32 Ryu applications are just Python scripts so you can save the file with
  33 any name, any extension, and any place you want. Let's name the file
  34 'l2.py' in your home directory.
  35
  36 This application does nothing useful yet, however it's a complete Ryu
  37 application. In fact, you can run this Ryu application::
  38
  39    % ryu-manager ~/l2.py
  40    loading app /Users/fujita/l2.py
  41    instantiating app /Users/fujita/l2.py
  42
  43
  44 All you have to do is define a new subclass of RyuApp to run
  45 your Python script as a Ryu application.
  46
  47 Next let's add some functionality that sends a received packet to all
  48 the ports.
  49
  50 .. code-block:: python
  51
  52    from ryu.base import app_manager
  53    from ryu.controller import ofp_event
  54    from ryu.controller.handler import MAIN_DISPATCHER
  55    from ryu.controller.handler import set_ev_cls
  56    from ryu.ofproto import ofproto_v1_0
  57
  58    class L2Switch(app_manager.RyuApp):
  59        OFP_VERSIONS = [ofproto_v1_0.OFP_VERSION]
  60
  61        def __init__(self, *args, **kwargs):
  62            super(L2Switch, self).__init__(*args, **kwargs)
  63
  64        @set_ev_cls(ofp_event.EventOFPPacketIn, MAIN_DISPATCHER)
  65        def packet_in_handler(self, ev):
  66            msg = ev.msg
  67            dp = msg.datapath
  68            ofp = dp.ofproto
  69            ofp_parser = dp.ofproto_parser
  70
  71            actions = [ofp_parser.OFPActionOutput(ofp.OFPP_FLOOD)]
  72            out = ofp_parser.OFPPacketOut(
  73                datapath=dp, buffer_id=msg.buffer_id, in_port=msg.in_port,
  74                actions=actions)
  75            dp.send_msg(out)
  76
  77
  78 A new method 'packet_in_handler' is added to the L2Switch class. This is
  79 called when Ryu receives an OpenFlow packet_in message. The trick is the
  80 'set_ev_cls' decorator. This decorator tells Ryu when the decorated
  81 function should be called.
  82
  83 The first argument of the decorator indicates which type of event this
  84 function should be called for. As you might expect, every time Ryu gets a
  85 packet_in message, this function is called.
  86
  87 The second argument indicates the state of the switch. You probably
  88 want to ignore packet_in messages before the negotiation between Ryu
  89 and the switch is finished. Using 'MAIN_DISPATCHER' as the second
  90 argument means this function is called only after the negotiation
  91 completes.
  92
  93 Next let's look at the first half of the 'packet_in_handler' function.
  94
  95 * ev.msg is an object that represents a packet_in data structure.
  96
  97 * msg.dp is an object that represents a datapath (switch).
  98
  99 * dp.ofproto and dp.ofproto_parser are objects that represent the
 100   OpenFlow protocol that Ryu and the switch negotiated.
 101
 102 Ready for the second half.
 103
 104 * OFPActionOutput class is used with a packet_out message to specify a
 105   switch port that you want to send the packet out of. This
 106   application uses the OFPP_FLOOD flag to indicate that the packet should
 107   be sent out on all ports.
 108
 109 * OFPPacketOut class is used to build a packet_out message.
 110
 111 * If you call Datapath class's send_msg method with a OpenFlow message
 112   class object, Ryu builds and sends the on-wire data format to the switch.
 113
 114
 115 There, you finished implementing your first Ryu application. You are ready to
 116 run a Ryu application that does something useful.
 117
 118
 119 Is a dumb L2 switch is too dumb? You want to implement a learning L2
 120 switch? Move to `the next step
 121 <https://github.com/osrg/ryu/blob/master/ryu/app/simple_switch.py>`_. You
 122 can learn from the existing Ryu applications at `ryu/app
 123 <https://github.com/osrg/ryu/blob/master/ryu/app/>`_ directory and
 124 `integrated tests
 125 <https://github.com/osrg/ryu/blob/master/ryu/tests/integrated/>`_
 126 directory.