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 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.
  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 = "puppetlabs/ubuntu-16.04-64-nocm"
  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 apt-get update
  81     $ sudo 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 need to install VPP by modifying the file
  93 **/etc/apt/sources.list.d/99fd.io.list**.
  94
  95 Write this file with the following contents:
  96
  97 .. code-block:: console
  98
  99    deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.ubuntu.xenial.main/ ./
 100
 101 Then execute the following commands.
 102
 103 .. code-block:: console
 104
 105    $ sudo bash
 106    # apt-get update
 107    # apt-get install vpp-lib vpp vpp-plugins
 108    #
 109
 110 Stop VPP for this tutorial. We will be creating our own instances of VPP.
 111
 112 .. code-block:: console
 113
 114    # service vpp stop
 115    #
 116
 117
 118 Create some startup files
 119 --------------------------
 120
 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`.
 124
 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.
 130
 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.
 135
 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
 138 start VPP.
 139
 140 startup1.conf:
 141
 142 .. code-block:: console
 143
 144    unix {cli-listen /run/vpp/cli-vpp1.sock}
 145    api-segment { prefix vpp1 }
 146    plugins { plugin dpdk_plugin.so { disable } }
 147
 148 startup2.conf:
 149
 150 .. code-block:: console
 151
 152    unix {cli-listen /run/vpp/cli-vpp2.sock}
 153    api-segment { prefix vpp2 }
 154    plugins { plugin dpdk_plugin.so { disable } }