docs/reference/vppvagrant/boxSetup.rst

   1 .. _boxSetup:
   2
   3 .. toctree::
   4
   5
   6 Vagrantfiles
   7 ============
   8
   9 A `Vagrantfile <https://www.vagrantup.com/docs/vagrantfile/>`_ contains the box and provision configuration settings for your VM. The syntax of Vagrantfiles is Ruby (Ruby experience is not necessary).
  10
  11 The command **vagrant up** creates a *Vagrant Box* based on your Vagrantfile. A Vagrant box is one of the motivations for using Vagrant - its a "development-ready box" that can be copied to other machines to recreate the same environment.
  12
  13 It's common for people to think that a Vagrant box *is* the VM. But rather, the VM is *inside* a Vagrant box, with the box containing additional configuration options you can set, such as VM options, scripts to run on boot, etc.
  14
  15 This `Vagrant website for boxes <https://app.vagrantup.com/boxes/search>`_  shows you how to configure a basic Vagrantfile for your specific OS and VM software.
  16
  17
  18 Box configuration
  19 _________________
  20
  21
  22 Looking at the :ref:`vppVagrantfile`, we can see that the default OS is Ubuntu 16.04 (since the variable *distro* equals *ubuntu1604* if there is no VPP_VAGRANT_DISTRO variable set - thus the **else** case is executed.)
  23
  24 .. code-block:: ruby
  25
  26     # -*- mode: ruby -*-
  27     # vi: set ft=ruby :
  28
  29     Vagrant.configure(2) do |config|
  30
  31       # Pick the right distro and bootstrap, default is ubuntu1604
  32       distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
  33       if distro == 'centos7'
  34         config.vm.box = "centos/7"
  35         config.vm.box_version = "1708.01"
  36         config.ssh.insert_key = false
  37       elsif distro == 'opensuse'
  38         config.vm.box = "opensuse/openSUSE-42.3-x86_64"
  39         config.vm.box_version = "1.0.4.20170726"
  40       else
  41         config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
  42
  43 As mentioned in the previous page, you can specify which OS and VM provider you want for your Vagrant box from the `Vagrant boxes page <https://app.vagrantup.com/boxes/search>`_, and setting your ENV variable appropriately in *env.sh*.
  44
  45 Next in the Vagrantfile, you see some *config.vm.provision* commands. As paraphrased from `Basic usage of Provisioners <https://www.vagrantup.com/docs/provisioning/basic_usage.html>`_, by default these are only run *once* - during the first boot of the box.
  46
  47 .. code-block:: ruby
  48
  49     config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
  50     config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
  51
  52 The two lines above set the VM to run two scripts during its first bootup: an update script *update.sh* that does basic updating and installation of some useful tools, as well as *build.sh* that builds (but does **not** install) VPP in the VM. You can view these scripts on your own for more detail on the commands used.
  53
  54
  55 Looking further in the :ref:`vppVagrantfile`, you can see more Ruby variables being set to ENV's or to a default value:
  56
  57 .. code-block:: ruby
  58
  59     # Define some physical ports for your VMs to be used by DPDK
  60     nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
  61     for i in 1..nics
  62       config.vm.network "private_network", type: "dhcp"
  63     end
  64
  65     # use http proxy if avaiable
  66     if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
  67      config.proxy.http     = ENV['http_proxy']
  68      config.proxy.https    = ENV['https_proxy']
  69      config.proxy.no_proxy = "localhost,127.0.0.1"
  70     end
  71
  72     vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
  73     vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
  74
  75
  76 You can see how the box or VM is configured, such as the amount of NICs (defaults to 3 NICs: 1 x NAT - host access and 2 x VPP DPDK enabled), CPUs (defaults to 2), and RAM (defaults to 4096 MB).
  77
  78
  79 Box bootup
  80 __________
  81
  82
  83 Once you're satisfied with your *Vagrantfile*, boot the box with:
  84
  85 .. code-block:: console
  86
  87     $ vagrant up
  88
  89 Doing this above command will take quite some time, since you are installing a VM and building VPP. Take a break and get some scooby snacks while you wait.
  90
  91 To confirm it is up, show the status and information of Vagrant boxes with:
  92
  93 .. code-block:: console
  94
  95   $ vagrant global-status
  96   id       name    provider   state    directory
  97   -----------------------------------------------------------------------------------------
  98   d90a17b  default virtualbox poweroff /home/centos/andrew-vpp/vppsb/vpp-userdemo
  99   77b085e  default virtualbox poweroff /home/centos/andrew-vpp/vppsb2/vpp-userdemo
 100   c1c8952  default virtualbox poweroff /home/centos/andrew-vpp/testingVPPSB/extras/vagrant
 101   c199140  default virtualbox running  /home/centos/andrew-vpp/vppsb3/vpp-userdemo
 102
 103   You will have only one machine running, but I have multiple as shown above.
 104
 105 .. note::
 106
 107   To poweroff your VM, type:
 108
 109   .. code-block:: console
 110
 111      $ vagrant halt <id>
 112
 113   To resume your VM, type:
 114
 115   .. code-block:: console
 116
 117      $ vagrant resume <id>
 118
 119   To destroy your VM, type:
 120
 121   .. code-block:: console
 122
 123      $ vagrant destroy <id>
 124
 125   Note that "destroying" a VM does not erase the box, but rather destroys all resources allocated for that VM. For other Vagrant commands, such as destroying a box, refer to the `Vagrant CLI Page <https://www.vagrantup.com/docs/cli/>`_.