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       else
  38         config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
  39
  40 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*.
  41
  42 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.
  43
  44 .. code-block:: ruby
  45
  46     config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
  47     config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
  48
  49 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.
  50
  51
  52 Looking further in the :ref:`vppVagrantfile`, you can see more Ruby variables being set to ENV's or to a default value:
  53
  54 .. code-block:: ruby
  55
  56     # Define some physical ports for your VMs to be used by DPDK
  57     nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
  58     for i in 1..nics
  59       config.vm.network "private_network", type: "dhcp"
  60     end
  61
  62     # use http proxy if available
  63     if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
  64      config.proxy.http     = ENV['http_proxy']
  65      config.proxy.https    = ENV['https_proxy']
  66      config.proxy.no_proxy = "localhost,127.0.0.1"
  67     end
  68
  69     vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
  70     vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
  71
  72
  73 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).
  74
  75
  76 Box bootup
  77 __________
  78
  79
  80 Once you're satisfied with your *Vagrantfile*, boot the box with:
  81
  82 .. code-block:: shell
  83
  84     $ vagrant up
  85
  86 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.
  87
  88 To confirm it is up, show the status and information of Vagrant boxes with:
  89
  90 .. code-block:: console
  91
  92   $ vagrant global-status
  93   id       name    provider   state    directory
  94   -----------------------------------------------------------------------------------------
  95   d90a17b  default virtualbox poweroff /home/centos/andrew-vpp/vppsb/vpp-userdemo
  96   77b085e  default virtualbox poweroff /home/centos/andrew-vpp/vppsb2/vpp-userdemo
  97   c1c8952  default virtualbox poweroff /home/centos/andrew-vpp/testingVPPSB/extras/vagrant
  98   c199140  default virtualbox running  /home/centos/andrew-vpp/vppsb3/vpp-userdemo
  99
 100   You will have only one machine running, but I have multiple as shown above.
 101
 102 .. note::
 103
 104   To poweroff your VM, type:
 105
 106   .. code-block:: shell
 107
 108      $ vagrant halt <id>
 109
 110   To resume your VM, type:
 111
 112   .. code-block:: shell
 113
 114      $ vagrant resume <id>
 115
 116   To destroy your VM, type:
 117
 118   .. code-block:: shell
 119
 120      $ vagrant destroy <id>
 121
 122   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/>`_.