1 L2Switch Developer Guide
2 ========================
7 The L2Switch project provides Layer2 switch functionality.
14 - Decodes the packets coming to the controller and dispatches them
19 - Removes loops in the network
23 - Handles the decoded ARP packets
27 - Learns the Addresses (MAC and IP) of entities in the network
31 - Tracks the locations of hosts in the network
35 - Installs flows on each switch based on network traffic
37 Key APIs and Interfaces
38 -----------------------
58 - AbstractPacketDecoder
60 - Defines the methods that all decoders must implement
64 - The base decoder which decodes the packet into an Ethernet packet
66 - ArpDecoder, Ipv4Decoder, Ipv6Decoder
68 - Decodes Ethernet packets into the either an ARP or IPv4 or IPv6
74 There is a need for more decoders. A developer can write
76 - A decoder for another EtherType, i.e. LLDP.
78 - A higher layer decoder for the body of the IPv4 packet or IPv6
79 packet, i.e. TCP and UDP.
81 How to write a new decoder
83 - extends AbstractDecoder<A, B>
85 - A refers to the notification that the new decoder consumes
87 - B refers to the notification that the new decoder produces
89 - implements xPacketListener
91 - The new decoder must specify which notification it is listening to
95 - This method should examine the consumed notification to see
96 whether the new decoder can decode the contents of the packet
100 - This method does the actual decoding of the packet
108 - **LoopRemoverModule**
110 - Reads config subsystem value for *is-install-lldp-flow*
112 - If *is-install-lldp-flow* is true, then an
113 **InitialFlowWriter** is created
115 - Creates and initializes the other LoopRemover classes
117 - **InitialFlowWriter**
119 - Only created when *is-install-lldp-flow* is true
121 - Installs a flow, which forwards all LLDP packets to the
122 controller, on each switch
124 - **TopologyLinkDataChangeHandler**
126 - Listens to data change events on the Topology tree
128 - When these changes occur, it waits *graph-refresh-delay* seconds
129 and then tells **NetworkGraphImpl** to update
131 - Writes an STP (Spanning Tree Protocol) status of "forwarding" or
132 "discarding" to each link in the Topology data tree
134 - Forwarding links can forward packets.
136 - Discarding links cannot forward packets.
138 - **NetworkGraphImpl**
140 - Creates a loop-free graph of the network
145 - graph-refresh-delay
147 - Used in TopologyLinkDataChangeHandler
149 - A higher value has the advantage of doing less graph updates, at
150 the potential cost of losing some packets because the graph didn’t
153 - A lower value has the advantage of handling network topology
154 changes quicker, at the cost of doing more computation.
156 - is-install-lldp-flow
158 - Used in LoopRemoverModule
160 - "true" means a flow that sends all LLDP packets to the controller
161 will be installed on each switch
163 - "false" means this flow will not be installed
167 - The LLDP flow will be installed on the specified flow table of
172 - The LLDP flow will be installed with the specified priority
174 - lldp-flow-idle-timeout
176 - The LLDP flow will timeout (removed from the switch) if the flow
177 doesn’t forward a packet for *x* seconds
179 - lldp-flow-hard-timeout
181 - The LLDP flow will timeout (removed from the switch) after *x*
182 seconds, regardless of how many packets it is forwarding
187 No suggestions at the moment.
189 Validating changes to Loop Remover
190 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
192 STP Status information is added to the Inventory data tree.
194 - A status of "forwarding" means the link is active and packets are
197 - A status of "discarding" means the link is inactive and packets are
200 The STP status of a link can be checked through a browser or a REST
205 http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
207 The STP status should still be there after changes are made.
215 - **ArpHandlerModule**
217 - Reads config subsystem value for *is-proactive-flood-mode*
219 - If *is-proactive-flood-mode* is true, then a
220 ProactiveFloodFlowWriter is created
222 - If *is-proactive-flood-mode* is false, then an
223 InitialFlowWriter is created
225 - **ProactiveFloodFlowWriter**
227 - Only created when *is-proactive-flood-mode* is true
229 - Installs a flood flow on each switch. With this flood flow, a
230 packet that doesn’t match any other flows will be
231 flooded/broadcast from that switch.
233 - **InitialFlowWriter**
235 - Only created when *is-proactive-flood-mode* is false
237 - Installs a flow, which sends all ARP packets to the controller, on
240 - **ArpPacketHandler**
242 - Only created when *is-proactive-flood-mode* is false
244 - Handles and processes the controller’s incoming ARP packets
246 - Uses **PacketDispatcher** to send the ARP packet back into the
249 - **PacketDispatcher**
251 - Only created when *is-proactive-flood-mode* is false
253 - Sends packets out to the network
255 - Uses **InventoryReader** to determine which node-connector to a
258 - **InventoryReader**
260 - Only created when *is-proactive-flood-mode* is false
262 - Maintains a list of each switch’s node-connectors
267 - is-proactive-flood-mode
269 - "true" means that flood flows will be installed on each switch.
270 With this flood flow, each switch will flood a packet that doesn’t
271 match any other flows.
273 - Advantage: Fewer packets are sent to the controller because
274 those packets are flooded to the network.
276 - Disadvantage: A lot of network traffic is generated.
278 - "false" means the previously mentioned flood flows will not be
279 installed. Instead an ARP flow will be installed on each switch
280 that sends all ARP packets to the controller.
282 - Advantage: Less network traffic is generated.
284 - Disadvantage: The controller handles more packets (ARP requests
285 & replies) and the ARP process takes longer than if there were
288 - flood-flow-table-id
290 - The flood flow will be installed on the specified flow table of
293 - flood-flow-priority
295 - The flood flow will be installed with the specified priority
297 - flood-flow-idle-timeout
299 - The flood flow will timeout (removed from the switch) if the flow
300 doesn’t forward a packet for *x* seconds
302 - flood-flow-hard-timeout
304 - The flood flow will timeout (removed from the switch) after *x*
305 seconds, regardless of how many packets it is forwarding
309 - The ARP flow will be installed on the specified flow table of each
314 - The ARP flow will be installed with the specified priority
316 - arp-flow-idle-timeout
318 - The ARP flow will timeout (removed from the switch) if the flow
319 doesn’t forward a packet for *x* seconds
321 - arp-flow-hard-timeout
323 - The ARP flow will timeout (removed from the switch) after
324 *arp-flow-hard-timeout* seconds, regardless of how many packets it
330 The **ProactiveFloodFlowWriter** needs to be improved. It does have the
331 advantage of having less traffic come to the controller; however, it
332 generates too much network traffic.
340 - AddressTrackerModule
342 - Reads config subsystem value for *observe-addresses-from*
344 - If *observe-addresses-from* contains "arp", then an
345 AddressObserverUsingArp is created
347 - If *observe-addresses-from* contains "ipv4", then an
348 AddressObserverUsingIpv4 is created
350 - If *observe-addresses-from* contains "ipv6", then an
351 AddressObserverUsingIpv6 is created
353 - AddressObserverUsingArp
355 - Registers for ARP packet notifications
357 - Uses **AddressObservationWriter** to write address observations
360 - AddressObserverUsingIpv4
362 - Registers for IPv4 packet notifications
364 - Uses **AddressObservationWriter** to write address observations
367 - AddressObserverUsingIpv6
369 - Registers for IPv6 packet notifications
371 - Uses **AddressObservationWriter** to write address observations
374 - AddressObservationWriter
376 - Writes new Address Observations to the Inventory data tree
378 - Updates existing Address Observations with updated "last seen"
381 - Uses the *timestamp-update-intervval* configuration variable to
382 determine whether or not to update
387 - timestamp-update-interval
389 - A last-seen timestamp is associated with each address. This
390 last-seen timestamp will only be updated after
391 *timestamp-update-interval* milliseconds.
393 - A higher value has the advantage of performing less writes to the
396 - A lower value has the advantage of knowing how fresh an address
399 - observe-addresses-from
401 - IP and MAC addresses can be observed/learned from ARP, IPv4, and
402 IPv6 packets. Set which packets to make these observations from.
407 Further improvements can be made to the **AddressObservationWriter** so
408 that it (1) doesn’t make any unnecessary writes to the DB and (2) is
409 optimized for multi-threaded environments.
411 Validating changes to Address Tracker
412 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
414 Address Observations are added to the Inventory data tree.
416 The Address Observations on a Node Connector can be checked through a
417 browser or a REST Client.
421 http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
423 The Address Observations should still be there after changes.
425 Developer’s Guide for Host Tracker
426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
428 Validationg changes to Host Tracker
429 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
431 Host information is added to the Topology data tree.
435 - Attachment point (link) to a node/switch
437 This host information and attachment point information can be checked
438 through a browser or a REST Client.
442 http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
444 Host information should still be there after changes.
454 - Reads config subsystem value for *is-install-dropall-flow*
456 - If *is-install-dropall-flow* is true, then an
457 **InitialFlowWriter** is created
459 - Reads config subsystem value for *is-learning-only-mode*
461 - If *is-learning-only-mode* is false, then a
462 **ReactiveFlowWriter** is created
466 - Only created when *is-install-dropall-flow* is true
468 - Installs a flow, which drops all packets, on each switch. This
469 flow has low priority and means that packets that don’t match any
470 higher-priority flows will simply be dropped.
474 - Reacts to network traffic and installs MAC-to-MAC flows on
475 switches. These flows have matches based on MAC source and MAC
478 - Uses **FlowWriterServiceImpl** to write these flows to the
481 - FlowWriterService / FlowWriterServiceImpl
483 - Writes flows to switches
488 - is-install-dropall-flow
490 - "true" means a drop-all flow will be installed on each switch, so
491 the default action will be to drop a packet instead of sending it
494 - "false" means this flow will not be installed
496 - dropall-flow-table-id
498 - The dropall flow will be installed on the specified flow table of
501 - This field is only relevant when "is-install-dropall-flow" is set
504 - dropall-flow-priority
506 - The dropall flow will be installed with the specified priority
508 - This field is only relevant when "is-install-dropall-flow" is set
511 - dropall-flow-idle-timeout
513 - The dropall flow will timeout (removed from the switch) if the
514 flow doesn’t forward a packet for *x* seconds
516 - This field is only relevant when "is-install-dropall-flow" is set
519 - dropall-flow-hard-timeout
521 - The dropall flow will timeout (removed from the switch) after *x*
522 seconds, regardless of how many packets it is forwarding
524 - This field is only relevant when "is-install-dropall-flow" is set
527 - is-learning-only-mode
529 - "true" means that the L2Switch will only be learning addresses. No
530 additional flows to optimize network traffic will be installed.
532 - "false" means that the L2Switch will react to network traffic and
533 install flows on the switches to optimize traffic. Currently,
534 MAC-to-MAC flows are installed.
536 - reactive-flow-table-id
538 - The reactive flow will be installed on the specified flow table of
541 - This field is only relevant when "is-learning-only-mode" is set to
544 - reactive-flow-priority
546 - The reactive flow will be installed with the specified priority
548 - This field is only relevant when "is-learning-only-mode" is set to
551 - reactive-flow-idle-timeout
553 - The reactive flow will timeout (removed from the switch) if the
554 flow doesn’t forward a packet for *x* seconds
556 - This field is only relevant when "is-learning-only-mode" is set to
559 - reactive-flow-hard-timeout
561 - The reactive flow will timeout (removed from the switch) after *x*
562 seconds, regardless of how many packets it is forwarding
564 - This field is only relevant when "is-learning-only-mode" is set to
570 The **ReactiveFlowWriter** needs to be improved to install the
571 MAC-to-MAC flows faster. For the first ping, the ARP request and reply
572 are successful. However, then the ping packets are sent out. The first
573 ping packet is dropped sometimes because the MAC-to-MAC flow isn’t
574 installed quickly enough. The second, third, and following ping packets
575 are successful though.
577 API Reference Documentation
578 ---------------------------
580 Further documentation can be found by checking out the L2Switch project.
582 Checking out the L2Switch project
583 ---------------------------------
587 git clone https://git.opendaylight.org/gerrit/p/l2switch.git
589 The above command will create a directory called "l2switch" with the
592 Testing your changes to the L2Switch project
593 --------------------------------------------
595 Running the L2Switch project
596 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
598 To run the base distribution, you can use the following command
602 ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
604 If you need additional resources, you can use these command line
609 -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
611 To run the karaf distribution, you can use the following command:
615 ./distribution/karaf/target/assembly/bin/karaf
617 Create a network using mininet
618 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622 sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
623 sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
625 The above command will create a virtual network consisting of 3
626 switches. Each switch will connect to the controller located at the
627 specified IP, i.e. 127.0.0.1
631 sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
633 The above command has the "mac" option, which makes it easier to
634 distinguish between Host MAC addresses and Switch MAC addresses.
636 Generating network traffic using mininet
637 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643 The above command will cause host1 (h1) to ping host2 (h2)
649 *pingall* will cause each host to ping every other host.
651 Miscellaneous mininet commands
652 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
658 This will bring the link between switch1 (s1) and switch2 (s2) down
664 This will bring the link between switch1 (s1) and switch2 (s2) up
670 This will bring the link between switch1 (s1) and host1 (h1) down