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 22.04 (Jammy) box.
   7
   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.
  10
  11 Install Libvirt and Vagrant
  12 -------------------------------
  13
  14 You will need to install Libvirt 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 = "generic/ubuntu2204"
  36
  37       vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
  38       vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
  39
  40       config.ssh.forward_agent = true
  41
  42       config.vm.provider "libvirt" do |vb|
  43           vb.memory = "#{vmram}"
  44           vb.cpus = "#{vmcpu}"
  45       end
  46     end
  47
  48
  49 Running Vagrant
  50 ---------------
  51
  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.
  55
  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,
  58 VPP supports this.
  59
  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
  63 on a file.
  64
  65 Setting up VPP environment with Vagrant
  66 ---------------------------------------------
  67
  68 After setting up Vagrant, use these commands on your Vagrant directory to boot the VM:
  69
  70 .. code-block:: console
  71
  72     $ vagrant up
  73     $ vagrant ssh
  74     $ sudo bash
  75     # apt-get update
  76     # reboot -n
  77     $ # Wait for the VM to reboot
  78     $ vagrant ssh
  79
  80 Install VPP
  81 ------------
  82
  83 Now that the VM is updated, we will install the VPP packages.
  84
  85 For more on installing VPP please refer to :ref:`installingVPP`.
  86
  87 For this tutorial we will install VPP by modifying the file
  88 **/etc/apt/sources.list.d/99fd.io.list**.
  89
  90 We write this file with the following contents:
  91
  92 .. code-block:: console
  93
  94    $ sudo bash
  95    # echo "deb https://packagecloud.io/fdio/release/ubuntu jammy main" > /etc/apt/sources.list.d/99fd.io.list
  96    #
  97
  98 Get the key.
  99
 100 .. code-block:: console
 101
 102    # curl -L https://packagecloud.io/fdio/release/gpgkey | sudo apt-key add -
 103    #
 104
 105 Then execute the following commands.
 106
 107 .. code-block:: console
 108
 109    # apt-get update
 110    # apt-get install vpp vpp-plugin-core vpp-plugin-dpdk
 111    #
 112
 113 Stop VPP for this tutorial. We will be creating our own instances of VPP.
 114
 115 .. code-block:: console
 116
 117    # service vpp stop
 118    #
 119
 120
 121 Create some startup files
 122 --------------------------
 123
 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`.
 127
 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.
 133
 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.
 138
 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
 141 start VPP.
 142
 143 startup1.conf:
 144
 145 .. code-block:: console
 146
 147    unix {cli-listen /run/vpp/cli-vpp1.sock}
 148    api-segment { prefix vpp1 }
 149    plugins { plugin dpdk_plugin.so { disable } }
 150
 151 startup2.conf:
 152
 153 .. code-block:: console
 154
 155    unix {cli-listen /run/vpp/cli-vpp2.sock}
 156    api-segment { prefix vpp2 }
 157    plugins { plugin dpdk_plugin.so { disable } }