Documentation/tutorials/ovn-sandbox.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ===========
  25 OVN Sandbox
  26 ===========
  27
  28 This tutorial shows you how to explore features using ``ovs-sandbox`` as a
  29 simulated test environment.  It's assumed that you have an understanding of OVS
  30 before going through this tutorial. Detail about OVN is covered in
  31 ovn-architecture_, but this tutorial lets you quickly see it in action.
  32
  33 Getting Started
  34 ---------------
  35
  36 For some general information about ``ovs-sandbox``, see the "Getting Started"
  37 section of the tutorial_.
  38
  39 ``ovs-sandbox`` does not include OVN support by default.  To enable OVN, you
  40 must pass the ``--ovn`` flag.  For example, if running it straight from the ovs
  41 git tree you would run::
  42
  43     $ make sandbox SANDBOXFLAGS="--ovn"
  44
  45 Running the sandbox with OVN enabled does the following additional steps to the
  46 environment:
  47
  48 1. Creates the ``OVN_Northbound`` and ``OVN_Southbound`` databases as described in
  49    `ovn-nb(5)`_ and `ovn-sb(5)`_.
  50
  51 2. Creates a backup server for ``OVN_Southbond`` database. Sandbox launch
  52    screen provides the instructions on accessing the backup database.  However
  53    access to the backup server is not required to go through the tutorial.
  54
  55 3. Creates the ``hardware_vtep`` database as described in `vtep(5)`_.
  56
  57 4. Runs the `ovn-northd(8)`_, `ovn-controller(8)`_, and
  58    `ovn-controller-vtep(8)`_ daemons.
  59
  60 5. Makes OVN and VTEP utilities available for use in the environment, including
  61    `vtep-ctl(8)`_, `ovn-nbctl(8)`_, and `ovn-sbctl(8)`_.
  62
  63 Using GDB
  64 ---------
  65
  66 GDB support is not required to go through the tutorial. See the "Using GDB"
  67 section of the `tutorial`_ for more info. Additional flags exist for launching
  68 the debugger for the OVN programs::
  69
  70     --gdb-ovn-northd
  71     --gdb-ovn-controller
  72     --gdb-ovn-controller-vtep
  73
  74 Creating OVN Resources
  75 ----------------------
  76
  77 Once you have ``ovs-sandbox`` running with OVN enabled, you can start using OVN
  78 utilities to create resources in OVN.  As an example, we will create an
  79 environment that has two logical switches connected by a logical router.
  80
  81 Create the first logical switch with one port::
  82
  83     $ ovn-nbctl ls-add sw0
  84     $ ovn-nbctl lsp-add sw0 sw0-port1
  85     $ ovn-nbctl lsp-set-addresses sw0-port1 "50:54:00:00:00:01 192.168.0.2"
  86
  87 Create the second logical switch with one port::
  88
  89     $ ovn-nbctl ls-add sw1
  90     $ ovn-nbctl lsp-add sw1 sw1-port1
  91     $ ovn-nbctl lsp-set-addresses sw1-port1 "50:54:00:00:00:03 11.0.0.2"
  92
  93 Create the logical router and attach both logical switches::
  94
  95     $ ovn-nbctl lr-add lr0
  96     $ ovn-nbctl lrp-add lr0 lrp0 00:00:00:00:ff:01 192.168.0.1/24
  97     $ ovn-nbctl lsp-add sw0 lrp0-attachment
  98     $ ovn-nbctl lsp-set-type lrp0-attachment router
  99     $ ovn-nbctl lsp-set-addresses lrp0-attachment 00:00:00:00:ff:01
 100     $ ovn-nbctl lsp-set-options lrp0-attachment router-port=lrp0
 101     $ ovn-nbctl lrp-add lr0 lrp1 00:00:00:00:ff:02 11.0.0.1/24
 102     $ ovn-nbctl lsp-add sw1 lrp1-attachment
 103     $ ovn-nbctl lsp-set-type lrp1-attachment router
 104     $ ovn-nbctl lsp-set-addresses lrp1-attachment 00:00:00:00:ff:02
 105     $ ovn-nbctl lsp-set-options lrp1-attachment router-port=lrp1
 106
 107 View a summary of OVN's current logical configuration::
 108
 109     $ ovn-nbctl show
 110         switch 1396cf55-d176-4082-9a55-1c06cef626e4 (sw1)
 111             port lrp1-attachment
 112                 addresses: ["00:00:00:00:ff:02"]
 113             port sw1-port1
 114                 addresses: ["50:54:00:00:00:03 11.0.0.2"]
 115         switch 2c9d6d03-09fc-4e32-8da6-305f129b0d53 (sw0)
 116             port lrp0-attachment
 117                 addresses: ["00:00:00:00:ff:01"]
 118             port sw0-port1
 119                 addresses: ["50:54:00:00:00:01 192.168.0.2"]
 120         router f8377e8c-f75e-4fc8-8751-f3ea03c6dd98 (lr0)
 121             port lrp0
 122                 mac: "00:00:00:00:ff:01"
 123                 networks: ["192.168.0.1/24"]
 124             port lrp1
 125                 mac: "00:00:00:00:ff:02"
 126                 networks: ["11.0.0.1/24"]
 127
 128 The ``tutorial`` directory of the OVS source tree includes a script
 129 that runs all of the commands for you::
 130
 131     $ ./ovn-setup.sh
 132
 133 Using ovn-trace
 134 ---------------
 135
 136 Once you have configured resources in OVN, try using ``ovn-trace`` to see
 137 how OVN would process a sample packet through its logical pipeline.
 138
 139 For example, we can trace an IP packet from ``sw0-port1`` to ``sw0-port2``.
 140 The ``--minimal`` output shows each visible action performed on the packet,
 141 which includes:
 142
 143 #. The logical router will decrement the IP TTL field.
 144 #. The logical router will change the source and destination
 145    MAC addresses to reflect the next hop.
 146 #. The packet will be output to ``sw1-port1``.
 147
 148 ::
 149
 150     $ ovn-trace --minimal sw0 'inport == "sw0-port1" \
 151     > && eth.src == 50:54:00:00:00:01 && ip4.src == 192.168.0.2 \
 152     > && eth.dst == 00:00:00:00:ff:01 && ip4.dst == 11.0.0.2 \
 153     > && ip.ttl == 64'
 154
 155     # ip,reg14=0x1,vlan_tci=0x0000,dl_src=50:54:00:00:00:01,dl_dst=00:00:00:00:ff:01,nw_src=192.168.0.2,nw_dst=11.0.0.2,nw_proto=0,nw_tos=0,nw_ecn=0,nw_ttl=64
 156     ip.ttl--;
 157     eth.src = 00:00:00:00:ff:02;
 158     eth.dst = 50:54:00:00:00:03;
 159     output("sw1-port1");
 160
 161 The ``ovn-trace`` utility can also provide much more detail on how the packet
 162 would be processed through OVN's logical pipeline, as well as correlate that
 163 to OpenFlow flows programmed by ``ovn-controller``.  See the `ovn-trace(8)`_
 164 man page for more detail.
 165
 166
 167 .. _ovn-architecture: http://openvswitch.org/support/dist-docs/ovn-architecture.7.html
 168 .. _Tutorial: :ref:`ovs-advanced`
 169 .. _ovn-nb(5): http://openvswitch.org/support/dist-docs/ovn-nb.5.html
 170 .. _ovn-sb(5): http://openvswitch.org/support/dist-docs/ovn-sb.5.html
 171 .. _vtep(5): http://openvswitch.org/support/dist-docs/vtep.5.html
 172 .. _ovn-northd(8): http://openvswitch.org/support/dist-docs/ovn-northd.8.html
 173 .. _ovn-controller(8): http://openvswitch.org/support/dist-docs/ovn-controller.8.html
 174 .. _ovn-controller-vtep(8): http://openvswitch.org/support/dist-docs/ovn-controller-vtep.8.html
 175 .. _vtep-ctl(8): http://openvswitch.org/support/dist-docs/vtep-ctl.8.html
 176 .. _ovn-nbctl(8): http://openvswitch.org/support/dist-docs/ovn-nbctl.8.html
 177 .. _ovn-sbctl(8): http://openvswitch.org/support/dist-docs/ovn-sbctl.8.html
 178 .. _ovn-trace(8): http://openvswitch.org/support/dist-docs/ovn-trace.8.html