docs/developer-guide/l2switch-developer-guide.rst

   1 L2Switch Developer Guide
   2 ========================
   3
   4 Overview
   5 --------
   6
   7 The L2Switch project provides Layer2 switch functionality.
   8
   9 L2Switch Architecture
  10 ---------------------
  11
  12 -  Packet Handler
  13
  14    -  Decodes the packets coming to the controller and dispatches them
  15       appropriately
  16
  17 -  Loop Remover
  18
  19    -  Removes loops in the network
  20
  21 -  Arp Handler
  22
  23    -  Handles the decoded ARP packets
  24
  25 -  Address Tracker
  26
  27    -  Learns the Addresses (MAC and IP) of entities in the network
  28
  29 -  Host Tracker
  30
  31    -  Tracks the locations of hosts in the network
  32
  33 -  L2Switch Main
  34
  35    -  Installs flows on each switch based on network traffic
  36
  37 Key APIs and Interfaces
  38 -----------------------
  39
  40 -  Packet Handler
  41
  42 -  Loop Remover
  43
  44 -  Arp Handler
  45
  46 -  Address Tracker
  47
  48 -  Host Tracker
  49
  50 -  L2Switch Main
  51
  52 Packet Dispatcher
  53 ~~~~~~~~~~~~~~~~~
  54
  55 Classes
  56 ^^^^^^^
  57
  58 -  AbstractPacketDecoder
  59
  60    -  Defines the methods that all decoders must implement
  61
  62 -  EthernetDecoder
  63
  64    -  The base decoder which decodes the packet into an Ethernet packet
  65
  66 -  ArpDecoder, Ipv4Decoder, Ipv6Decoder
  67
  68    -  Decodes Ethernet packets into the either an ARP or IPv4 or IPv6
  69       packet
  70
  71 Further development
  72 ^^^^^^^^^^^^^^^^^^^
  73
  74 There is a need for more decoders. A developer can write
  75
  76 -  A decoder for another EtherType, i.e. LLDP.
  77
  78 -  A higher layer decoder for the body of the IPv4 packet or IPv6
  79    packet, i.e. TCP and UDP.
  80
  81 How to write a new decoder
  82
  83 -  extends AbstractDecoder<A, B>
  84
  85    -  A refers to the notification that the new decoder consumes
  86
  87    -  B refers to the notification that the new decoder produces
  88
  89 -  implements xPacketListener
  90
  91    -  The new decoder must specify which notification it is listening to
  92
  93 -  canDecode method
  94
  95    -  This method should examine the consumed notification to see
  96       whether the new decoder can decode the contents of the packet
  97
  98 -  decode method
  99
 100    -  This method does the actual decoding of the packet
 101
 102 Loop Remover
 103 ~~~~~~~~~~~~
 104
 105 Classes
 106 ^^^^^^^
 107
 108 -  **LoopRemoverModule**
 109
 110    -  Reads config subsystem value for *is-install-lldp-flow*
 111
 112       -  If *is-install-lldp-flow* is true, then an
 113          **InitialFlowWriter** is created
 114
 115    -  Creates and initializes the other LoopRemover classes
 116
 117 -  **InitialFlowWriter**
 118
 119    -  Only created when *is-install-lldp-flow* is true
 120
 121    -  Installs a flow, which forwards all LLDP packets to the
 122       controller, on each switch
 123
 124 -  **TopologyLinkDataChangeHandler**
 125
 126    -  Listens to data change events on the Topology tree
 127
 128    -  When these changes occur, it waits *graph-refresh-delay* seconds
 129       and then tells **NetworkGraphImpl** to update
 130
 131    -  Writes an STP (Spanning Tree Protocol) status of "forwarding" or
 132       "discarding" to each link in the Topology data tree
 133
 134       -  Forwarding links can forward packets.
 135
 136       -  Discarding links cannot forward packets.
 137
 138 -  **NetworkGraphImpl**
 139
 140    -  Creates a loop-free graph of the network
 141
 142 Configuration
 143 ^^^^^^^^^^^^^
 144
 145 -  graph-refresh-delay
 146
 147    -  Used in TopologyLinkDataChangeHandler
 148
 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
 151       update immediately.
 152
 153    -  A lower value has the advantage of handling network topology
 154       changes quicker, at the cost of doing more computation.
 155
 156 -  is-install-lldp-flow
 157
 158    -  Used in LoopRemoverModule
 159
 160    -  "true" means a flow that sends all LLDP packets to the controller
 161       will be installed on each switch
 162
 163    -  "false" means this flow will not be installed
 164
 165 -  lldp-flow-table-id
 166
 167    -  The LLDP flow will be installed on the specified flow table of
 168       each switch
 169
 170 -  lldp-flow-priority
 171
 172    -  The LLDP flow will be installed with the specified priority
 173
 174 -  lldp-flow-idle-timeout
 175
 176    -  The LLDP flow will timeout (removed from the switch) if the flow
 177       doesn’t forward a packet for *x* seconds
 178
 179 -  lldp-flow-hard-timeout
 180
 181    -  The LLDP flow will timeout (removed from the switch) after *x*
 182       seconds, regardless of how many packets it is forwarding
 183
 184 Further development
 185 ^^^^^^^^^^^^^^^^^^^
 186
 187 No suggestions at the moment.
 188
 189 Validating changes to Loop Remover
 190 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 191
 192 STP Status information is added to the Inventory data tree.
 193
 194 -  A status of "forwarding" means the link is active and packets are
 195    flowing on it.
 196
 197 -  A status of "discarding" means the link is inactive and packets are
 198    not sent over it.
 199
 200 The STP status of a link can be checked through a browser or a REST
 201 Client.
 202
 203 ::
 204
 205     http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
 206
 207 The STP status should still be there after changes are made.
 208
 209 Arp Handler
 210 ~~~~~~~~~~~
 211
 212 Classes
 213 ^^^^^^^
 214
 215 -  **ArpHandlerModule**
 216
 217    -  Reads config subsystem value for *is-proactive-flood-mode*
 218
 219       -  If *is-proactive-flood-mode* is true, then a
 220          ProactiveFloodFlowWriter is created
 221
 222       -  If *is-proactive-flood-mode* is false, then an
 223          InitialFlowWriter is created
 224
 225 -  **ProactiveFloodFlowWriter**
 226
 227    -  Only created when *is-proactive-flood-mode* is true
 228
 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.
 232
 233 -  **InitialFlowWriter**
 234
 235    -  Only created when *is-proactive-flood-mode* is false
 236
 237    -  Installs a flow, which sends all ARP packets to the controller, on
 238       each switch
 239
 240 -  **ArpPacketHandler**
 241
 242    -  Only created when *is-proactive-flood-mode* is false
 243
 244    -  Handles and processes the controller’s incoming ARP packets
 245
 246    -  Uses **PacketDispatcher** to send the ARP packet back into the
 247       network
 248
 249 -  **PacketDispatcher**
 250
 251    -  Only created when *is-proactive-flood-mode* is false
 252
 253    -  Sends packets out to the network
 254
 255    -  Uses **InventoryReader** to determine which node-connector to a
 256       send a packet on
 257
 258 -  **InventoryReader**
 259
 260    -  Only created when *is-proactive-flood-mode* is false
 261
 262    -  Maintains a list of each switch’s node-connectors
 263
 264 Configuration
 265 ^^^^^^^^^^^^^
 266
 267 -  is-proactive-flood-mode
 268
 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.
 272
 273       -  Advantage: Fewer packets are sent to the controller because
 274          those packets are flooded to the network.
 275
 276       -  Disadvantage: A lot of network traffic is generated.
 277
 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.
 281
 282       -  Advantage: Less network traffic is generated.
 283
 284       -  Disadvantage: The controller handles more packets (ARP requests
 285          & replies) and the ARP process takes longer than if there were
 286          flood flows.
 287
 288 -  flood-flow-table-id
 289
 290    -  The flood flow will be installed on the specified flow table of
 291       each switch
 292
 293 -  flood-flow-priority
 294
 295    -  The flood flow will be installed with the specified priority
 296
 297 -  flood-flow-idle-timeout
 298
 299    -  The flood flow will timeout (removed from the switch) if the flow
 300       doesn’t forward a packet for *x* seconds
 301
 302 -  flood-flow-hard-timeout
 303
 304    -  The flood flow will timeout (removed from the switch) after *x*
 305       seconds, regardless of how many packets it is forwarding
 306
 307 -  arp-flow-table-id
 308
 309    -  The ARP flow will be installed on the specified flow table of each
 310       switch
 311
 312 -  arp-flow-priority
 313
 314    -  The ARP flow will be installed with the specified priority
 315
 316 -  arp-flow-idle-timeout
 317
 318    -  The ARP flow will timeout (removed from the switch) if the flow
 319       doesn’t forward a packet for *x* seconds
 320
 321 -  arp-flow-hard-timeout
 322
 323    -  The ARP flow will timeout (removed from the switch) after
 324       *arp-flow-hard-timeout* seconds, regardless of how many packets it
 325       is forwarding
 326
 327 Further development
 328 ^^^^^^^^^^^^^^^^^^^
 329
 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.
 333
 334 Address Tracker
 335 ~~~~~~~~~~~~~~~
 336
 337 Classes
 338 ^^^^^^^
 339
 340 -  AddressTrackerModule
 341
 342    -  Reads config subsystem value for *observe-addresses-from*
 343
 344    -  If *observe-addresses-from* contains "arp", then an
 345       AddressObserverUsingArp is created
 346
 347    -  If *observe-addresses-from* contains "ipv4", then an
 348       AddressObserverUsingIpv4 is created
 349
 350    -  If *observe-addresses-from* contains "ipv6", then an
 351       AddressObserverUsingIpv6 is created
 352
 353 -  AddressObserverUsingArp
 354
 355    -  Registers for ARP packet notifications
 356
 357    -  Uses **AddressObservationWriter** to write address observations
 358       from ARP packets
 359
 360 -  AddressObserverUsingIpv4
 361
 362    -  Registers for IPv4 packet notifications
 363
 364    -  Uses **AddressObservationWriter** to write address observations
 365       from IPv4 packets
 366
 367 -  AddressObserverUsingIpv6
 368
 369    -  Registers for IPv6 packet notifications
 370
 371    -  Uses **AddressObservationWriter** to write address observations
 372       from IPv6 packets
 373
 374 -  AddressObservationWriter
 375
 376    -  Writes new Address Observations to the Inventory data tree
 377
 378    -  Updates existing Address Observations with updated "last seen"
 379       timestamps
 380
 381       -  Uses the *timestamp-update-intervval* configuration variable to
 382          determine whether or not to update
 383
 384 Configuration
 385 ^^^^^^^^^^^^^
 386
 387 -  timestamp-update-interval
 388
 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.
 392
 393    -  A higher value has the advantage of performing less writes to the
 394       database.
 395
 396    -  A lower value has the advantage of knowing how fresh an address
 397       is.
 398
 399 -  observe-addresses-from
 400
 401    -  IP and MAC addresses can be observed/learned from ARP, IPv4, and
 402       IPv6 packets. Set which packets to make these observations from.
 403
 404 Further development
 405 ^^^^^^^^^^^^^^^^^^^
 406
 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.
 410
 411 Validating changes to Address Tracker
 412 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 413
 414 Address Observations are added to the Inventory data tree.
 415
 416 The Address Observations on a Node Connector can be checked through a
 417 browser or a REST Client.
 418
 419 ::
 420
 421     http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
 422
 423 The Address Observations should still be there after changes.
 424
 425 Developer’s Guide for Host Tracker
 426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 427
 428 Validationg changes to Host Tracker
 429 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 430
 431 Host information is added to the Topology data tree.
 432
 433 -  Host address
 434
 435 -  Attachment point (link) to a node/switch
 436
 437 This host information and attachment point information can be checked
 438 through a browser or a REST Client.
 439
 440 ::
 441
 442     http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
 443
 444 Host information should still be there after changes.
 445
 446 L2Switch Main
 447 ~~~~~~~~~~~~~
 448
 449 Classes
 450 ^^^^^^^
 451
 452 -  L2SwitchMainModule
 453
 454    -  Reads config subsystem value for *is-install-dropall-flow*
 455
 456       -  If *is-install-dropall-flow* is true, then an
 457          **InitialFlowWriter** is created
 458
 459    -  Reads config subsystem value for *is-learning-only-mode*
 460
 461       -  If *is-learning-only-mode* is false, then a
 462          **ReactiveFlowWriter** is created
 463
 464 -  InitialFlowWriter
 465
 466    -  Only created when *is-install-dropall-flow* is true
 467
 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.
 471
 472 -  ReactiveFlowWriter
 473
 474    -  Reacts to network traffic and installs MAC-to-MAC flows on
 475       switches. These flows have matches based on MAC source and MAC
 476       destination.
 477
 478    -  Uses **FlowWriterServiceImpl** to write these flows to the
 479       switches
 480
 481 -  FlowWriterService / FlowWriterServiceImpl
 482
 483    -  Writes flows to switches
 484
 485 Configuration
 486 ^^^^^^^^^^^^^
 487
 488 -  is-install-dropall-flow
 489
 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
 492       to the controller
 493
 494    -  "false" means this flow will not be installed
 495
 496 -  dropall-flow-table-id
 497
 498    -  The dropall flow will be installed on the specified flow table of
 499       each switch
 500
 501    -  This field is only relevant when "is-install-dropall-flow" is set
 502       to "true"
 503
 504 -  dropall-flow-priority
 505
 506    -  The dropall flow will be installed with the specified priority
 507
 508    -  This field is only relevant when "is-install-dropall-flow" is set
 509       to "true"
 510
 511 -  dropall-flow-idle-timeout
 512
 513    -  The dropall flow will timeout (removed from the switch) if the
 514       flow doesn’t forward a packet for *x* seconds
 515
 516    -  This field is only relevant when "is-install-dropall-flow" is set
 517       to "true"
 518
 519 -  dropall-flow-hard-timeout
 520
 521    -  The dropall flow will timeout (removed from the switch) after *x*
 522       seconds, regardless of how many packets it is forwarding
 523
 524    -  This field is only relevant when "is-install-dropall-flow" is set
 525       to "true"
 526
 527 -  is-learning-only-mode
 528
 529    -  "true" means that the L2Switch will only be learning addresses. No
 530       additional flows to optimize network traffic will be installed.
 531
 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.
 535
 536 -  reactive-flow-table-id
 537
 538    -  The reactive flow will be installed on the specified flow table of
 539       each switch
 540
 541    -  This field is only relevant when "is-learning-only-mode" is set to
 542       "false"
 543
 544 -  reactive-flow-priority
 545
 546    -  The reactive flow will be installed with the specified priority
 547
 548    -  This field is only relevant when "is-learning-only-mode" is set to
 549       "false"
 550
 551 -  reactive-flow-idle-timeout
 552
 553    -  The reactive flow will timeout (removed from the switch) if the
 554       flow doesn’t forward a packet for *x* seconds
 555
 556    -  This field is only relevant when "is-learning-only-mode" is set to
 557       "false"
 558
 559 -  reactive-flow-hard-timeout
 560
 561    -  The reactive flow will timeout (removed from the switch) after *x*
 562       seconds, regardless of how many packets it is forwarding
 563
 564    -  This field is only relevant when "is-learning-only-mode" is set to
 565       "false"
 566
 567 Further development
 568 ^^^^^^^^^^^^^^^^^^^
 569
 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.
 576
 577 API Reference Documentation
 578 ---------------------------
 579
 580 Further documentation can be found by checking out the L2Switch project.
 581
 582 Checking out the L2Switch project
 583 ---------------------------------
 584
 585 ::
 586
 587     git clone https://git.opendaylight.org/gerrit/p/l2switch.git
 588
 589 The above command will create a directory called "l2switch" with the
 590 project.
 591
 592 Testing your changes to the L2Switch project
 593 --------------------------------------------
 594
 595 Running the L2Switch project
 596 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 597
 598 To run the base distribution, you can use the following command
 599
 600 ::
 601
 602     ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
 603
 604 If you need additional resources, you can use these command line
 605 arguments:
 606
 607 ::
 608
 609     -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
 610
 611 To run the karaf distribution, you can use the following command:
 612
 613 ::
 614
 615     ./distribution/karaf/target/assembly/bin/karaf
 616
 617 Create a network using mininet
 618 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 619
 620 ::
 621
 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
 624
 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
 628
 629 ::
 630
 631     sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 632
 633 The above command has the "mac" option, which makes it easier to
 634 distinguish between Host MAC addresses and Switch MAC addresses.
 635
 636 Generating network traffic using mininet
 637 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 638
 639 ::
 640
 641     h1 ping h2
 642
 643 The above command will cause host1 (h1) to ping host2 (h2)
 644
 645 ::
 646
 647     pingall
 648
 649 *pingall* will cause each host to ping every other host.
 650
 651 Miscellaneous mininet commands
 652 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 653
 654 ::
 655
 656     link s1 s2 down
 657
 658 This will bring the link between switch1 (s1) and switch2 (s2) down
 659
 660 ::
 661
 662     link s1 s2 up
 663
 664 This will bring the link between switch1 (s1) and switch2 (s2) up
 665
 666 ::
 667
 668     link s1 h1 down
 669
 670 This will bring the link between switch1 (s1) and host1 (h1) down
 671