[ovs-dev] [PATCH] Documentation: Add Faucet tutorial.
stephen at that.guru
Thu Oct 19 09:41:26 UTC 2017
On Wed, 2017-10-18 at 14:05 -0700, Ben Pfaff wrote:
> This is for a talk at the Faucet conference on Oct. 19:
> Signed-off-by: Ben Pfaff <blp at ovn.org>
Spotted a few small issues while skimming this. Did this build correctly and
did the output HTML look OK?
> Documentation/automake.mk | 1 +
> Documentation/tutorials/faucet.rst | 1462
> Documentation/tutorials/index.rst | 1 +
> 3 files changed, 1464 insertions(+)
> create mode 100644 Documentation/tutorials/faucet.rst
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 6f38912f264b..da482b419887 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -23,6 +23,7 @@ DOC_SOURCE = \
> Documentation/intro/install/windows.rst \
> Documentation/intro/install/xenserver.rst \
> Documentation/tutorials/index.rst \
> + Documentation/tutorials/faucet.rst \
> Documentation/tutorials/ovs-advanced.rst \
> Documentation/tutorials/ovn-openstack.rst \
> Documentation/tutorials/ovn-sandbox.rst \
> diff --git a/Documentation/tutorials/faucet.rst
> new file mode 100644
> index 000000000000..67c663649f72
> --- /dev/null
> +++ b/Documentation/tutorials/faucet.rst
> @@ -0,0 +1,1462 @@
> + Licensed under the Apache License, Version 2.0 (the "License"); you
> + not use this file except in compliance with the License. You may
> + a copy of the License at
> + http://www.apache.org/licenses/LICENSE-2.0
> + Unless required by applicable law or agreed to in writing, software
> + distributed under the License is distributed on an "AS IS" BASIS,
> + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
> + License for the specific language governing permissions and
> + under the License.
> + Convention for heading levels in Open vSwitch documentation:
> + ======= Heading 0 (reserved for the title in a document)
> + ------- Heading 1
> + ~~~~~~~ Heading 2
> + +++++++ Heading 3
> + ''''''' Heading 4
> + Avoid deeper levels because they do not render well.
> +OVS Faucet Tutorial
> +This tutorial demonstrates how Open vSwitch works with a controller, using
> +Faucet controller as a simple way to get started. It was tested with the
> +"master" branch of Open vSwitch and version 1.6.7 of Faucet in October 2017.
> +It does not use advanced or recently added features in OVS or Faucet, so
> +versions of both pieces of software are likely to work equally well.
> +The goal of the tutorial is to demonstrate Open vSwitch and Faucet in an
> +end-to-end way, that is, to show how it works from the Faucet controller
> +configuration at the top, through the OpenFlow flow table, to the datapath
> +processing. Along the way, in addition to helping to understand the
> +architecture at each level, we discuss performance and troubleshooting
> +We hope that this demonstration makes it easier for users and potential
> +to understand how Open vSwitch works and how to debug and troubleshoot it.
> +We provide enough details in the tutorial that you should be able to fully
> +follow along by following the instructions.
> +Setting Up OVS
> +This section explains to how to set up Open vSwitch for the purpose of using
> +with Faucet for the tutorial.
> +You might already have Open vSwitch installed on one or more computers or
> +perhaps set up to control a set of VMs or a physical network. This is
> +admirable, but we will be using Open vSwitch in a different way to set up a
> +simulation environment called the OVS "sandbox". The sandbox does not use
> +virtual machines or containers, which makes it more limited than setups
> +on those kinds of setups, but on the other hand it is also (in this writer's
> +opinion) easier to set up.
> +There are two ways to start a sandbox: one that uses the Open vSwitch that
> +already installed on a system, and another that uses a copy of Open vSwitch
> +that has been built but not yet installed. The latter is more often used
> +thus better tested, but both should work. The instructions below explain
> +1. Get a copy of the Open vSwitch source repository using Git, then ``cd``
> + the new directory::
> + $ git clone https://github.com/openvswitch/ovs.git
> + $ cd ovs
> + The default checkout is the master branch. You can check out a tag
> + (such as v2.8.0) or a branch (such as origin/branch-2.8), if you
> + prefer.
> +2. If you do not already have an installed copy of Open vSwitch on your
> + or if you do not want to use it for the sandbox (the sandbox will not
> + disturb the functionality of any existing switches), then proceed to step
> + If you do have an installed copy and you want to use it for the sandbox,
> + to start the sandbox by running::
> + $ tutorial/ovs-sandbox
> + If it is successful, you will find yourself in a subshell environment,
> + is the sandbox (you can exit with ``exit`` or Control+D). If so, you're
> + finished and do not need to complete the rest of the steps. If it fails,
> + you can proceed to step 3 to build Open vSwitch anyway.
> +3. Before you build, you might want to check that your system meets the
> + requirements. Read :doc:``intro/install/general.rst`` to find out. For
I don't imagine this renders - you need to give a relative path or an absolute
path. Absolute are probably easier to comprehend. Also, the suffix is either
not necessary or not allowed (I don't recall):
> + this tutorial, there is no need to compile the Linux kernel module, or to
> + use any of the optional libraries such as OpenSSL, DPDK, or libcap-ng.
> +4. Configure and build Open vSwitch::
> + $ ./boot.sh
> + $ ./configure
> + $ make -j4
> +5. Try out the sandbox by running::
> + $ make sandbox
> + You can exit the sandbox with ``exit`` or Control+D.
> +Setting up Faucet
> +This section explains how to get a copy of Faucet and set it up
> +appropriately for the tutorial. There are many other ways to install
> +Faucet, but this simple approach worked well for me. It has the
> +advantage that it does not require modifying any system-level files or
> +directories on your machine. It does, on the other hand, require
> +Docker, so make sure you have it installed and working.
> +It will be a little easier to go through the rest of the tutorial if
> +you run these instructions in a separate terminal from the one that
> +you're using for Open vSwitch, because it's often necessary to switch
> +between one and the other.
> +1. Get a copy of the Faucet source repository using Git, then ``cd``
> + into the new directory::
> + $ git clone https://github.com/faucetsdn/faucet.git
> + $ cd faucet
> + At this point I checked out the latest tag::
> + $ git checkout v1.6.7
> +2. Build a docker container image::
> + $ docker build -t faucet/faucet .
> + This will take a few minutes.
> +3. Create an installation directory under the ``faucet`` directory for
> + the docker image to use::
> + $ mkdir inst
> + The Faucet configuration will go in ``inst/faucet.yaml`` and its
> + main log will appear in ``inst/faucet.log``. (The official Faucet
> + installation instructions call to put these in ``/etc/ryu/faucet``
> + and ``/var/log/ryu/faucet``, respectively, but we avoid modifying
> + these system directories.)
> +4. Create a container and start Faucet::
> + $ docker run -d --name faucet -v `pwd`/inst/:/etc/ryu/faucet/ -v
> `pwd`/inst/:/var/log/ryu/faucet/ -p 6653:6653 faucet/faucet
Any chance you could wrap this with backslashes?
> +5. Look in ``inst/faucet.log`` to verify that Faucet started. It will
> + probably start with an exception and traceback because we have not
> + yet created ``inst/faucet.yaml``.
> +6. Later on, to make a new or updated Faucet configuration take
> + effect quickly, you can run::
> + $ docker exec faucet pkill -HUP -f faucet.faucet
> + Another way is to stop and start the Faucet container::
> + $ docker restart faucet
> + You can also stop and delete the container; after this, to start it
> + again, you need to rerun the ``docker run`` command::
> + $ docker stop faucet
> + $ docker rm faucet
> +Now that Open vSwitch and Faucet are ready, here's an overview of what
> +we're going to do for the remainder of the tutorial:
> +1. Switching: Set up an L2 network with Faucet.
> +2. Routing: Route between multiple L3 networks with Faucet.
> +3. ACLs: Add and modify access control rules.
> +At each step, we will take a look at how the features in question work
> +from Faucet at the top to the data plane layer at the bottom. From
> +the highest to lowest level, these layers and the software components
> +that connect them are:
> +* Faucet, which as the top level in the system is the authoritative
> + source of the network configuration.
This section would look great as a definition list, were you so inclined:
As the top-level (something?) in the system, this is the authoritative
The OpenFlow subsystem in Open vSwitch
OpenFlow is the protocol...
> +Faucet is now waiting for a switch with datapath ID 0x1 to connect to
> +it over OpenFlow, so our next step is to create a switch with OVS and
> +make it connect to Faucet. To do that, switch to the terminal where
> +you checked out OVS and start a sandbox with ``make sandbox`` or
> +`tutorial/ovs-sandbox`` (as explained earlier under `Setting Up
missing backtick here (``tutorial/ovs-sandbox``)
More information about the dev