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

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