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