docs/user-guide/l2switch-user-guide.rst

   1 L2 Switch User Guide
   2 ====================
   3
   4 Overview
   5 --------
   6
   7 The L2 Switch project provides Layer2 switch functionality.
   8
   9 L2 Switch 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 -  L2 Switch Main
  34
  35    -  Installs flows on each switch based on network traffic
  36
  37 Configurable parameters in L2 Switch
  38 ------------------------------------
  39
  40 The sections below give details about the configuration settings for
  41 the components that can be configured.
  42
  43 The process to change the configuration has been changed with
  44 the introduction of Blueprint in the Boron release. Please
  45 refer to :ref:`l2switch-change-config` for an
  46 example illustrating how to change the configurations.
  47
  48 Configurable parameters in Loop Remover
  49 ---------------------------------------
  50
  51 -  l2switch/loopremover/implementation/src/main/yang/loop-remover-config.yang
  52
  53    -  is-install-lldp-flow
  54
  55       -  "true" means a flow that sends all LLDP packets to the
  56          controller will be installed on each switch
  57
  58       -  "false" means this flow will not be installed
  59
  60       -  default value is true
  61
  62    -  lldp-flow-table-id
  63
  64       -  The LLDP flow will be installed on the specified flow table of
  65          each switch
  66
  67       -  This field is only relevant when "is-install-lldp-flow" is set
  68          to "true"
  69
  70       -  default value is 0
  71
  72    -  lldp-flow-priority
  73
  74       -  The LLDP flow will be installed with the specified priority
  75
  76       -  This field is only relevant when "is-install-lldp-flow" is set
  77          to "true"
  78
  79       -  default value is 100
  80
  81    -  lldp-flow-idle-timeout
  82
  83       -  The LLDP flow will timeout (removed from the switch) if the
  84          flow doesn’t forward a packet for *x* seconds
  85
  86       -  This field is only relevant when "is-install-lldp-flow" is set
  87          to "true"
  88
  89       -  default value is 0
  90
  91    -  lldp-flow-hard-timeout
  92
  93       -  The LLDP flow will timeout (removed from the switch) after *x*
  94          seconds, regardless of how many packets it is forwarding
  95
  96       -  This field is only relevant when "is-install-lldp-flow" is set
  97          to "true"
  98
  99       -  default value is 0
 100
 101    -  graph-refresh-delay
 102
 103       -  A graph of the network is maintained and gets updated as
 104          network elements go up/down (i.e. links go up/down and switches
 105          go up/down)
 106
 107       -  After a network element going up/down, it waits
 108          *graph-refresh-delay* seconds before recomputing the graph
 109
 110       -  A higher value has the advantage of doing less graph updates,
 111          at the potential cost of losing some packets because the graph
 112          didn’t update immediately.
 113
 114       -  A lower value has the advantage of handling network topology
 115          changes quicker, at the cost of doing more computation.
 116
 117       -  default value is 1000
 118
 119 Configurable parameters in Arp Handler
 120 --------------------------------------
 121
 122 -  l2switch/arphandler/src/main/yang/arp-handler-config.yang
 123
 124    -  is-proactive-flood-mode
 125
 126       -  "true" means that flood flows will be installed on each switch.
 127          With this flood flow, each switch will flood a packet that
 128          doesn’t match any other flows.
 129
 130          -  Advantage: Fewer packets are sent to the controller because
 131             those packets are flooded to the network.
 132
 133          -  Disadvantage: A lot of network traffic is generated.
 134
 135       -  "false" means the previously mentioned flood flows will not be
 136          installed. Instead an ARP flow will be installed on each switch
 137          that sends all ARP packets to the controller.
 138
 139          -  Advantage: Less network traffic is generated.
 140
 141          -  Disadvantage: The controller handles more packets (ARP
 142             requests & replies) and the ARP process takes longer than if
 143             there were flood flows.
 144
 145       -  default value is true
 146
 147    -  flood-flow-table-id
 148
 149       -  The flood flow will be installed on the specified flow table of
 150          each switch
 151
 152       -  This field is only relevant when "is-proactive-flood-mode" is
 153          set to "true"
 154
 155       -  default value is 0
 156
 157    -  flood-flow-priority
 158
 159       -  The flood flow will be installed with the specified priority
 160
 161       -  This field is only relevant when "is-proactive-flood-mode" is
 162          set to "true"
 163
 164       -  default value is 2
 165
 166    -  flood-flow-idle-timeout
 167
 168       -  The flood flow will timeout (removed from the switch) if the
 169          flow doesn’t forward a packet for *x* seconds
 170
 171       -  This field is only relevant when "is-proactive-flood-mode" is
 172          set to "true"
 173
 174       -  default value is 0
 175
 176    -  flood-flow-hard-timeout
 177
 178       -  The flood flow will timeout (removed from the switch) after *x*
 179          seconds, regardless of how many packets it is forwarding
 180
 181       -  This field is only relevant when "is-proactive-flood-mode" is
 182          set to "true"
 183
 184       -  default value is 0
 185
 186    -  arp-flow-table-id
 187
 188       -  The ARP flow will be installed on the specified flow table of
 189          each switch
 190
 191       -  This field is only relevant when "is-proactive-flood-mode" is
 192          set to "false"
 193
 194       -  default value is 0
 195
 196    -  arp-flow-priority
 197
 198       -  The ARP flow will be installed with the specified priority
 199
 200       -  This field is only relevant when "is-proactive-flood-mode" is
 201          set to "false"
 202
 203       -  default value is 1
 204
 205    -  arp-flow-idle-timeout
 206
 207       -  The ARP flow will timeout (removed from the switch) if the flow
 208          doesn’t forward a packet for *x* seconds
 209
 210       -  This field is only relevant when "is-proactive-flood-mode" is
 211          set to "false"
 212
 213       -  default value is 0
 214
 215    -  arp-flow-hard-timeout
 216
 217       -  The ARP flow will timeout (removed from the switch) after
 218          *arp-flow-hard-timeout* seconds, regardless of how many packets
 219          it is forwarding
 220
 221       -  This field is only relevant when "is-proactive-flood-mode" is
 222          set to "false"
 223
 224       -  default value is 0
 225
 226 Configurable parameters in Address Tracker
 227 ------------------------------------------
 228
 229 -  l2switch/addresstracker/implementation/src/main/yang/address-tracker-config.yang
 230
 231    -  timestamp-update-interval
 232
 233       -  A last-seen timestamp is associated with each address. This
 234          last-seen timestamp will only be updated after
 235          *timestamp-update-interval* milliseconds.
 236
 237       -  A higher value has the advantage of performing less writes to
 238          the database.
 239
 240       -  A lower value has the advantage of knowing how fresh an address
 241          is.
 242
 243       -  default value is 600000
 244
 245    -  observe-addresses-from
 246
 247       -  IP and MAC addresses can be observed/learned from ARP, IPv4,
 248          and IPv6 packets. Set which packets to make these observations
 249          from.
 250
 251       -  default value is arp
 252
 253 Configurable parameters in L2 Switch Main
 254 -----------------------------------------
 255
 256 -  l2switch/l2switch-main/src/main/yang/l2switch-config.yang
 257
 258    -  is-install-dropall-flow
 259
 260       -  "true" means a drop-all flow will be installed on each switch,
 261          so the default action will be to drop a packet instead of
 262          sending it to the controller
 263
 264       -  "false" means this flow will not be installed
 265
 266       -  default value is true
 267
 268    -  dropall-flow-table-id
 269
 270       -  The dropall flow will be installed on the specified flow table
 271          of each switch
 272
 273       -  This field is only relevant when "is-install-dropall-flow" is
 274          set to "true"
 275
 276       -  default value is 0
 277
 278    -  dropall-flow-priority
 279
 280       -  The dropall flow will be installed with the specified priority
 281
 282       -  This field is only relevant when "is-install-dropall-flow" is
 283          set to "true"
 284
 285       -  default value is 0
 286
 287    -  dropall-flow-idle-timeout
 288
 289       -  The dropall flow will timeout (removed from the switch) if the
 290          flow doesn’t forward a packet for *x* seconds
 291
 292       -  This field is only relevant when "is-install-dropall-flow" is
 293          set to "true"
 294
 295       -  default value is 0
 296
 297    -  dropall-flow-hard-timeout
 298
 299       -  The dropall flow will timeout (removed from the switch) after
 300          *x* seconds, regardless of how many packets it is forwarding
 301
 302       -  This field is only relevant when "is-install-dropall-flow" is
 303          set to "true"
 304
 305       -  default value is 0
 306
 307    -  is-learning-only-mode
 308
 309       -  "true" means that the L2 Switch will only be learning addresses.
 310          No additional flows to optimize network traffic will be
 311          installed.
 312
 313       -  "false" means that the L2 Switch will react to network traffic
 314          and install flows on the switches to optimize traffic.
 315          Currently, MAC-to-MAC flows are installed.
 316
 317       -  default value is false
 318
 319    -  reactive-flow-table-id
 320
 321       -  The reactive flow will be installed on the specified flow table
 322          of each switch
 323
 324       -  This field is only relevant when "is-learning-only-mode" is set
 325          to "false"
 326
 327       -  default value is 0
 328
 329    -  reactive-flow-priority
 330
 331       -  The reactive flow will be installed with the specified priority
 332
 333       -  This field is only relevant when "is-learning-only-mode" is set
 334          to "false"
 335
 336       -  default value is 10
 337
 338    -  reactive-flow-idle-timeout
 339
 340       -  The reactive flow will timeout (removed from the switch) if the
 341          flow doesn’t forward a packet for *x* seconds
 342
 343       -  This field is only relevant when "is-learning-only-mode" is set
 344          to "false"
 345
 346       -  default value is 600
 347
 348    -  reactive-flow-hard-timeout
 349
 350       -  The reactive flow will timeout (removed from the switch) after
 351          *x* seconds, regardless of how many packets it is forwarding
 352
 353       -  This field is only relevant when "is-learning-only-mode" is set
 354          to "false"
 355
 356       -  default value is 300
 357
 358 .. _l2switch-change-config:
 359
 360 Change configuration in L2 Switch
 361 ---------------------------------
 362
 363 .. note:: For more information on Blueprint in OpenDaylight, see `this wiki page <https://wiki.opendaylight.org/view/Using_Blueprint>`_.
 364
 365 The following is an example on how to change the configurations of the L2 Switch components.
 366
 367 **Use Case:** Change the L2 switch from proactive flood mode to reactive mode.
 368
 369 **Option 1:** (external xml file)
 370
 371 #. Navigate to etc folder under download distribution
 372 #. Create following directory structure::
 373
 374       mkdir - p opendaylight/datastore/initial/config
 375
 376 #. Create a new xml file corresponding to ``<yang module name>_<container name>.xml``::
 377
 378       vi arp-handler-config_arp-handler-config.xml
 379
 380 #. Add following contents to the created file::
 381
 382       <?xml version="1.0" encoding="UTF-8"?>
 383         <arp-handler-config xmlns="urn:opendaylight:packet:arp-handler-config">
 384         <is-proactive-flood-mode>false</is-proactive-flood-mode>
 385       </arp-handler-config>
 386
 387 #. Restart the controller which injects the configurations.
 388
 389 **Option 2:** (REST URL)
 390
 391 #. Make the following REST call
 392
 393    * *URL:* ``http://{{LOCALIP}}:8181/restconf/config/arp-handler-config:arp-handler-config/``
 394    * *Content-Type:* application/json
 395    * *Body*::
 396
 397          {
 398            "arp-handler-config":
 399            {
 400              "is-proactive-flood-mode":false
 401            }
 402          }
 403
 404    * *Expected Result:* 201 Created
 405
 406 #. Restart the controller to see updated configurations. With out a restart
 407    new configurations will be merged with old configurations which is not desirable.
 408
 409 Running the L2 Switch
 410 ---------------------
 411
 412 To run the L2 Switch inside the OpenDaylight distribution simply
 413 install the ``odl-l2switch-switch-ui`` feature;
 414
 415 ::
 416
 417     feature:install odl-l2switch-switch-ui
 418
 419 Create a network using mininet
 420 ------------------------------
 421
 422 ::
 423
 424     sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 425     sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 426
 427 The above command will create a virtual network consisting of 3
 428 switches. Each switch will connect to the controller located at the
 429 specified IP, i.e. 127.0.0.1
 430
 431 ::
 432
 433     sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 434
 435 The above command has the "mac" option, which makes it easier to
 436 distinguish between Host MAC addresses and Switch MAC addresses.
 437
 438 Generating network traffic using mininet
 439 ----------------------------------------
 440
 441 ::
 442
 443     h1 ping h2
 444
 445 The above command will cause host1 (h1) to ping host2 (h2)
 446
 447 ::
 448
 449     pingall
 450
 451 *pingall* will cause each host to ping every other host.
 452
 453 Checking Address Observations
 454 -----------------------------
 455
 456 Address Observations are added to the Inventory data tree.
 457
 458 The Address Observations on a Node Connector can be checked through a
 459 browser or a REST Client.
 460
 461 ::
 462
 463     http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
 464
 465 .. figure:: ./images/l2switch-address-observations.png
 466    :alt: Address Observations
 467
 468    Address Observations
 469
 470 Checking Hosts
 471 --------------
 472
 473 Host information is added to the Topology data tree.
 474
 475 -  Host address
 476
 477 -  Attachment point (link) to a node/switch
 478
 479 This host information and attachment point information can be checked
 480 through a browser or a REST Client.
 481
 482 ::
 483
 484     http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
 485
 486 .. figure:: ./images/l2switch-hosts.png
 487    :alt: Hosts
 488
 489    Hosts
 490
 491 Checking STP status of each link
 492 --------------------------------
 493
 494 STP Status information is added to the Inventory data tree.
 495
 496 -  A status of "forwarding" means the link is active and packets are
 497    flowing on it.
 498
 499 -  A status of "discarding" means the link is inactive and packets are
 500    not sent over it.
 501
 502 The STP status of a link can be checked through a browser or a REST
 503 Client.
 504
 505 ::
 506
 507     http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
 508
 509 .. figure:: ./images/l2switch-stp-status.png
 510    :alt: STP status
 511
 512    STP status
 513
 514 Miscellaneous mininet commands
 515 ------------------------------
 516
 517 ::
 518
 519     link s1 s2 down
 520
 521 This will bring the link between switch1 (s1) and switch2 (s2) down
 522
 523 ::
 524
 525     link s1 s2 up
 526
 527 This will bring the link between switch1 (s1) and switch2 (s2) up
 528
 529 ::
 530
 531     link s1 h1 down
 532
 533 This will bring the link between switch1 (s1) and host1 (h1) down
 534