[ovs-dev] [PATCH] Documentation: Add Faucet tutorial.

Stephen Finucane 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:
> http://conference.faucet.nz/schedule/
> 
> 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?

Stephen

> ---
>  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
> b/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
> may
> +      not use this file except in compliance with the License. You may
> obtain
> +      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,
> WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
> the
> +      License for the specific language governing permissions and
> limitations
> +      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
> the
> +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
> other
> +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
> issues.
> +We hope that this demonstration makes it easier for users and potential
> users
> +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
> it
> +with Faucet for the tutorial.
> +
> +You might already have Open vSwitch installed on one or more computers or
> VMs,
> +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
> based
> +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
> is
> +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
> and
> +thus better tested, but both should work.  The instructions below explain
> both
> +approaches:
> +
> +1. Get a copy of the Open vSwitch source repository using Git, then ``cd``
> into
> +   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
> system,
> +   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
> 3.
> +   If you do have an installed copy and you want to use it for the sandbox,
> try
> +   to start the sandbox by running::
> +
> +     $ tutorial/ovs-sandbox
> +
> +   If it is successful, you will find yourself in a subshell environment,
> which
> +   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
> build
> +   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):

  :doc:`/intro/install/general`.

> +   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
> +
> +Overview
> +--------
> +
> +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:

  Faucet
    As the top-level (something?) in the system, this is the authoritative
    source ...

    ...

  The OpenFlow subsystem in Open vSwitch
    OpenFlow is the protocol...


[snip]

> +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 mailing list