diff options
21 files changed, 394 insertions, 471 deletions
diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst index 8c39069032b..b56fec8635c 100644 --- a/docs/gettingstarted/developers/index.rst +++ b/docs/gettingstarted/developers/index.rst @@ -1,8 +1,8 @@ .. _gstarteddevel: -########## -Developers -########## +############### +For Developers +############### The Developers section covers the following areas: diff --git a/docs/gettingstarted/developers/vnet.md b/docs/gettingstarted/developers/vnet.md index 191a2a16969..602ffb7e782 100644 --- a/docs/gettingstarted/developers/vnet.md +++ b/docs/gettingstarted/developers/vnet.md @@ -17,10 +17,6 @@ classification, feeds ipv4-input, ipv6-input, arp-input etc.\] and "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 ---------------------------------------- diff --git a/docs/gettingstarted/index.rst b/docs/gettingstarted/index.rst index 4fcc51348fc..f29d17942e5 100644 --- a/docs/gettingstarted/index.rst +++ b/docs/gettingstarted/index.rst @@ -33,6 +33,7 @@ The Writing VPP Documentation section covers the following topics: .. toctree:: :maxdepth: 2 + progressivevpp/index.rst users/index.rst developers/index.rst writingdocs/index.rst diff --git a/docs/gettingstarted/progressivevpp/index.rst b/docs/gettingstarted/progressivevpp/index.rst new file mode 100644 index 00000000000..458beda57bc --- /dev/null +++ b/docs/gettingstarted/progressivevpp/index.rst @@ -0,0 +1,27 @@ +.. _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 diff --git a/docs/guides/progressivevpp/interface.rst b/docs/gettingstarted/progressivevpp/interface.rst index 619216d5f42..476fc5dda37 100644 --- a/docs/guides/progressivevpp/interface.rst +++ b/docs/gettingstarted/progressivevpp/interface.rst @@ -2,11 +2,20 @@ .. 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>`_ @@ -20,7 +29,7 @@ VPP command learned in this exercise #. `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 @@ -28,13 +37,13 @@ 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 @@ -55,7 +64,7 @@ Turn up both ends: $ sudo ip link set dev vpp1host up Assign an IP address -~~~~~~~~~~~~~~~~~~~~ +--------------------- .. code-block:: console @@ -65,7 +74,7 @@ Display the result: .. 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 @@ -74,7 +83,29 @@ Display the result: 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**. diff --git a/docs/guides/progressivevpp/routing.rst b/docs/gettingstarted/progressivevpp/routing.rst index b5766c03865..c9586c1c85d 100644 --- a/docs/guides/progressivevpp/routing.rst +++ b/docs/gettingstarted/progressivevpp/routing.rst @@ -6,7 +6,7 @@ Routing ======= Skills to be Learned -^^^^^^^^^^^^^^^^^^^^ +--------------------- In this exercise you will learn these new skills: @@ -22,14 +22,14 @@ And revisit the old ones: #. 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 @@ -37,14 +37,14 @@ 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 @@ -56,14 +56,19 @@ Setup host route 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 diff --git a/docs/gettingstarted/progressivevpp/runningvpp.rst b/docs/gettingstarted/progressivevpp/runningvpp.rst new file mode 100644 index 00000000000..ff20064b5eb --- /dev/null +++ b/docs/gettingstarted/progressivevpp/runningvpp.rst @@ -0,0 +1,74 @@ +.. _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 diff --git a/docs/gettingstarted/progressivevpp/settingupenvironment.rst b/docs/gettingstarted/progressivevpp/settingupenvironment.rst new file mode 100644 index 00000000000..b22f79b3085 --- /dev/null +++ b/docs/gettingstarted/progressivevpp/settingupenvironment.rst @@ -0,0 +1,154 @@ +.. _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 } } diff --git a/docs/guides/progressivevpp/switching.rst b/docs/gettingstarted/progressivevpp/switching.rst index aede969f42f..72005080b08 100644 --- a/docs/guides/progressivevpp/switching.rst +++ b/docs/gettingstarted/progressivevpp/switching.rst @@ -6,7 +6,7 @@ Switching ========= Skills to be Learned -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------- #. Associate an interface with a bridge domain #. Create a loopback interaface @@ -14,7 +14,7 @@ Skills to be Learned #. 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>`__ @@ -26,7 +26,7 @@ FD.io VPP command learned in this exercise 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 @@ -34,7 +34,7 @@ Topology Switching Topology Initial state -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------- Unlike previous exercises, for this one you want to start tabula rasa. @@ -46,16 +46,17 @@ To clear existing config from previous exercises run: $ 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. @@ -63,7 +64,7 @@ Connect vpp1 to host #. 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. @@ -71,7 +72,7 @@ Connect vpp1 to vpp2 #. 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: @@ -128,7 +129,7 @@ Examine bridge domain 1: host-vpp1vpp2 2 1 0 - * none Configure loopback interface on vpp2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------- .. code-block:: console @@ -139,7 +140,7 @@ 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) @@ -160,7 +161,7 @@ Add interface vpp2vpp1 to bridge domain 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 @@ -169,7 +170,7 @@ Ping from host to vpp and vpp to host #. Examine and clear trace on vpp1 and vpp2 Examine l2 fib -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------- .. code-block:: console diff --git a/docs/guides/progressivevpp/traces.rst b/docs/gettingstarted/progressivevpp/traces.rst index 076e2fa57b8..b8238db2cd8 100644 --- a/docs/guides/progressivevpp/traces.rst +++ b/docs/gettingstarted/progressivevpp/traces.rst @@ -2,11 +2,22 @@ .. 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]. @@ -14,7 +25,6 @@ Show trace buffer [max COUNT]. vpp# show trace - Clear trace buffer and free memory. .. code-block:: console @@ -27,26 +37,15 @@ filter trace output - include NODE COUNT | exclude NODE COUNT | none. 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 @@ -59,12 +58,12 @@ Ping from Host to FD.io VPP 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 @@ -121,14 +120,14 @@ Examine Trace of ping from host to FD.io VPP 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 @@ -141,8 +140,8 @@ Ping from FD.io VPP to Host 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. @@ -442,7 +441,7 @@ 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 @@ -451,7 +450,7 @@ Examine arp tables 1101.5636 10.10.1.1 D e2:0f:1e:59:ec:f7 host-vpp1out Examine routing tables -~~~~~~~~~~~~~~~~~~~~~~ +----------------------- .. code-block:: console diff --git a/docs/guides/progressivevpp/twovppinstances.rst b/docs/gettingstarted/progressivevpp/twovppinstances.rst index 13447b5ea8b..7a8bbe0fd1c 100644 --- a/docs/guides/progressivevpp/twovppinstances.rst +++ b/docs/gettingstarted/progressivevpp/twovppinstances.rst @@ -2,19 +2,19 @@ .. 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: @@ -30,7 +30,7 @@ learned in previous exercises: .. _topology-1: Topology -^^^^^^^^ +--------- .. figure:: /_images/Connecting_two_vpp_instances_with_memif.png :alt: Connect two FD.io VPP topology @@ -40,7 +40,7 @@ Topology .. _initial-state-1: Initial state -^^^^^^^^^^^^^ +-------------- The initial state here is presumed to be the final state from the exercise `Create an @@ -49,27 +49,43 @@ 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. +.. 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 @@ -78,7 +94,7 @@ Use your previously used skills to: .. _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 @@ -99,7 +115,7 @@ Use your previously used skills to: .. _action-ping-from-vpp1-to-vpp2-1: Ping from vpp1 to vpp2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ Ping 10.10.2.2 from vpp1 @@ -111,4 +127,4 @@ Ping 10.10.2.1 from vpp2 .. code-block:: console - $ ping 10.10.2.1
\ No newline at end of file + $ ping 10.10.2.1 diff --git a/docs/gettingstarted/users/configuring/startup.rst b/docs/gettingstarted/users/configuring/startup.rst index b756dd4f3cd..0bc6ca4ae8a 100644 --- a/docs/gettingstarted/users/configuring/startup.rst +++ b/docs/gettingstarted/users/configuring/startup.rst @@ -1,9 +1,5 @@ .. _startup: - -.. toctree:: - - ======================================= VPP Configuration File - 'startup.conf' ======================================= diff --git a/docs/gettingstarted/users/index.rst b/docs/gettingstarted/users/index.rst index 7bac586d65a..4ec261a9937 100644 --- a/docs/gettingstarted/users/index.rst +++ b/docs/gettingstarted/users/index.rst @@ -1,8 +1,8 @@ .. _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 @@ -21,7 +21,7 @@ section covers the following areas: .. toctree:: :maxdepth: 2 + configutil/index.rst installing/index.rst configuring/index.rst running/index.rst - configutil/index.rst diff --git a/docs/gettingstarted/users/installing/ubuntu.rst b/docs/gettingstarted/users/installing/ubuntu.rst index cb7a1c6097d..d1daed14ddb 100644 --- a/docs/gettingstarted/users/installing/ubuntu.rst +++ b/docs/gettingstarted/users/installing/ubuntu.rst @@ -64,7 +64,7 @@ Install the mandatory packages by running the following commands: .. 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 diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 59a1b38205a..ab73368e887 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -7,5 +7,4 @@ User Guides .. toctree:: :maxdepth: 2 - progressivevpp/index.rst api/index.rst diff --git a/docs/guides/progressivevpp/index.rst b/docs/guides/progressivevpp/index.rst deleted file mode 100644 index 8be904dc911..00000000000 --- a/docs/guides/progressivevpp/index.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _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 diff --git a/docs/guides/progressivevpp/removedpdkplugin.rst b/docs/guides/progressivevpp/removedpdkplugin.rst deleted file mode 100644 index b64e1f0d197..00000000000 --- a/docs/guides/progressivevpp/removedpdkplugin.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _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 diff --git a/docs/guides/progressivevpp/settingupenvironment.rst b/docs/guides/progressivevpp/settingupenvironment.rst deleted file mode 100644 index a1ffc997b02..00000000000 --- a/docs/guides/progressivevpp/settingupenvironment.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _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. - diff --git a/docs/guides/progressivevpp/sourceNAT.rst b/docs/guides/progressivevpp/sourceNAT.rst deleted file mode 100644 index f51a4ad9039..00000000000 --- a/docs/guides/progressivevpp/sourceNAT.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. _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. - diff --git a/docs/reference/vppvagrant/index.rst b/docs/reference/vppvagrant/index.rst index 7852cb88514..04da9e3f022 100644 --- a/docs/reference/vppvagrant/index.rst +++ b/docs/reference/vppvagrant/index.rst @@ -1,4 +1,4 @@ -.. _vppcontainers: +.. _vppvagrant: VM's with Vagrant ================= @@ -13,5 +13,3 @@ This reference guide will cover using Vagrant to boot a VM (virtual machine). boxSetup VagrantVMSetup vppVagrantfile - - diff --git a/docs/reference/vppvagrant/installingVboxVagrant.rst b/docs/reference/vppvagrant/installingVboxVagrant.rst index 018ce6cfb53..326312899b4 100644 --- a/docs/reference/vppvagrant/installingVboxVagrant.rst +++ b/docs/reference/vppvagrant/installingVboxVagrant.rst @@ -1,7 +1,5 @@ .. _installingVboxVagrant: -.. toctree:: - Installing Vbox and Vagrant =========================== @@ -19,6 +17,8 @@ If you're on Ubuntu, perform: $ 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 __________________ @@ -35,4 +35,4 @@ This is a similar command, but on a 64-bit version of Debian: $ 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>`_. |