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

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