manuals/user-guide/src/main/asciidoc/l2switch/l2switch-user.adoc

   1 == L2Switch User Guide
   2
   3 === Overview
   4 The L2Switch project provides Layer2 switch functionality.
   5
   6 === L2Switch Architecture
   7 * Packet Handler
   8   ** Decodes the packets coming to the controller and dispatches them appropriately
   9 * Loop Remover
  10   ** Removes loops in the network
  11 * Arp Handler
  12   ** Handles the decoded ARP packets
  13 * Address Tracker
  14   ** Learns the Addresses (MAC and IP) of entities in the network
  15 * Host Tracker
  16   ** Tracks the locations of hosts in the network
  17 * L2Switch Main
  18   ** Installs flows on each switch based on network traffic
  19
  20 === Configuring L2Switch
  21 This sections below give details about the configuration settings for the components that can be configured.
  22
  23 //The base distribution configuration files are located in distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial
  24
  25 //The karaf distribution configuration files are located in distribution/karaf/target/assembly/etc/opendaylight/karaf
  26
  27 === Configuring Loop Remover
  28 * 52-loopremover.xml
  29   ** is-install-lldp-flow
  30     *** "true" means a flow that sends all LLDP packets to the controller will be installed on each switch
  31     *** "false" means this flow will not be installed
  32   ** lldp-flow-table-id
  33     *** The LLDP flow will be installed on the specified flow table of each switch
  34     *** This field is only relevant when "is-install-lldp-flow" is set to "true"
  35   ** lldp-flow-priority
  36     *** The LLDP flow will be installed with the specified priority
  37     *** This field is only relevant when "is-install-lldp-flow" is set to "true"
  38   ** lldp-flow-idle-timeout
  39     *** The LLDP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
  40     *** This field is only relevant when "is-install-lldp-flow" is set to "true"
  41   ** lldp-flow-hard-timeout
  42     *** The LLDP flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
  43     *** This field is only relevant when "is-install-lldp-flow" is set to "true"
  44   ** graph-refresh-delay
  45     *** A graph of the network is maintained and gets updated as network elements go up/down (i.e. links go up/down and switches go up/down)
  46     *** After a network element going up/down, it waits _graph-refresh-delay_ seconds before recomputing the graph
  47     *** A higher value has the advantage of doing less graph updates, at the potential cost of losing some packets because the graph didn't update immediately.
  48     *** A lower value has the advantage of handling network topology changes quicker, at the cost of doing more computation.
  49
  50 === Configuring Arp Handler
  51 * 54-arphandler.xml
  52   ** is-proactive-flood-mode
  53     *** "true" means that flood flows will be installed on each switch.  With this flood flow, each switch will flood a packet that doesn't match any other flows.
  54       **** Advantage: Fewer packets are sent to the controller because those packets are flooded to the network.
  55       **** Disadvantage: A lot of network traffic is generated.
  56     *** "false" means the previously mentioned flood flows will not be installed.  Instead an ARP flow will be installed on each switch that sends all ARP packets to the controller.
  57       **** Advantage: Less network traffic is generated.
  58       **** Disadvantage: The controller handles more packets (ARP requests & replies) and the ARP process takes longer than if there were flood flows.
  59   ** flood-flow-table-id
  60     *** The flood flow will be installed on the specified flow table of each switch
  61     *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
  62   ** flood-flow-priority
  63     *** The flood flow will be installed with the specified priority
  64     *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
  65   ** flood-flow-idle-timeout
  66     *** The flood flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
  67     *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
  68   ** flood-flow-hard-timeout
  69     *** The flood flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
  70     *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
  71   ** arp-flow-table-id
  72     *** The ARP flow will be installed on the specified flow table of each switch
  73     *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
  74   ** arp-flow-priority
  75     *** The ARP flow will be installed with the specified priority
  76     *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
  77   ** arp-flow-idle-timeout
  78     *** The ARP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
  79     *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
  80   ** arp-flow-hard-timeout
  81     *** The ARP flow will timeout (removed from the switch) after _arp-flow-hard-timeout_ seconds, regardless of how many packets it is forwarding
  82     *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
  83
  84 === Configuring Address Tracker
  85 * 56-addresstracker.xml
  86   ** timestamp-update-interval
  87     *** A last-seen timestamp is associated with each address.  This last-seen timestamp will only be updated after _timestamp-update-interval_ milliseconds.
  88     *** A higher value has the advantage of performing less writes to the database.
  89     *** A lower value has the advantage of knowing how fresh an address is.
  90   ** observe-addresses-from
  91     *** IP and MAC addresses can be observed/learned from ARP, IPv4, and IPv6 packets.  Set which packets to make these observations from.
  92
  93 === Configuring L2Switch Main
  94 * 58-l2switchmain.xml
  95   ** is-install-dropall-flow
  96     *** "true" means a drop-all flow will be installed on each switch, so the default action will be to drop a packet instead of sending it to the controller
  97     *** "false" means this flow will not be installed
  98   ** dropall-flow-table-id
  99     *** The dropall flow will be installed on the specified flow table of each switch
 100     *** This field is only relevant when "is-install-dropall-flow" is set to "true"
 101   ** dropall-flow-priority
 102     *** The dropall flow will be installed with the specified priority
 103     *** This field is only relevant when "is-install-dropall-flow" is set to "true"
 104   ** dropall-flow-idle-timeout
 105     *** The dropall flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
 106     *** This field is only relevant when "is-install-dropall-flow" is set to "true"
 107   ** dropall-flow-hard-timeout
 108     *** The dropall flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
 109     *** This field is only relevant when "is-install-dropall-flow" is set to "true"
 110   ** is-learning-only-mode
 111     *** "true" means that the L2Switch will only be learning addresses.  No additional flows to optimize network traffic will be installed.
 112     *** "false" means that the L2Switch will react to network traffic and install flows on the switches to optimize traffic.  Currently, MAC-to-MAC flows are installed.
 113   ** reactive-flow-table-id
 114     *** The reactive flow will be installed on the specified flow table of each switch
 115     *** This field is only relevant when "is-learning-only-mode" is set to "false"
 116   ** reactive-flow-priority
 117     *** The reactive flow will be installed with the specified priority
 118     *** This field is only relevant when "is-learning-only-mode" is set to "false"
 119   ** reactive-flow-idle-timeout
 120     *** The reactive flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
 121     *** This field is only relevant when "is-learning-only-mode" is set to "false"
 122   ** reactive-flow-hard-timeout
 123     *** The reactive flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
 124     *** This field is only relevant when "is-learning-only-mode" is set to "false"
 125
 126 === Running the L2Switch project
 127
 128 To run the L2 Switch inside the Lithium OpenDaylight distribution simply install the `odl-l2switch-switch-ui` feature;
 129
 130  feature:install odl-l2switch-switch-ui
 131
 132 //==== Check out the project using git
 133 // git clone https://git.opendaylight.org/gerrit/p/l2switch.git
 134 //
 135 //The above command will create a directory called "l2switch" with the project.
 136 //
 137 //==== Run the distribution
 138 //To run the base distribution, you can use the following command
 139 //
 140 // ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
 141 //
 142 //If you need additional resources, you can use these command line arguments:
 143 //
 144 // -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
 145 //
 146 //To run the karaf distribution, you can use the following command:
 147 //
 148 // ./distribution/karaf/target/assembly/bin/karaf
 149
 150 === Create a network using mininet
 151  sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 152  sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 153
 154 The above command will create a virtual network consisting of 3 switches.
 155 Each switch will connect to the controller located at the specified IP, i.e. 127.0.0.1
 156
 157  sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
 158
 159 The above command has the "mac" option, which makes it easier to distinguish between Host MAC addresses and Switch MAC addresses.
 160
 161 === Generating network traffic using mininet
 162  h1 ping h2
 163
 164 The above command will cause host1 (h1) to ping host2 (h2)
 165
 166  pingall
 167
 168 'pingall' will cause each host to ping every other host.
 169
 170 === Checking Address Observations
 171 Address Observations are added to the Inventory data tree.
 172
 173 The Address Observations on a Node Connector can be checked through a browser or a REST Client.
 174
 175  http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
 176
 177 .Address Observations
 178 image::l2switch-address-observations.png["AddressObservations image",width=500]
 179
 180 === Checking Hosts
 181 Host information is added to the Topology data tree.
 182
 183 * Host address
 184 * Attachment point (link) to a node/switch
 185
 186 This host information and attachment point information can be checked through a browser or a REST Client.
 187
 188  http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
 189
 190 .Hosts
 191 image::l2switch-hosts.png["Hosts image",width=500]
 192
 193 === Checking STP status of each link
 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 flowing on it.
 197 * A status of "discarding" means the link is inactive and packets are not sent over it.
 198
 199 The STP status of a link can be checked through a browser or a REST Client.
 200
 201  http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
 202
 203 .STP status
 204 image::l2switch-stp-status.png["STPStatus image",width=500]
 205
 206 === Miscellaneous mininet commands
 207  link s1 s2 down
 208
 209 This will bring the link between switch1 (s1) and switch2 (s2) down
 210
 211  link s1 s2 up
 212
 213 This will bring the link between switch1 (s1) and switch2 (s2) up
 214
 215  link s1 h1 down
 216
 217 This will bring the link between switch1 (s1) and host1 (h1) down
 218