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 <[email protected]>
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``) _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
