Added missing file

docs: Incorporate Javier's progressive VPP tutorial

Change-Id: Iecee041039c7ed81713bc0530fc536e989c71497
Signed-off-by: John DeNisco <jdenisco@cisco.com>

docs/gettingstarted/users/configutil/installing.rst

@@ -2,9 +2,11 @@
 
 .. toctree::
 
-**********
-Installing
-**********
+.. _installing-vpp-config:
+
+*********************
+Installing VPP-Config
+*********************
 
 The FD.io VPP configuration utility uses the `Python Package Index <https://pypi.org>`__
 or "pypi".

docs/gettingstarted/writingdocs/gitreview.rst

@@ -66,6 +66,7 @@ To modify an existing patch:
 
 .. code-block:: console
 
+    $ git review -d <review number>
     $ git status
     $ git add <filename>
     $ git commit --amend

docs/gettingstarted/writingdocs/todo.rst

@@ -43,11 +43,6 @@ The getting started users guide needs an overview
 This section should be references to the doxygen links. The doxygen links will need to be cleaned up.
 This section could be a quick reference only using commands we have tested.
 
-:ref:`progressivevpp`
-=====================
-
-This section needs work. It needs to be split up and tested.
-
 :ref:`vswitchrtr`
 =================
 

docs/guides/progressivevpp/index.rst

@@ -1,9 +1,176 @@
 .. _progressivevpp:
 
-=========================================
-Progressive VPP Tutorial
-=========================================
-
 .. toctree::
 
-    vagrant
+########################
+Progressive VPP Tutorial
+########################
+
+Overview
+========
+
+Learn to run FD.io VPP on a single Ubuntu 16.04 VM using Vagrant with this walkthrough
+covering basic FD.io VPP senarios. Useful FD.io VPP commands will be used, and
+will discuss basic operations, and the state of a running FD.io VPP on a system.
+
+.. note::
+
+    This is *not* intended to be a 'How to Run in a Production Environment' set of instructions.
+
+.. _introduction-to-vpp-vagrant:
+
+Setting up your environment
+===========================
+
+All of these exercises are designed to be performed on an Ubuntu 16.04 (Xenial) box.
+
+* If you have an Ubuntu 16.04 box on which you have sudo or root access, you can feel free to use that.
+* If you do not, a Vagrantfile is provided to setup a basic Ubuntu 16.04 box for you in the the steps below.
+
+Running Vagrant
+===============
+
+FD.io VPP runs in userspace.  In a production environment you will often run it with DPDK to connect to real NICs or vhost to connect to VMs.
+In those circumstances you usually run a single instance of FD.io VPP.
+
+For purposes of this tutorial, it is going to be extremely useful to run multiple instances of vpp, and connect them to each other to form
+a topology.  Fortunately, FD.io VPP supports this.
+
+When running multiple FD.io VPP instances, each instance needs to have specified a 'name' or 'prefix'.  In the example below, the 'name' or 'prefix' is "vpp1". Note that only one instance can use the dpdk plugin, since this plugin is trying to acquire a lock on a file.
+
+.. toctree::
+
+    settingupenvironment.rst
+
+The DPDK Plugin will be disabled for this section. The link below demonstrates how this is done.
+
+.. toctree::
+
+    removedpdkplugin.rst
+
+Start a FD.io VPP shell using vppctl
+====================================
+
+The command *$ sudo vppctl* will launch a FD.io VPP shell with which you can run multiple FD.io VPP commands interactively by running:
+
+.. code-block:: console
+
+    $ sudo vppctl
+       _______    _        _   _____  ___
+    __/ __/ _ \  (_)__    | | / / _ \/ _ \
+    _/ _// // / / / _ \   | |/ / ___/ ___/
+    /_/ /____(_)_/\___/   |___/_/  /_/
+    vpp# show ver
+    vpp v18.07-release built by root on c469eba2a593 at Mon Jul 30 23:27:03 UTC 2018
+
+Create an Interface
+===================
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+#. Create a veth interface in Linux host
+#. Assign an IP address to one end of the veth interface in the Linux host
+#. Create a vpp host-interface that connected to one end of a veth interface via AF_PACKET
+#. Add an ip address to a vpp interface
+
+.. toctree::
+
+    interface.rst
+
+Traces
+======
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+#. Setup a 'trace'
+#. View a 'trace'
+#. Clear a 'trace'
+#. Verify using ping from host
+#. Ping from vpp
+#. Examine Arp Table
+#. Examine ip fib
+
+.. toctree::
+
+    traces.rst
+
+Routing
+=======
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+In this exercise you will learn these new skills:
+
+#. Add route to Linux Host routing table
+#. Add route to FD.io VPP routing table
+
+And revisit the old ones:
+
+#. Examine FD.io VPP routing table
+#. Enable trace on vpp1 and vpp2
+#. ping from host to FD.io VPP
+#. Examine and clear trace on vpp1 and vpp2
+#. ping from FD.io VPP to host
+#. Examine and clear trace on vpp1 and vpp2
+
+
+.. toctree::
+
+    routing.rst
+
+Connecting Two FD.io VPP Instances
+==================================
+
+memif is a very high performance, direct memory interface type which can
+be used between FD.io VPP instances to form a topology. It uses a file socket
+for a control channel to set up that shared memory.
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+You will learn the following new skill in this exercise:
+
+#. Create a memif interface between two FD.io VPP instances
+
+You should be able to perform this exercise with the following skills
+learned in previous exercises:
+
+#. Run a second FD.io VPP instance
+#. Add an ip address to a FD.io VPP interface
+#. Ping from FD.io VPP
+
+.. toctree::
+
+    twovppinstances.rst
+
+Switching
+=========
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+#. Associate an interface with a bridge domain
+#. Create a loopback interaface
+#. Create a BVI (Bridge Virtual Interface) for a bridge domain
+#. Examine a bridge domain
+
+.. toctree::
+
+    switching.rst
+
+Source NAT
+==========
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+#. Abusing networks namespaces for fun and profit
+#. Configuring snat address
+#. Configuring snat inside and outside interfaces
+
+.. toctree::
+
+    sourceNAT.rst

docs/guides/progressivevpp/interface.rst

@@ -0,0 +1,126 @@
+.. _interface:
+
+.. toctree::
+
+Interface
+=========
+
+VPP command learned in this exercise
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#. `create host-interface <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_devices_af_packet.html#clicmd_create_host-interface>`_
+#. `set int state <https://docs.fd.io/vpp/17.04/clicmd_src_vnet.html#clicmd_set_interface_state>`_
+#. `set int ip address <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_ip.html#clicmd_set_interface_ip_address>`_
+#. `show hardware <https://docs.fd.io/vpp/17.04/clicmd_src_vnet.html#clicmd_show_hardware-interfaces>`_
+#. `show int <https://docs.fd.io/vpp/17.04/clicmd_src_vnet.html#clicmd_show_interfaces>`_
+#. `show int addr <https://docs.fd.io/vpp/17.04/clicmd_src_vnet.html#clicmd_show_interfaces>`_
+#. `trace add <https://docs.fd.io/vpp/17.04/clicmd_src_vlib.html#clicmd_trace_add>`_
+#. `clear trace <https://docs.fd.io/vpp/17.04/clicmd_src_vlib.html#clicmd_clear_trace>`_
+#. `ping <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_ip.html#clicmd_ping>`_
+#. `show ip arp <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_ethernet.html#clicmd_show_ip_arp>`_
+#. `show ip fib <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_fib.html#clicmd_show_ip_fib>`_
+
+Topology
+~~~~~~~~
+
+.. figure:: /_images/Create_Interface_Topology.jpg
+  :alt: Figure: Create Interface Topology
+
+  Figure: Create Interface Topology
+
+Initial State
+~~~~~~~~~~~~~
+
+The initial state here is presumed to be the final state from the
+exercise `VPP Basics <VPP/Progressive_VPP_Tutorial#Exercise:_vpp_basics>`__
+ 
+Create veth interfaces on host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Linux, there is a type of interface call 'veth'. Think of a 'veth'
+interface as being an interface that has two ends to it (rather than
+one).
+
+Create a veth interface with one end named **vpp1out** and the other
+named **vpp1host**
+
+.. code-block:: console
+
+  $ sudo ip link add name vpp1out type veth peer name vpp1host
+
+Turn up both ends:
+
+.. code-block:: console
+
+  $ sudo ip link set dev vpp1out up
+  $ sudo ip link set dev vpp1host up
+
+Assign an IP address
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+  $ sudo ip addr add 10.10.1.1/24 dev vpp1host
+
+Display the result:
+
+.. code-block:: console
+
+  $ sudo ip addr show vpp1host
+  5: vpp1host@vpp1out: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether e2:0f:1e:59:ec:f7 brd ff:ff:ff:ff:ff:ff
+    inet 10.10.1.1/24 scope global vpp1host
+       valid_lft forever preferred_lft forever
+    inet6 fe80::e00f:1eff:fe59:ecf7/64 scope link
+       valid_lft forever preferred_lft forever
+
+Create vpp host-interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a host interface attached to **vpp1out**.
+
+.. code-block:: console
+
+  vpp# create host-interface name vpp1out
+  host-vpp1out
+
+Confirm the interface:
+
+.. code-block:: console
+
+  vpp# show hardware
+                Name                Idx   Link  Hardware
+  host-vpp1out                       1     up   host-vpp1out
+  Ethernet address 02:fe:d9:75:d5:b4
+  Linux PACKET socket interface
+  local0                             0    down  local0
+  local
+
+Turn up the interface:
+
+.. code-block:: console
+
+  vpp# set int state host-vpp1out up
+
+Confirm the interface is up:
+
+.. code-block:: console
+
+  vpp# show int
+                Name               Idx    State  MTU (L3/IP4/IP6/MPLS)     Counter          Count
+  host-vpp1out                      1      up          9000/0/0/0
+  local0                            0     down          0/0/0/0
+
+Assign ip address 10.10.1.2/24
+
+.. code-block:: console
+
+  vpp# set int ip address host-vpp1out 10.10.1.2/24
+
+Confirm the ip address is assigned:
+
+.. code-block:: console
+
+  vpp# show int addr
+  host-vpp1out (up):
+    L3 10.10.1.2/24
+  local0 (dn):

docs/guides/progressivevpp/removedpdkplugin.rst

@@ -0,0 +1,18 @@
+.. _removedpdkplugin:
+
+.. toctree::
+
+Removing the DPDK Plugin
+------------------------
+
+For the purposes of this tutorial, the dpdk plugin will be removed. 
+To do this edit the *startup.conf* file with the following, 
+your *startup.conf* file may already have this line commented, and may just need to 
+uncomment it:
+
+.. code-block:: console
+
+    plugins
+    {
+        plugin dpdk_plugin.so { disable }
+    }

docs/guides/progressivevpp/routing.rst

@@ -0,0 +1,71 @@
+.. _routing:
+
+.. toctree::
+
+Routing
+=======
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+In this exercise you will learn these new skills:
+
+#. Add route to Linux Host routing table
+#. Add route to FD.io VPP routing table
+
+And revisit the old ones:
+
+#. Examine FD.io VPP routing table
+#. Enable trace on vpp1 and vpp2
+#. ping from host to FD.io VPP
+#. Examine and clear trace on vpp1 and vpp2
+#. ping from FD.io VPP to host
+#. Examine and clear trace on vpp1 and vpp2
+
+FD.io VPP command learned in this exercise
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. `ip route
+   add <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_ip.html#clicmd_ip_route>`__
+
+Topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_images/Connecting_two_vpp_instances_with_memif.png
+   :alt: Connect two FD.io VPP topology
+
+   Connect two FD.io VPP topology
+
+Initial State
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The initial state here is presumed to be the final state from the
+exercise `Connecting two FD.io VPP
+instances <VPP/Progressive_VPP_Tutorial#Connecting_two_vpp_instances>`__
+
+Setup host route
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+   $ sudo ip route add 10.10.2.0/24 via 10.10.1.2
+   $ ip route
+   default via 10.0.2.2 dev enp0s3 
+   10.0.2.0/24 dev enp0s3  proto kernel  scope link  src 10.0.2.15 
+   10.10.1.0/24 dev vpp1host  proto kernel  scope link  src 10.10.1.1 
+   10.10.2.0/24 via 10.10.1.2 dev vpp1host 
+
+Setup return route on vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    vpp# ip route add 10.10.1.0/24  via 10.10.2.1
+
+Ping from host through vpp1 to vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Setup a trace on vpp1 and vpp2
+#. Ping 10.10.2.2 from the host
+#. Examine the trace on vpp1 and vpp2
+#. Clear the trace on vpp1 and vpp2

docs/guides/progressivevpp/settingupenvironment.rst

@@ -0,0 +1,21 @@
+.. _settingupenvironment:
+
+.. toctree::
+
+Setting up FD.io VPP environment with Vagrant
+---------------------------------------------
+
+Refer to :ref:`this guide<installingVboxVagrant>` for setting up a Virtual Box with Vagrant
+
+After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
+
+.. code-block:: console
+
+    # vagrant up
+
+.. code-block:: console 
+
+    # vagrant ssh
+
+Afterwards, configure FD.io VPP on the Vagrant system following the steps on the :ref:`configutil` guide.
+

docs/guides/progressivevpp/sourceNAT.rst

@@ -0,0 +1,159 @@
+.. _sourceNAT:
+
+.. toctree::
+
+Source NAT
+==========
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Abusing networks namespaces for fun and profit
+#. Configuring snat address
+#. Configuring snat inside and outside interfaces
+
+FD.io VPP command learned in this exercise
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. `snat add interface
+   address <https://docs.fd.io/vpp/17.04/clicmd_src_plugins_snat.html#clicmd_snat_add_interface_address>`__
+#. `set interface
+   snat <https://docs.fd.io/vpp/17.04/clicmd_src_plugins_snat.html#clicmd_set_interface_snat>`__
+
+Topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_images/SNAT_Topology.jpg
+   :alt: SNAT Topology
+
+   SNAT Topology
+
+Initial state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike previous exercises, for this one you want to start tabula rasa.
+
+Note: You will lose all your existing config in your FD.io VPP  instances!
+
+To clear existing config from previous exercises run:
+
+.. code-block:: console
+
+   ps -ef | grep vpp | awk '{print $2}'| xargs sudo kill
+   $ sudo ip link del dev vpp1host
+   $ sudo ip link del dev vpp1vpp2
+
+Install vpp-plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Snat is supported by a plugin, so vpp-plugins need to be installed
+
+.. code-block:: console
+
+   $ sudo apt-get install vpp-plugins
+
+Create FD.io VPP  instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create one FD.io VPP  instance named vpp1.
+
+Confirm snat plugin is present:
+
+.. code-block:: console
+
+    vpp# show plugins
+    Plugin path is: /usr/lib/vpp_plugins
+    Plugins loaded: 
+     1.ioam_plugin.so
+     2.ila_plugin.so
+     3.acl_plugin.so
+     4.flowperpkt_plugin.so
+     5.snat_plugin.so
+     6.libsixrd_plugin.so
+     7.lb_plugin.so
+
+Create veth interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a veth interface with one end named vpp1outside and the other
+   named vpp1outsidehost
+#. Assign IP address 10.10.1.1/24 to vpp1outsidehost
+#. Create a veth interface with one end named vpp1inside and the other
+   named vpp1insidehost
+#. Assign IP address 10.10.2.1/24 to vpp1outsidehost
+
+Because we'd like to be able to route \*via\* our vpp instance to an
+interface on the same host, we are going to put vpp1insidehost into a
+network namespace
+
+Create a new network namespace 'inside'
+
+.. code-block:: console
+
+    $ sudo ip netns add inside
+
+Move interface vpp1inside into the 'inside' namespace:
+
+.. code-block:: console
+
+    $ sudo ip link set dev vpp1insidehost up netns inside
+
+Assign an ip address to vpp1insidehost
+
+.. code-block:: console
+
+    $ sudo ip netns exec inside ip addr add 10.10.2.1/24 dev vpp1insidehost
+
+Create a route inside the netns:
+
+.. code-block:: console
+
+    $ sudo ip netns exec inside ip route add 10.10.1.0/24 via 10.10.2.2
+
+Configure vpp outside interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a vpp host interface connected to vpp1outside
+#. Assign ip address 10.10.1.2/24
+#. Create a vpp host interface connected to vpp1inside
+#. Assign ip address 10.10.2.2/24
+
+Configure snat
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configure snat to use the address of host-vpp1outside
+
+.. code-block:: console
+
+   vpp# snat add interface address host-vpp1outside
+
+Configure snat inside and outside interfaces
+
+.. code-block:: console
+
+   vpp# set interface snat in host-vpp1inside out host-vpp1outside
+
+Prepare to Observe Snat
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Observing snat in this configuration is interesting. To do so, vagrant
+ssh a second time into your VM and run:
+
+.. code-block:: console
+
+   $ sudo tcpdump -s 0 -i vpp1outsidehost
+
+Also enable tracing on vpp1
+
+Ping via snat
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+   $ sudo ip netns exec inside ping -c 1 10.10.1.1
+
+Confirm snat
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Examine the tcpdump output and vpp1 trace to confirm snat occurred.
+

docs/guides/progressivevpp/switching.rst

@@ -0,0 +1,188 @@
+.. _switching:
+
+.. toctree::
+
+Switching
+=========
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Associate an interface with a bridge domain
+#. Create a loopback interaface
+#. Create a BVI (Bridge Virtual Interface) for a bridge domain
+#. Examine a bridge domain
+
+FD.io VPP command learned in this exercise
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. `show
+   bridge <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_l2.html#clicmd_show_bridge-domain>`__
+#. `show bridge
+   detail <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_l2.html#clicmd_show_bridge-domain>`__
+#. `set int l2
+   bridge <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_l2.html#clicmd_set_interface_l2_bridge>`__
+#. `show l2fib
+   verbose <https://docs.fd.io/vpp/17.04/clicmd_src_vnet_l2.html#clicmd_show_l2fib>`__
+
+Topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_images/Switching_Topology.jpg
+   :alt: Switching Topology
+
+   Switching Topology
+
+Initial state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike previous exercises, for this one you want to start tabula rasa.
+
+Note: You will lose all your existing config in your FD.io VPP instances!
+
+To clear existing config from previous exercises run:
+
+.. code-block:: console
+
+   $ ps -ef | grep vpp | awk '{print $2}'| xargs sudo kill
+   $ sudo ip link del dev vpp1host
+   $ sudo ip link del dev vpp1vpp2
+
+Run FD.io VPP instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Run a vpp instance named **vpp1**
+#. Run a vpp instance named **vpp2**
+
+Connect vpp1 to host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a veth with one end named vpp1host and the other named
+   vpp1out.
+#. Connect vpp1out to vpp1
+#. Add ip address 10.10.1.1/24 on vpp1host
+
+Connect vpp1 to vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a veth with one end named vpp1vpp2 and the other named
+   vpp2vpp1.
+#. Connect vpp1vpp2 to vpp1.
+#. Connect vpp2vpp1 to vpp2.
+
+Configure Bridge Domain on vpp1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Check to see what bridge domains already exist, and select the first
+bridge domain number not in use:
+
+.. code-block:: console
+
+   vpp# show bridge-domain
+    ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf   
+    0      0        off        off        off        off        off        local0    
+
+In the example above, there is bridge domain ID '0' already. Even though
+sometimes we might get feedback as below:
+
+.. code-block:: console
+
+   no bridge-domains in use
+
+the bridge domain ID '0' still exists, where no operations are
+supported. For instance, if we try to add host-vpp1out and host-vpp1vpp2
+to bridge domain ID 0, we will get nothing setup.
+
+.. code-block:: console
+
+   vpp# set int l2 bridge host-vpp1out 0
+   vpp# set int l2 bridge host-vpp1vpp2 0
+   vpp# show bridge-domain 0 detail
+   show bridge-domain: No operations on the default bridge domain are supported
+
+So we will create bridge domain 1 instead of playing with the default
+bridge domain ID 0.
+
+Add host-vpp1out to bridge domain ID 1
+
+.. code-block:: console
+
+   vpp# set int l2 bridge host-vpp1out 1
+
+Add host-vpp1vpp2 to bridge domain ID1
+
+.. code-block:: console
+
+   vpp# set int l2 bridge host-vpp1vpp2  1
+
+Examine bridge domain 1:
+
+.. code-block:: console
+
+    vpp# show bridge-domain 1 detail
+    BD-ID   Index   BSN  Age(min)  Learning  U-Forwrd  UU-Flood  Flooding  ARP-Term  BVI-Intf
+    1       1      0     off        on        on        on        on       off       N/A
+
+            Interface           If-idx ISN  SHG  BVI  TxFlood        VLAN-Tag-Rewrite
+        host-vpp1out            1     1    0    -      *                 none
+        host-vpp1vpp2           2     1    0    -      *                 none
+
+Configure loopback interface on vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    vpp# create loopback interface
+    loop0
+
+Add the ip address 10.10.1.2/24 to vpp2 interface loop0. Set the state
+of interface loop0 on vpp2 to 'up'
+
+Configure bridge domain on vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Check to see the first available bridge domain ID (it will be 1 in this
+case)
+
+Add interface loop0 as a bridge virtual interface (bvi) to bridge domain
+1
+
+.. code-block:: console
+
+   vpp# set int l2 bridge loop0 1 bvi
+
+Add interface vpp2vpp1 to bridge domain 1
+
+.. code-block:: console
+
+   vpp# set int l2 bridge host-vpp2vpp1  1
+
+Examine the bridge domain and interfaces.
+
+Ping from host to vpp and vpp to host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Add trace on vpp1 and vpp2
+#. ping from host to 10.10.1.2
+#. Examine and clear trace on vpp1 and vpp2
+#. ping from vpp2 to 10.10.1.1
+#. Examine and clear trace on vpp1 and vpp2
+
+Examine l2 fib
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    vpp# show l2fib verbose
+    Mac Address     BD Idx           Interface           Index  static  filter  bvi   Mac Age (min) 
+    de:ad:00:00:00:00    1            host-vpp1vpp2           2       0       0     0      disabled    
+    c2:f6:88:31:7b:8e    1            host-vpp1out            1       0       0     0      disabled    
+    2 l2fib entries
+
+.. code-block:: console
+
+    vpp# show l2fib verbose
+    Mac Address     BD Idx           Interface           Index  static  filter  bvi   Mac Age (min) 
+    de:ad:00:00:00:00    1                loop0               2       1       0     1      disabled    
+    c2:f6:88:31:7b:8e    1            host-vpp2vpp1           1       0       0     0      disabled    
+    2 l2fib entries

docs/guides/progressivevpp/twovppinstances.rst

@@ -0,0 +1,114 @@
+.. _twovppinstances:
+
+.. toctree::
+
+Connecting two FD.io VPP Instances
+----------------------------------
+
+.. _background-1:
+
+memif is a very high performance, direct memory interface type which can
+be used between FD.io VPP instances to form a topology. It uses a file socket
+for a control channel to set up that shared memory.
+
+.. _skills-to-be-learned-1:
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^
+
+You will learn the following new skill in this exercise:
+
+#. Create a memif interface between two FD.io VPP instances
+
+You should be able to perform this exercise with the following skills
+learned in previous exercises:
+
+#. Run a second FD.io VPP instance
+#. Add an ip address to a FD.io VPP interface
+#. Ping from FD.io VPP
+
+.. _topology-1:
+
+Topology
+^^^^^^^^
+
+.. figure:: /_images/Connecting_two_vpp_instances_with_memif.png
+   :alt: Connect two FD.io VPP topology
+
+   Connect two FD.io VPP topology
+
+.. _initial-state-1:
+
+Initial state
+^^^^^^^^^^^^^
+
+The initial state here is presumed to be the final state from the
+exercise `Create an
+Interface <VPP/Progressive_VPP_Tutorial#Exercise:_Create_an_Interface>`__
+
+.. _action-running-a-second-vpp-instances-1:
+
+Running a second FD.io VPP instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You should already have a FD.io VPP instance running named: vpp1.
+
+Run a second FD.io VPP instance named: vpp2.
+
+.. _action-create-memif-interface-on-vpp1-1:
+
+Create memif interface on vpp1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create a memif interface on vpp1:
+
+.. code-block:: console
+
+   vpp# create interface memif id 0 master
+
+This will create an interface on vpp1 memif0/0 using /run/vpp/memif as
+its socket file. The role of vpp1 for this memif inteface is 'master'.
+
+Use your previously used skills to:
+
+#. Set the memif0/0 state to up.
+#. Assign IP address 10.10.2.1/24 to memif0/0
+#. Examine memif0/0 via show commands
+
+.. _action-create-memif-interface-on-vpp2-1:
+
+Create memif interface on vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We want vpp2 to pick up the 'slave' role using the same
+run/vpp/memif-vpp1vpp2 socket file
+
+.. code-block:: console
+
+   vpp# create interface memif id 0 slave
+
+This will create an interface on vpp2 memif0/0 using /run/vpp/memif as
+its socket file. The role of vpp1 for this memif inteface is 'slave'.
+
+Use your previously used skills to:
+
+#. Set the memif0/0 state to up.
+#. Assign IP address 10.10.2.2/24 to memif0/0
+#. Examine memif0/0 via show commands
+
+.. _action-ping-from-vpp1-to-vpp2-1:
+
+Ping from vpp1 to vpp2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ping 10.10.2.2 from vpp1
+
+.. code-block:: console
+
+    $ ping 10.10.2.2 
+
+Ping 10.10.2.1 from vpp2
+
+.. code-block:: console
+
+    $ ping 10.10.2.1