1 .. _settingupenvironment:
3 Setting up your environment
4 ===========================
6 All of these exercises are designed to be performed on an Ubuntu 22.04 (Jammy) box.
8 * If you have an Ubuntu 22.04 box on which you have sudo or root access, you can feel free to use that.
9 * If you do not, a Vagrantfile is provided to setup a basic Ubuntu 22.04 box for you in the the steps below.
11 Install Libvirt and Vagrant
12 -------------------------------
14 You will need to install Libvirt and Vagrant.
16 Create a Vagrant Directory
17 ---------------------------
19 To get started create a directory for vagrant
21 .. code-block:: console
26 Create a file called **Vagrantfile** with the following contents:
33 Vagrant.configure(2) do |config|
35 config.vm.box = "generic/ubuntu2204"
37 vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
38 vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
40 config.ssh.forward_agent = true
42 config.vm.provider "libvirt" do |vb|
43 vb.memory = "#{vmram}"
52 VPP runs in userspace. In a production environment you will often run it with
53 DPDK to connect to real NICs or vhost to connect to VMs.mIn those circumstances
54 you usually run a single instance of VPP.
56 For purposes of this tutorial, it is going to be extremely useful to run multiple
57 instances of vpp, and connect them to each other to form a topology. Fortunately,
60 When running multiple VPP instances, each instance needs to have specified a 'name'
61 or 'prefix'. In the example below, the 'name' or 'prefix' is "vpp1". Note that only
62 one instance can use the dpdk plugin, since this plugin is trying to acquire a lock
65 Setting up VPP environment with Vagrant
66 ---------------------------------------------
68 After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
70 .. code-block:: console
77 $ # Wait for the VM to reboot
83 Now that the VM is updated, we will install the VPP packages.
85 For more on installing VPP please refer to :ref:`installingVPP`.
87 For this tutorial we will install VPP by modifying the file
88 **/etc/apt/sources.list.d/99fd.io.list**.
90 We write this file with the following contents:
92 .. code-block:: console
95 # echo "deb https://packagecloud.io/fdio/release/ubuntu jammy main" > /etc/apt/sources.list.d/99fd.io.list
100 .. code-block:: console
102 # curl -L https://packagecloud.io/fdio/release/gpgkey | sudo apt-key add -
105 Then execute the following commands.
107 .. code-block:: console
110 # apt-get install vpp vpp-plugin-core vpp-plugin-dpdk
113 Stop VPP for this tutorial. We will be creating our own instances of VPP.
115 .. code-block:: console
121 Create some startup files
122 --------------------------
124 We will create some startup files for the use of this tutorial. Typically you will
125 modify the startup.conf file found in /etc/vpp/startup.conf. For more information
126 on this file refer to :ref:`configuration_reference`.
128 When running multiple VPP instances, each instance needs to have
129 specified a 'name' or 'prefix'. In the example below, the 'name' or 'prefix'
130 is "vpp1". Note that only one instance can use the dpdk plugin, since this
131 plugin is trying to acquire a lock on a file. These startup files we create will
132 disable the dpdk plugin.
134 Also in our startup files notice **api-segment**. **api-segment {prefix vpp1}**
135 tells FD.io VPP how to name the files in /dev/shm/ for your VPP instance
136 differently from the default. **unix {cli-listen /run/vpp/cli-vpp1.sock}**
137 tells vpp to use a non-default socket file when being addressed by vppctl.
139 Now create 2 files named startup1.conf and startup2.conf with the following
140 content. These files can be located anywhere. We specify the location when we
145 .. code-block:: console
147 unix {cli-listen /run/vpp/cli-vpp1.sock}
148 api-segment { prefix vpp1 }
149 plugins { plugin dpdk_plugin.so { disable } }
153 .. code-block:: console
155 unix {cli-listen /run/vpp/cli-vpp2.sock}
156 api-segment { prefix vpp2 }
157 plugins { plugin dpdk_plugin.so { disable } }