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

[Ben Pfaff]

On Thu, Oct 19, 2017 at 10:41:26AM +0100, Stephen Finucane wrote:
> 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?

Yes, I did test that, but only after I sent out the patch.  I found and
fixed some errors, and your feedback is useful too, see below.

> > +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`.

Thanks, fixed.

> > +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?

Looking at this, I guess you must mean the uses of `pwd`.  I decided to
change them to $(pwd).

> > +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...

OK, sure, I made that change.

> > +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``)

Thanks, I fixed that now.