docs/gettingstarted/progressivevpp/settingupenvironment.rst

   1 .. _settingupenvironment:
   2
   3 Setting up your environment
   4 ===========================
   5
   6 All of these exercises are designed to be performed on an Ubuntu 16.04 (Xenial) box.
   7
   8 * If you have an Ubuntu 18.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 18.04 box for you in the the steps below.
  10
  11 Install Virtual Box and Vagrant
  12 -------------------------------
  13
  14 You will need to install Virtual Box and Vagrant.
  15
  16 Create a Vagrant Directory
  17 ---------------------------
  18
  19 To get started create a directory for vagrant
  20
  21 .. code-block:: console
  22
  23    $ mkdir vpp-tutorial
  24    $ cd vpp-tutorial
  25
  26 Create a file called **Vagrantfile** with the following contents:
  27
  28 .. code-block:: ruby
  29
  30     # -*- mode: ruby -*-
  31     # vi: set ft=ruby :
  32
  33     Vagrant.configure(2) do |config|
  34
  35       config.vm.box = "bento/ubuntu-18.04"
  36       config.vm.box_check_update = false
  37
  38       vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
  39       vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
  40
  41       config.ssh.forward_agent = true
  42
  43       config.vm.provider "virtualbox" do |vb|
  44           vb.customize ["modifyvm", :id, "--ioapic", "on"]
  45           vb.memory = "#{vmram}"
  46           vb.cpus = "#{vmcpu}"
  47           #support for the SSE4.x instruction is required in some versions of VB.
  48           vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
  49           vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
  50       end
  51     end
  52
  53
  54 Running Vagrant
  55 ---------------
  56
  57 VPP runs in userspace.  In a production environment you will often run it with
  58 DPDK to connect to real NICs or vhost to connect to VMs.mIn those circumstances
  59 you usually run a single instance of VPP.
  60
  61 For purposes of this tutorial, it is going to be extremely useful to run multiple
  62 instances of vpp, and connect them to each other to form a topology.  Fortunately,
  63 VPP supports this.
  64
  65 When running multiple VPP instances, each instance needs to have specified a 'name'
  66 or 'prefix'.  In the example below, the 'name' or 'prefix' is "vpp1". Note that only
  67 one instance can use the dpdk plugin, since this plugin is trying to acquire a lock
  68 on a file.
  69
  70 Setting up VPP environment with Vagrant
  71 ---------------------------------------------
  72
  73 After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
  74
  75 .. code-block:: console
  76
  77     $ vagrant up
  78     $ vagrant ssh
  79     $ sudo bash
  80     # apt-get update
  81     # reboot -n
  82     $ # Wait for the VM to reboot
  83     $ vagrant ssh
  84
  85 Install VPP
  86 ------------
  87
  88 Now that the VM is updated, we will install the VPP packages.
  89
  90 For more on installing VPP please refer to :ref:`installingVPP`.
  91
  92 For this tutorial we will install VPP by modifying the file
  93 **/etc/apt/sources.list.d/99fd.io.list**.
  94
  95 We write this file with the following contents:
  96
  97 .. code-block:: console
  98
  99    $ sudo bash
 100    # echo "deb [trusted=yes] https://packagecloud.io/fdio/release/ubuntu bionic main" > /etc/apt/sources.list.d/99fd.io.list
 101    #
 102
 103 Get the key.
 104
 105 .. code-block:: console
 106
 107    # curl -L https://packagecloud.io/fdio/release/gpgkey | sudo apt-key add -
 108    #
 109
 110 Then execute the following commands.
 111
 112 .. code-block:: console
 113
 114    # apt-get update
 115    # apt-get install vpp vpp-plugin-core vpp-plugin-dpdk
 116    #
 117
 118 Stop VPP for this tutorial. We will be creating our own instances of VPP.
 119
 120 .. code-block:: console
 121
 122    # service vpp stop
 123    #
 124
 125
 126 Create some startup files
 127 --------------------------
 128
 129 We will create some startup files for the use of this tutorial. Typically you will
 130 modify the startup.conf file found in /etc/vpp/startup.conf. For more information
 131 on this file refer to :ref:`configuration_reference`.
 132
 133 When running multiple VPP instances, each instance needs to have
 134 specified a 'name' or 'prefix'. In the example below, the 'name' or 'prefix'
 135 is "vpp1". Note that only one instance can use the dpdk plugin, since this
 136 plugin is trying to acquire a lock on a file. These startup files we create will
 137 disable the dpdk plugin.
 138
 139 Also in our startup files notice **api-segment**. **api-segment {prefix vpp1}**
 140 tells FD.io VPP how to name the files in /dev/shm/ for your VPP instance
 141 differently from the default. **unix {cli-listen /run/vpp/cli-vpp1.sock}**
 142 tells vpp to use a non-default socket file when being addressed by vppctl.
 143
 144 Now create 2 files named startup1.conf and startup2.conf with the following
 145 content. These files can be located anywhere. We specify the location when we
 146 start VPP.
 147
 148 startup1.conf:
 149
 150 .. code-block:: console
 151
 152    unix {cli-listen /run/vpp/cli-vpp1.sock}
 153    api-segment { prefix vpp1 }
 154    plugins { plugin dpdk_plugin.so { disable } }
 155
 156 startup2.conf:
 157
 158 .. code-block:: console
 159
 160    unix {cli-listen /run/vpp/cli-vpp2.sock}
 161    api-segment { prefix vpp2 }
 162    plugins { plugin dpdk_plugin.so { disable } }