1 .. _l2switch-dev-guide:
3 L2Switch Developer Guide
4 ========================
9 The L2Switch project provides Layer2 switch functionality.
16 - Decodes the packets coming to the controller and dispatches them
21 - Removes loops in the network
25 - Handles the decoded ARP packets
29 - Learns the Addresses (MAC and IP) of entities in the network
33 - Tracks the locations of hosts in the network
37 - Installs flows on each switch based on network traffic
39 Key APIs and Interfaces
40 -----------------------
60 - AbstractPacketDecoder
62 - Defines the methods that all decoders must implement
66 - The base decoder which decodes the packet into an Ethernet packet
68 - ArpDecoder, Ipv4Decoder, Ipv6Decoder
70 - Decodes Ethernet packets into the either an ARP or IPv4 or IPv6
76 There is a need for more decoders. A developer can write
78 - A decoder for another EtherType, i.e. LLDP.
80 - A higher layer decoder for the body of the IPv4 packet or IPv6
81 packet, i.e. TCP and UDP.
83 How to write a new decoder
85 - extends AbstractDecoder<A, B>
87 - A refers to the notification that the new decoder consumes
89 - B refers to the notification that the new decoder produces
91 - implements xPacketListener
93 - The new decoder must specify which notification it is listening to
97 - This method should examine the consumed notification to see
98 whether the new decoder can decode the contents of the packet
102 - This method does the actual decoding of the packet
110 - **LoopRemoverModule**
112 - Reads config subsystem value for *is-install-lldp-flow*
114 - If *is-install-lldp-flow* is true, then an
115 **InitialFlowWriter** is created
117 - Creates and initializes the other LoopRemover classes
119 - **InitialFlowWriter**
121 - Only created when *is-install-lldp-flow* is true
123 - Installs a flow, which forwards all LLDP packets to the
124 controller, on each switch
126 - **TopologyLinkDataChangeHandler**
128 - Listens to data change events on the Topology tree
130 - When these changes occur, it waits *graph-refresh-delay* seconds
131 and then tells **NetworkGraphImpl** to update
133 - Writes an STP (Spanning Tree Protocol) status of "forwarding" or
134 "discarding" to each link in the Topology data tree
136 - Forwarding links can forward packets.
138 - Discarding links cannot forward packets.
140 - **NetworkGraphImpl**
142 - Creates a loop-free graph of the network
147 - graph-refresh-delay
149 - Used in TopologyLinkDataChangeHandler
151 - A higher value has the advantage of doing less graph updates, at
152 the potential cost of losing some packets because the graph didn’t
155 - A lower value has the advantage of handling network topology
156 changes quicker, at the cost of doing more computation.
158 - is-install-lldp-flow
160 - Used in LoopRemoverModule
162 - "true" means a flow that sends all LLDP packets to the controller
163 will be installed on each switch
165 - "false" means this flow will not be installed
169 - The LLDP flow will be installed on the specified flow table of
174 - The LLDP flow will be installed with the specified priority
176 - lldp-flow-idle-timeout
178 - The LLDP flow will timeout (removed from the switch) if the flow
179 doesn’t forward a packet for *x* seconds
181 - lldp-flow-hard-timeout
183 - The LLDP flow will timeout (removed from the switch) after *x*
184 seconds, regardless of how many packets it is forwarding
189 No suggestions at the moment.
191 Validating changes to Loop Remover
192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194 STP Status information is added to the Inventory data tree.
196 - A status of "forwarding" means the link is active and packets are
199 - A status of "discarding" means the link is inactive and packets are
202 The STP status of a link can be checked through a browser or a REST
207 http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
209 The STP status should still be there after changes are made.
217 - **ArpHandlerModule**
219 - Reads config subsystem value for *is-proactive-flood-mode*
221 - If *is-proactive-flood-mode* is true, then a
222 ProactiveFloodFlowWriter is created
224 - If *is-proactive-flood-mode* is false, then an
225 InitialFlowWriter is created
227 - **ProactiveFloodFlowWriter**
229 - Only created when *is-proactive-flood-mode* is true
231 - Installs a flood flow on each switch. With this flood flow, a
232 packet that doesn’t match any other flows will be
233 flooded/broadcast from that switch.
235 - **InitialFlowWriter**
237 - Only created when *is-proactive-flood-mode* is false
239 - Installs a flow, which sends all ARP packets to the controller, on
242 - **ArpPacketHandler**
244 - Only created when *is-proactive-flood-mode* is false
246 - Handles and processes the controller’s incoming ARP packets
248 - Uses **PacketDispatcher** to send the ARP packet back into the
251 - **PacketDispatcher**
253 - Only created when *is-proactive-flood-mode* is false
255 - Sends packets out to the network
257 - Uses **InventoryReader** to determine which node-connector to a
260 - **InventoryReader**
262 - Only created when *is-proactive-flood-mode* is false
264 - Maintains a list of each switch’s node-connectors
269 - is-proactive-flood-mode
271 - "true" means that flood flows will be installed on each switch.
272 With this flood flow, each switch will flood a packet that doesn’t
273 match any other flows.
275 - Advantage: Fewer packets are sent to the controller because
276 those packets are flooded to the network.
278 - Disadvantage: A lot of network traffic is generated.
280 - "false" means the previously mentioned flood flows will not be
281 installed. Instead an ARP flow will be installed on each switch
282 that sends all ARP packets to the controller.
284 - Advantage: Less network traffic is generated.
286 - Disadvantage: The controller handles more packets (ARP requests
287 & replies) and the ARP process takes longer than if there were
290 - flood-flow-table-id
292 - The flood flow will be installed on the specified flow table of
295 - flood-flow-priority
297 - The flood flow will be installed with the specified priority
299 - flood-flow-idle-timeout
301 - The flood flow will timeout (removed from the switch) if the flow
302 doesn’t forward a packet for *x* seconds
304 - flood-flow-hard-timeout
306 - The flood flow will timeout (removed from the switch) after *x*
307 seconds, regardless of how many packets it is forwarding
311 - The ARP flow will be installed on the specified flow table of each
316 - The ARP flow will be installed with the specified priority
318 - arp-flow-idle-timeout
320 - The ARP flow will timeout (removed from the switch) if the flow
321 doesn’t forward a packet for *x* seconds
323 - arp-flow-hard-timeout
325 - The ARP flow will timeout (removed from the switch) after
326 *arp-flow-hard-timeout* seconds, regardless of how many packets it
332 The **ProactiveFloodFlowWriter** needs to be improved. It does have the
333 advantage of having less traffic come to the controller; however, it
334 generates too much network traffic.
342 - AddressTrackerModule
344 - Reads config subsystem value for *observe-addresses-from*
346 - If *observe-addresses-from* contains "arp", then an
347 AddressObserverUsingArp is created
349 - If *observe-addresses-from* contains "ipv4", then an
350 AddressObserverUsingIpv4 is created
352 - If *observe-addresses-from* contains "ipv6", then an
353 AddressObserverUsingIpv6 is created
355 - AddressObserverUsingArp
357 - Registers for ARP packet notifications
359 - Uses **AddressObservationWriter** to write address observations
362 - AddressObserverUsingIpv4
364 - Registers for IPv4 packet notifications
366 - Uses **AddressObservationWriter** to write address observations
369 - AddressObserverUsingIpv6
371 - Registers for IPv6 packet notifications
373 - Uses **AddressObservationWriter** to write address observations
376 - AddressObservationWriter
378 - Writes new Address Observations to the Inventory data tree
380 - Updates existing Address Observations with updated "last seen"
383 - Uses the *timestamp-update-intervval* configuration variable to
384 determine whether or not to update
389 - timestamp-update-interval
391 - A last-seen timestamp is associated with each address. This
392 last-seen timestamp will only be updated after
393 *timestamp-update-interval* milliseconds.
395 - A higher value has the advantage of performing less writes to the
398 - A lower value has the advantage of knowing how fresh an address
401 - observe-addresses-from
403 - IP and MAC addresses can be observed/learned from ARP, IPv4, and
404 IPv6 packets. Set which packets to make these observations from.
409 Further improvements can be made to the **AddressObservationWriter** so
410 that it (1) doesn’t make any unnecessary writes to the DB and (2) is
411 optimized for multi-threaded environments.
413 Validating changes to Address Tracker
414 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
416 Address Observations are added to the Inventory data tree.
418 The Address Observations on a Node Connector can be checked through a
419 browser or a REST Client.
423 http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
425 The Address Observations should still be there after changes.
427 Developer’s Guide for Host Tracker
428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430 Validationg changes to Host Tracker
431 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
433 Host information is added to the Topology data tree.
437 - Attachment point (link) to a node/switch
439 This host information and attachment point information can be checked
440 through a browser or a REST Client.
444 http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
446 Host information should still be there after changes.
456 - Reads config subsystem value for *is-install-dropall-flow*
458 - If *is-install-dropall-flow* is true, then an
459 **InitialFlowWriter** is created
461 - Reads config subsystem value for *is-learning-only-mode*
463 - If *is-learning-only-mode* is false, then a
464 **ReactiveFlowWriter** is created
468 - Only created when *is-install-dropall-flow* is true
470 - Installs a flow, which drops all packets, on each switch. This
471 flow has low priority and means that packets that don’t match any
472 higher-priority flows will simply be dropped.
476 - Reacts to network traffic and installs MAC-to-MAC flows on
477 switches. These flows have matches based on MAC source and MAC
480 - Uses **FlowWriterServiceImpl** to write these flows to the
483 - FlowWriterService / FlowWriterServiceImpl
485 - Writes flows to switches
490 - is-install-dropall-flow
492 - "true" means a drop-all flow will be installed on each switch, so
493 the default action will be to drop a packet instead of sending it
496 - "false" means this flow will not be installed
498 - dropall-flow-table-id
500 - The dropall flow will be installed on the specified flow table of
503 - This field is only relevant when "is-install-dropall-flow" is set
506 - dropall-flow-priority
508 - The dropall flow will be installed with the specified priority
510 - This field is only relevant when "is-install-dropall-flow" is set
513 - dropall-flow-idle-timeout
515 - The dropall flow will timeout (removed from the switch) if the
516 flow doesn’t forward a packet for *x* seconds
518 - This field is only relevant when "is-install-dropall-flow" is set
521 - dropall-flow-hard-timeout
523 - The dropall flow will timeout (removed from the switch) after *x*
524 seconds, regardless of how many packets it is forwarding
526 - This field is only relevant when "is-install-dropall-flow" is set
529 - is-learning-only-mode
531 - "true" means that the L2Switch will only be learning addresses. No
532 additional flows to optimize network traffic will be installed.
534 - "false" means that the L2Switch will react to network traffic and
535 install flows on the switches to optimize traffic. Currently,
536 MAC-to-MAC flows are installed.
538 - reactive-flow-table-id
540 - The reactive flow will be installed on the specified flow table of
543 - This field is only relevant when "is-learning-only-mode" is set to
546 - reactive-flow-priority
548 - The reactive flow will be installed with the specified priority
550 - This field is only relevant when "is-learning-only-mode" is set to
553 - reactive-flow-idle-timeout
555 - The reactive flow will timeout (removed from the switch) if the
556 flow doesn’t forward a packet for *x* seconds
558 - This field is only relevant when "is-learning-only-mode" is set to
561 - reactive-flow-hard-timeout
563 - The reactive flow will timeout (removed from the switch) after *x*
564 seconds, regardless of how many packets it is forwarding
566 - This field is only relevant when "is-learning-only-mode" is set to
572 The **ReactiveFlowWriter** needs to be improved to install the
573 MAC-to-MAC flows faster. For the first ping, the ARP request and reply
574 are successful. However, then the ping packets are sent out. The first
575 ping packet is dropped sometimes because the MAC-to-MAC flow isn’t
576 installed quickly enough. The second, third, and following ping packets
577 are successful though.
579 API Reference Documentation
580 ---------------------------
582 Further documentation can be found by checking out the L2Switch project.
584 Checking out the L2Switch project
585 ---------------------------------
589 git clone https://git.opendaylight.org/gerrit/p/l2switch.git
591 The above command will create a directory called "l2switch" with the
594 Testing your changes to the L2Switch project
595 --------------------------------------------
597 Running the L2Switch project
598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600 To run the base distribution, you can use the following command
604 ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
606 If you need additional resources, you can use these command line
611 -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
613 To run the karaf distribution, you can use the following command:
617 ./distribution/karaf/target/assembly/bin/karaf
619 Create a network using mininet
620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
624 sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
625 sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
627 The above command will create a virtual network consisting of 3
628 switches. Each switch will connect to the controller located at the
629 specified IP, i.e. 127.0.0.1
633 sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
635 The above command has the "mac" option, which makes it easier to
636 distinguish between Host MAC addresses and Switch MAC addresses.
638 Generating network traffic using mininet
639 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
645 The above command will cause host1 (h1) to ping host2 (h2)
651 *pingall* will cause each host to ping every other host.
653 Miscellaneous mininet commands
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
660 This will bring the link between switch1 (s1) and switch2 (s2) down
666 This will bring the link between switch1 (s1) and switch2 (s2) up
672 This will bring the link between switch1 (s1) and host1 (h1) down