1 .. _settingupenvironment:
3 Setting up your environment
4 ===========================
6 All of these exercises are designed to be performed on an Ubuntu 16.04 (Xenial) box.
8 * If you have an Ubuntu 16.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 16.04 box for you in the the steps below.
11 Install Virtual Box and Vagrant
12 -------------------------------
14 You will need to install Virtual Box and Vagrant. If you have not installed Virtual Box or Vagrant please
15 refer to :ref:`installingVboxVagrant` to install Virtual Box and Vagrant.
17 Create a Vagrant Directory
18 ---------------------------
20 To get started create a directory for vagrant
22 .. code-block:: console
27 Create a file called **Vagrantfile** with the following contents:
34 Vagrant.configure(2) do |config|
36 config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
37 config.vm.box_check_update = false
39 vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
40 vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
42 config.ssh.forward_agent = true
44 config.vm.provider "virtualbox" do |vb|
45 vb.customize ["modifyvm", :id, "--ioapic", "on"]
46 vb.memory = "#{vmram}"
48 #support for the SSE4.x instruction is required in some versions of VB.
49 vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
50 vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
58 VPP runs in userspace. In a production environment you will often run it with
59 DPDK to connect to real NICs or vhost to connect to VMs.mIn those circumstances
60 you usually run a single instance of VPP.
62 For purposes of this tutorial, it is going to be extremely useful to run multiple
63 instances of vpp, and connect them to each other to form a topology. Fortunately,
66 When running multiple VPP instances, each instance needs to have specified a 'name'
67 or 'prefix'. In the example below, the 'name' or 'prefix' is "vpp1". Note that only
68 one instance can use the dpdk plugin, since this plugin is trying to acquire a lock
71 Setting up VPP environment with Vagrant
72 ---------------------------------------------
74 After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
76 .. code-block:: console
82 $ # Wait for the VM to reboot
88 Now that the VM is updated, we will install the VPP packages.
90 For more on installing VPP please refer to :ref:`installingVPP`.
92 For this tutorial we need to install VPP by modifying the file
93 **/etc/apt/sources.list.d/99fd.io.list**.
95 Write this file with the following contents:
97 .. code-block:: console
99 deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.ubuntu.xenial.main/ ./
101 Then execute the following commands.
103 .. code-block:: console
107 # apt-get install vpp-lib vpp vpp-plugins
110 Stop VPP for this tutorial. We will be creating our own instances of VPP.
112 .. code-block:: console
118 Create some startup files
119 --------------------------
121 We will create some startup files for the use of this tutorial. Typically you will
122 modify the startup.conf file found in /etc/vpp/startup.conf. For more information
123 on this file refer to :ref:`startup`.
125 When running multiple VPP instances, each instance needs to have
126 specified a 'name' or 'prefix'. In the example below, the 'name' or 'prefix'
127 is "vpp1". Note that only one instance can use the dpdk plugin, since this
128 plugin is trying to acquire a lock on a file. These startup files we create will
129 disable the dpdk plugin.
131 Also in our startup files notice **api-segment**. **api-segment {prefix vpp1}**
132 tells FD.io VPP how to name the files in /dev/shm/ for your VPP instance
133 differently from the default. **unix {cli-listen /run/vpp/cli-vpp1.sock}**
134 tells vpp to use a non-default socket file when being addressed by vppctl.
136 Now create 2 files named startup1.conf and startup2.conf with the following
137 content. These files can be located anywhere. We specify the location when we
142 .. code-block:: console
144 unix {cli-listen /run/vpp/cli-vpp1.sock}
145 api-segment { prefix vpp1 }
146 plugins { plugin dpdk_plugin.so { disable } }
150 .. code-block:: console
152 unix {cli-listen /run/vpp/cli-vpp2.sock}
153 api-segment { prefix vpp2 }
154 plugins { plugin dpdk_plugin.so { disable } }