.. _gstarteddevel:
-##########
-Developers
-##########
+###############
+For Developers
+###############
The Developers section covers the following areas:
"ipv4-input-no-checksum" \[if hardware can classify, perform ipv4 header
checksum\].
-
-
-List of features and layer areas that VNET works with:
-
Effective graph dispatch function coding
----------------------------------------
.. toctree::
:maxdepth: 2
+ progressivevpp/index.rst
users/index.rst
developers/index.rst
writingdocs/index.rst
--- /dev/null
+.. _progressivevpp:
+
+.. toctree::
+
+########################
+Progressive VPP Tutorial
+########################
+
+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.
+
+For more information on using VPP with Virtual Box/Vagrant, please refer to :ref:`vppvagrant`
+
+.. toctree::
+
+ settingupenvironment.rst
+ runningvpp.rst
+ interface.rst
+ traces.rst
+ twovppinstances.rst
+ routing.rst
+ switching.rst
.. toctree::
-Interface
-=========
+Creating 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
+
+VPP commands learned in this exercise
+--------------------------------------
-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 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>`__
+The initial state here is presumed to be the final state from the previous sections
+of the tutorial.
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
$ sudo ip link set dev vpp1host up
Assign an IP address
-~~~~~~~~~~~~~~~~~~~~
+---------------------
.. code-block:: console
.. code-block:: console
- $ sudo ip addr show vpp1host
+ $ 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
Create vpp host-interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
+
+Make sure VPP is running, if not start it.
+
+.. code-block:: console
+
+ $ ps -eaf | grep vpp
+ vagrant 2141 903 0 05:28 pts/0 00:00:00 grep --color=auto vpp
+ # vpp is not running, so start it
+ $ sudo /usr/bin/vpp -c startup1.conf
+
+These commands are run from the vpp shell. Enter the VPP shell with the following
+command:
+
+.. code-block:: console
+
+ $ sudo vppctl -s /run/vpp/cli-vpp1.sock
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ vpp#
Create a host interface attached to **vpp1out**.
=======
Skills to be Learned
-^^^^^^^^^^^^^^^^^^^^
+---------------------
In this exercise you will learn these new skills:
#. ping from FD.io VPP to host
#. Examine and clear trace on vpp1 and vpp2
-FD.io VPP command learned in this exercise
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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
10.10.2.0/24 via 10.10.1.2 dev vpp1host
Setup return route on vpp2
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
.. code-block:: console
+ $ sudo vppctl -s /run/vpp/cli-vpp2.sock
vpp# ip route add 10.10.1.0/24 via 10.10.2.1
Ping from host through vpp1 to vpp2
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------------
+
+The connection from vpp1 to vpp2 uses the **memif** driver, the connection to the host
+uses the **af-packet** driver. To trace packets from the host we use **af-packet-input** from
+vpp1 to vpp2 we use **memif-input**.
#. Setup a trace on vpp1 and vpp2
#. Ping 10.10.2.2 from the host
--- /dev/null
+.. _runningvpp:
+
+Running VPP
+===========
+
+Using the files we create in :ref`settingupenvironment` we will now start and
+run VPP.
+
+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 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, VPP supports this.
+
+
+Using the files we created in setup we will start VPP.
+
+.. code-block:: console
+
+ $ sudo /usr/bin/vpp -c startup1.conf
+ vlib_plugin_early_init:361: plugin path /usr/lib/vpp_plugins:/usr/lib64/vpp_plugins
+ load_one_plugin:189: Loaded plugin: abf_plugin.so (ACL based Forwarding)
+ load_one_plugin:189: Loaded plugin: acl_plugin.so (Access Control Lists)
+ load_one_plugin:189: Loaded plugin: avf_plugin.so (Intel Adaptive Virtual Function (AVF) Device Plugin)
+ .........
+ $
+
+If VPP does not start you can try adding **nodaemon** to the startup.conf file in the
+**unix** section. This should provide more information in the output.
+
+startup.conf example with nodaemon:
+
+.. code-block:: console
+
+ unix {nodaemon cli-listen /run/vpp/cli-vpp1.sock}
+ api-segment { prefix vpp1 }
+ plugins { plugin dpdk_plugin.so { disable } }
+
+The command **vppctl** will launch a VPP shell with which you can run
+VPP commands interactively.
+
+We should now be able to execute the VPP shell and show the version.
+
+.. code-block:: console
+
+ $ sudo vppctl -s /run/vpp/cli-vpp1.sock
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ vpp# show version
+ vpp v18.07-release built by root on c469eba2a593 at Mon Jul 30 23:27:03 UTC 2018
+ vpp#
+
+.. note::
+
+ Use ctrl-d or q to exit from the VPP shell.
+
+If you are going to run several instances of VPP this way be sure to kill them
+when you are finished.
+
+You can use something like the following:
+
+.. code-block:: console
+
+ $ ps -eaf | grep vpp
+ root 2067 1 2 05:12 ? 00:00:00 /usr/bin/vpp -c startup1.conf
+ vagrant 2070 903 0 05:12 pts/0 00:00:00 grep --color=auto vpp
+ $ kill -9 2067
+ $ ps -eaf | grep vpp
+ vagrant 2074 903 0 05:13 pts/0 00:00:00 grep --color=auto vpp
--- /dev/null
+.. _settingupenvironment:
+
+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.
+
+Install Virtual Box and Vagrant
+-------------------------------
+
+You will need to install Virtual Box and Vagrant. If you have not installed Virtual Box or Vagrant please
+refer to :ref:`installingVboxVagrant` to install Virtual Box and Vagrant.
+
+Create a Vagrant Directory
+---------------------------
+
+To get started create a directory for vagrant
+
+.. code-block:: console
+
+ $ mkdir vpp-tutorial
+ $ cd vpp-tutorial
+
+Create a file called **Vagrantfile** with the following contents:
+
+.. code-block:: ruby
+
+ # -*- mode: ruby -*-
+ # vi: set ft=ruby :
+
+ Vagrant.configure(2) do |config|
+
+ config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
+ config.vm.box_check_update = false
+
+ vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
+ vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
+
+ config.ssh.forward_agent = true
+
+ config.vm.provider "virtualbox" do |vb|
+ vb.customize ["modifyvm", :id, "--ioapic", "on"]
+ vb.memory = "#{vmram}"
+ vb.cpus = "#{vmcpu}"
+ #support for the SSE4.x instruction is required in some versions of VB.
+ vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
+ vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
+ end
+ end
+
+
+Running Vagrant
+---------------
+
+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.mIn those circumstances
+you usually run a single instance of 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,
+VPP supports this.
+
+When running multiple 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.
+
+Setting up VPP environment with Vagrant
+---------------------------------------------
+
+After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
+
+.. code-block:: console
+
+ $ vagrant up
+ $ vagrant ssh
+ $ sudo apt-get update
+ $ sudo reboot -n
+ $ # Wait for the VM to reboot
+ $ vagrant ssh
+
+Install VPP
+------------
+
+Now that the VM is updated, we will install the VPP packages.
+
+For more on installing VPP please refer to :ref:`installingVPP`.
+
+For this tutorial we need to install VPP by modifying the file
+**/etc/apt/sources.list.d/99fd.io.list**.
+
+Write this file with the following contents:
+
+.. code-block:: console
+
+ deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.ubuntu.xenial.main/ ./
+
+Then execute the following commands.
+
+.. code-block:: console
+
+ $ sudo bash
+ # apt-get update
+ # apt-get install vpp-lib vpp vpp-plugins
+ #
+
+Stop VPP for this tutorial. We will be creating our own instances of VPP.
+
+.. code-block:: console
+
+ # service vpp stop
+ #
+
+
+Create some startup files
+--------------------------
+
+We will create some startup files for the use of this tutorial. Typically you will
+modify the startup.conf file found in /etc/vpp/startup.conf. For more information
+on this file refer to :ref:`startup`.
+
+When running multiple 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. These startup files we create will
+disable the dpdk plugin.
+
+Also in our startup files notice **api-segment**. **api-segment {prefix vpp1}**
+tells FD.io VPP how to name the files in /dev/shm/ for your VPP instance
+differently from the default. **unix {cli-listen /run/vpp/cli-vpp1.sock}**
+tells vpp to use a non-default socket file when being addressed by vppctl.
+
+Now create 2 files named startup1.conf and startup2.conf with the following
+content. These files can be located anywhere. We specify the location when we
+start VPP.
+
+startup1.conf:
+
+.. code-block:: console
+
+ unix {cli-listen /run/vpp/cli-vpp1.sock}
+ api-segment { prefix vpp1 }
+ plugins { plugin dpdk_plugin.so { disable } }
+
+startup2.conf:
+
+.. code-block:: console
+
+ unix {cli-listen /run/vpp/cli-vpp2.sock}
+ api-segment { prefix vpp2 }
+ plugins { plugin dpdk_plugin.so { disable } }
=========
Skills to be Learned
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------
#. Associate an interface with a bridge domain
#. Create a loopback interaface
#. 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>`__
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.
$ ps -ef | grep vpp | awk '{print $2}'| xargs sudo kill
$ sudo ip link del dev vpp1host
+ $ # do the next command if you are cleaing up from this example
$ 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.
#. 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 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:
host-vpp1vpp2 2 1 0 - * none
Configure loopback interface on vpp2
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------
.. code-block:: console
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)
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
Examine l2 fib
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------
.. code-block:: console
.. toctree::
-Traces
-======
+Using the trace command
+========================
+
+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
Basic Trace Commands
-~~~~~~~~~~~~~~~~~~~~
+---------------------
Show trace buffer [max COUNT].
vpp# show trace
-
Clear trace buffer and free memory.
.. code-block:: console
vpp# trace filter <include NODE COUNT | exclude NODE COUNT | none>
-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
-
Add Trace
-~~~~~~~~~
+----------
.. code-block:: console
vpp# trace add af-packet-input 10
-Ping from Host to FD.io VPP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ping from Host to VPP
+----------------------
.. code-block:: console
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.283/0.283/0.283/0.000 ms
-Examine Trace of ping from host to FD.io VPP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Examine Trace of ping from host to VPP
+----------------------------------------
.. code-block:: console
- # vppctl
+ $ sudo vppctl -s /run/vpp/cli-vpp1.sock
vpp# show trace
------------------- Start of thread 0 vpp_main -------------------
Packet 1
ICMP echo_reply checksum 0xc843
Clear trace buffer
-~~~~~~~~~~~~~~~~~~
+-------------------
.. code-block:: console
vpp# clear trace
-Ping from FD.io VPP to Host
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ping from VPP to Host
+-----------------------
.. code-block:: console
Statistics: 5 sent, 5 received, 0% packet loss
-Examine Trace of ping from FD.io VPP to host
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Examine Trace of ping from VPP to host
+---------------------------------------
The output will demonstrate FD.io VPP's trace of ping for all packets.
After examining the trace, clear it again using vpp# clear trace.
Examine arp tables
-~~~~~~~~~~~~~~~~~~
+-------------------
.. code-block:: console
1101.5636 10.10.1.1 D e2:0f:1e:59:ec:f7 host-vpp1out
Examine routing tables
-~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
.. code-block:: console
.. toctree::
-Connecting two FD.io VPP Instances
-----------------------------------
+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.
+be used between FD.io VPP instances. It uses a file socket for a control channel
+to set up shared memory.
.. _skills-to-be-learned-1:
Skills to be Learned
-^^^^^^^^^^^^^^^^^^^^
+---------------------
You will learn the following new skill in this exercise:
.. _topology-1:
Topology
-^^^^^^^^
+---------
.. figure:: /_images/Connecting_two_vpp_instances_with_memif.png
:alt: 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
.. _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.
+.. code-block:: console
+
+ $ sudo /usr/bin/vpp -c startup2.conf
+ ....
+ $ sudo vppctl -s /run/vpp/cli-vpp2.sock
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ vpp# show version
+ vpp v18.07-release built by root on c469eba2a593 at Mon Jul 30 23:27:03 UTC 2018
+ vpp# quit
+
.. _action-create-memif-interface-on-vpp1-1:
Create memif interface on vpp1
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------
-Create a memif interface on vpp1:
+Create a memif interface on vpp1. To connect to the instance vpp1 use the
+socket **/run/vpp/cli-vpp1.sock**
.. code-block:: console
+ $ sudo vppctl -s /run/vpp/cli-vpp1.sock
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:
+With what you have learned:
#. Set the memif0/0 state to up.
#. Assign IP address 10.10.2.1/24 to memif0/0
.. _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
.. _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.1
\ No newline at end of file
+ $ ping 10.10.2.1
.. _startup:
-
-.. toctree::
-
-
=======================================
VPP Configuration File - 'startup.conf'
=======================================
.. _users:
-########
-Users
-########
+###########
+For Users
+###########
The Users section describe a basic VPP installation and configuration operation.
The installation and configuration of VPP can be done either manually, or by
.. toctree::
:maxdepth: 2
+ configutil/index.rst
installing/index.rst
configuring/index.rst
running/index.rst
- configutil/index.rst
.. code-block:: console
sudo apt-get update
- sudo apt-get install vpp vpp-lib vpp-plugin
+ sudo apt-get install vpp-lib vpp vpp-plugins
Install the Optional Packages
.. toctree::
:maxdepth: 2
- progressivevpp/index.rst
api/index.rst
+++ /dev/null
-.. _progressivevpp:
-
-.. toctree::
-
-########################
-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
+++ /dev/null
-.. _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 }
- }
\ No newline at end of file
+++ /dev/null
-.. _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.
-
+++ /dev/null
-.. _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.
-
-.. _vppcontainers:
+.. _vppvagrant:
VM's with Vagrant
=================
boxSetup
VagrantVMSetup
vppVagrantfile
-
-
.. _installingVboxVagrant:
-.. toctree::
-
Installing Vbox and Vagrant
===========================
$ sudo apt-get install virtualbox
+If you want to download a newer version of Virtual Box or one specific to your OS and architecture, go to the `Virtual Box download page <https://www.virtualbox.org/wiki/Downloads>`_.
+
Installing Vagrant
__________________
$ sudo apt-get install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.deb
-If you want to download a newer version of Vagrant or one specific to your OS and architecture, go to the Vagrant `download page <https://www.vagrantup.com/downloads.html>`_, right-click and copy the link address for your specified version, and replace the above install command for your respective OS and architechure.
\ No newline at end of file
+If you want to download a newer version of Vagrant or one specific to your OS and architecture, go to the `Vagrant download page <https://www.vagrantup.com/downloads.html>`_.
Code Review / vpp.git / commitdiff