Initial commit of Sphinx docs

Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77
Signed-off-by: John DeNisco <jdenisco@cisco.com>

8 files changed, 419 insertions, 0 deletions

diff --git a/docs/reference/vppvagrant/VagrantVMSetup.rst b/docs/reference/vppvagrant/VagrantVMSetup.rst
new file mode 100644
index 00000000000..769c6186170
--- /dev/null
+++ b/docs/reference/vppvagrant/VagrantVMSetup.rst
@@ -0,0 +1,56 @@
+.. _VagrantVMSetup:
+
+.. toctree::
+
+Accessing your VM
+^^^^^^^^^^^^^^^^^
+ssh into the newly created box:
+
+.. code-block:: console
+
+    $ vagrant ssh <id>
+
+Sample output looks like:
+
+.. code-block:: console
+
+  $ vagrant ssh c1c
+  Welcome to Ubuntu 16.04 LTS (GNU/Linux 4.4.0-21-generic x86_64)
+
+   * Documentation:  https://help.ubuntu.com/
+  Last login: Mon Jun 25 08:05:38 2018 from 10.0.2.2
+  vagrant@localhost:~$
+
+
+.. note::
+  
+  Type **exit** in the command-line if you want to exit the VM.
+
+Become the root with:
+
+.. code-block:: console
+
+    $ sudo bash
+
+Now *install* VPP in the VM. Keep in mind that VPP is already built (but not yet installed) at this point based on the commands from the provisioned script *build.sh*. 
+
+When you ssh into your Vagrant box you will be placed in the directory */home/vagrant*. Change directories to */vpp/build-root*, and run these commands to install VPP based on your OS and architechture:
+
+For Ubuntu systems:
+
+.. code-block:: console
+    
+    # dpkg -i *.deb
+
+For CentOS systems:
+
+.. code-block:: console
+    
+    # rpm -Uvh *.rpm
+
+
+Since VPP is now installed, you can start running VPP with:
+
+.. code-block:: console
+  
+  # service vpp start 
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/Vagrantfile b/docs/reference/vppvagrant/Vagrantfile
new file mode 100644
index 00000000000..32a13adedd8
--- /dev/null
+++ b/docs/reference/vppvagrant/Vagrantfile
@@ -0,0 +1,115 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant.configure(2) do |config|
+
+  # Pick the right distro and bootstrap, default is ubuntu1604
+  distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
+  if distro == 'centos7'
+    config.vm.box = "centos/7"
+    config.vm.box_version = "1708.01"
+    config.ssh.insert_key = false
+  elsif distro == 'opensuse'
+    config.vm.box = "opensuse/openSUSE-42.3-x86_64"
+    config.vm.box_version = "1.0.4.20170726"
+  else
+    config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
+  end
+  config.vm.box_check_update = false
+
+  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
+  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
+
+  post_build = ( ENV['VPP_VAGRANT_POST_BUILD'] )
+  if post_build == "test"
+    config.vm.provision "shell", inline: "echo Testing VPP; cd /vpp; make test"
+  elsif post_build == "install"
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"install.sh"), :args => "/vpp"
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"clearinterfaces.sh")
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"run.sh")
+  end
+
+  # Add .gnupg dir in so folks can sign patches
+  # Note, as gnupg puts socket files in that dir, we have
+  # to be cautious and make sure we are dealing with a plain file
+  homedir = File.expand_path("~/")
+  Dir["#{homedir}/.gnupg/**/*"].each do |fname|
+    if File.file?(fname)
+      destname = fname.sub(Regexp.escape("#{homedir}/"),'')
+      config.vm.provision "file", source: fname, destination: destname
+    end
+  end
+
+  # Copy in the .gitconfig if it exists
+  if File.file?(File.expand_path("~/.gitconfig"))
+    config.vm.provision  "file", source: "~/.gitconfig", destination: ".gitconfig"
+  end
+
+  # vagrant-cachier caches apt/yum etc to speed subsequent
+  # vagrant up
+  # to enable, run
+  # vagrant plugin install vagrant-cachier
+  #
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :box
+  end
+
+  # Define some physical ports for your VMs to be used by DPDK
+  nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
+  for i in 1..nics
+    config.vm.network "private_network", type: "dhcp"
+  end
+
+  # use http proxy if avaiable
+  if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
+   config.proxy.http     = ENV['http_proxy']
+   config.proxy.https    = ENV['https_proxy']
+   config.proxy.no_proxy = "localhost,127.0.0.1"
+  end
+
+  vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
+  vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
+
+  config.ssh.forward_agent = true
+  config.ssh.forward_x11 = true
+
+  config.vm.provider "virtualbox" do |vb|
+      vb.customize ["modifyvm", :id, "--ioapic", "on"]
+      vb.memory = "#{vmram}"
+      vb.cpus = "#{vmcpu}"
+
+      # rsync the vpp directory if provision hasn't happened yet
+      unless File.exist? (".vagrant/machines/default/virtualbox/action_provision")
+        config.vm.synced_folder "../../", "/vpp", type: "rsync",
+         rsync__auto: false,
+         rsync__exclude: [
+          "build-root/build*/",
+          "build-root/install*/",
+          "build-root/images*/",
+          "build-root/*.deb",
+          "build-root/*.rpm",
+          "build-root/*.changes",
+          "build-root/python",
+          "build-root/deb/debian/*.dkms",
+          "build-root/deb/debian/*.install",
+          "build-root/deb/debian/changes",
+          "build-root/tools"]
+      end
+
+      #support for the SSE4.x instruction is required in some versions of VB.
+      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
+      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
+  end
+  config.vm.provider "vmware_fusion" do |fusion,override|
+    fusion.vmx["memsize"] = "#{vmram}"
+    fusion.vmx["numvcpus"] = "#{vmcpu}"
+  end
+  config.vm.provider "libvirt" do |lv|
+    lv.memory = "#{vmram}"
+    lv.cpus = "#{vmcpu}"
+  end
+  config.vm.provider "vmware_workstation" do |vws,override|
+    vws.vmx["memsize"] = "#{vmram}"
+    vws.vmx["numvcpus"] = "#{vmcpu}"
+  end
+end
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/boxSetup.rst b/docs/reference/vppvagrant/boxSetup.rst
new file mode 100644
index 00000000000..d23033da856
--- /dev/null
+++ b/docs/reference/vppvagrant/boxSetup.rst
@@ -0,0 +1,125 @@
+.. _boxSetup:
+
+.. toctree::
+
+
+Vagrantfiles
+============
+
+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).
+
+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. 
+
+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.
+
+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.
+
+
+Box configuration 
+_________________
+
+
+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.)
+
+.. code-block:: ruby
+
+    # -*- mode: ruby -*-
+    # vi: set ft=ruby :
+
+    Vagrant.configure(2) do |config|
+
+      # Pick the right distro and bootstrap, default is ubuntu1604
+      distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
+      if distro == 'centos7'
+        config.vm.box = "centos/7"
+        config.vm.box_version = "1708.01"
+        config.ssh.insert_key = false
+      elsif distro == 'opensuse'
+        config.vm.box = "opensuse/openSUSE-42.3-x86_64"
+        config.vm.box_version = "1.0.4.20170726"
+      else
+        config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
+
+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*.
+
+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.
+
+.. code-block:: ruby
+
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
+
+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.
+
+
+Looking further in the :ref:`vppVagrantfile`, you can see more Ruby variables being set to ENV's or to a default value:
+
+.. code-block:: ruby
+
+    # Define some physical ports for your VMs to be used by DPDK
+    nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
+    for i in 1..nics
+      config.vm.network "private_network", type: "dhcp"
+    end
+
+    # use http proxy if avaiable
+    if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
+     config.proxy.http     = ENV['http_proxy']
+     config.proxy.https    = ENV['https_proxy']
+     config.proxy.no_proxy = "localhost,127.0.0.1"
+    end
+
+    vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
+    vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
+
+
+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).
+
+
+Box bootup
+__________
+
+
+Once you're satisfied with your *Vagrantfile*, boot the box with:
+
+.. code-block:: console
+
+    $ vagrant up
+
+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.
+
+To confirm it is up, show the status and information of Vagrant boxes with: 
+
+.. code-block:: console
+
+  $ vagrant global-status
+  id       name    provider   state    directory                                           
+  -----------------------------------------------------------------------------------------
+  d90a17b  default virtualbox poweroff /home/centos/andrew-vpp/vppsb/vpp-userdemo          
+  77b085e  default virtualbox poweroff /home/centos/andrew-vpp/vppsb2/vpp-userdemo         
+  c1c8952  default virtualbox poweroff /home/centos/andrew-vpp/testingVPPSB/extras/vagrant 
+  c199140  default virtualbox running  /home/centos/andrew-vpp/vppsb3/vpp-userdemo 
+
+  You will have only one machine running, but I have multiple as shown above.
+
+.. note::
+
+  To poweroff your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant halt <id>
+
+  To resume your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant resume <id>
+     
+  To destroy your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant destroy <id>
+
+  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/>`_.
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/index.rst b/docs/reference/vppvagrant/index.rst
new file mode 100644
index 00000000000..7852cb88514
--- /dev/null
+++ b/docs/reference/vppvagrant/index.rst
@@ -0,0 +1,17 @@
+.. _vppcontainers:
+
+VM's with Vagrant
+=================
+
+This reference guide will cover using Vagrant to boot a VM (virtual machine).
+
+.. toctree::
+
+    vagrantOverview
+    installingVboxVagrant
+    settingENV
+    boxSetup
+    VagrantVMSetup
+    vppVagrantfile
+
+
diff --git a/docs/reference/vppvagrant/installingVboxVagrant.rst b/docs/reference/vppvagrant/installingVboxVagrant.rst
new file mode 100644
index 00000000000..1bd4ba076d7
--- /dev/null
+++ b/docs/reference/vppvagrant/installingVboxVagrant.rst
@@ -0,0 +1,38 @@
+.. _installingVboxVagrant:
+
+.. toctree::
+
+Installing Vbox and Vagrant
+===========================
+
+Installing VirtualBox
+_____________________
+
+First download VirtualBox, which is virtualization software for creating VM's.
+
+If you're on CentOS, follow the `steps here <https://wiki.centos.org/HowTos/Virtualization/VirtualBox>`_.
+
+
+If you're on Ubuntu, perform:
+
+.. code-block:: console
+
+   $ sudo apt-get install virtualbox 
+
+Installing Vagrant
+__________________
+
+Here we are on a 64-bit version of CentOS, downloading and installing Vagrant 2.1.2:
+
+.. code-block:: console
+
+   $ yum -y install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.rpm
+
+This is a similar command, but on a 64-bit version of Debian:
+
+.. code-block:: console
+
+   $ sudo apt-get install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.deb
+
+
+If you want to download a newer version of Vagrant or one specific to your OS and architecture, go to the Vagrant `download page <https://www.vagrantup.com/downloads.html>`_, right-click and copy the link address for your specified version, and replace the above install command for your respective OS and architechure.
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/settingENV.rst b/docs/reference/vppvagrant/settingENV.rst
new file mode 100644
index 00000000000..269b36bda84
--- /dev/null
+++ b/docs/reference/vppvagrant/settingENV.rst
@@ -0,0 +1,29 @@
+.. _settingENV:
+
+.. toctree::
+
+
+Setting your ENV Variables
+==========================
+
+
+The :ref:`vppVagrantfile` used in the VPP repo sets the configuration options based on your ENV (environment) variables, or to default the configuration at specified values if your ENV variables are not initialized (if you did not run the *env.sh* script found below). 
+
+This is the *env.sh* script found in *vpp/extras/vagrant*. When run, the script sets ENV variables using the **export** command.
+
+.. code-block:: bash
+
+    export VPP_VAGRANT_DISTRO="ubuntu1604"
+    export VPP_VAGRANT_NICS=2
+    export VPP_VAGRANT_VMCPU=4
+    export VPP_VAGRANT_VMRAM=4096 
+
+In the :ref:`vppVagrantfile`, you can see these same ENV variables used (discussed on the next page).
+
+Adding your own ENV variables is easy. For example, if you wanted to setup proxies for your VM, you would add to this file the **export** commands found in the :ref:`building VPP commands section <building>`. Note that this only works if the ENV variable is defined in the :ref:`vppVagrantfile`.
+
+Once you're finished with *env.sh* script, and you are in the directory containing *env.sh*, run the script to set the ENV variables with:
+
+.. code-block:: console
+   
+   $ source ./env.sh
diff --git a/docs/reference/vppvagrant/vagrantOverview.rst b/docs/reference/vppvagrant/vagrantOverview.rst
new file mode 100644
index 00000000000..882b8a68cfd
--- /dev/null
+++ b/docs/reference/vppvagrant/vagrantOverview.rst
@@ -0,0 +1,25 @@
+.. _vagrantOverview:
+
+.. toctree::
+
+Overview
+^^^^^^^^
+
+This guide shows how the VPP :ref:`vppVagrantfile` interacts with shell scripts to configure a `Vagrant box <https://www.vagrantup.com/docs/boxes.html>`_ that boots a VM with VPP. 
+
+.. _prereqlabel:
+
+Prerequisites
+_____________
+
+You have the `FD.io VPP repo <https://github.com/FDio/vpp>`_ cloned locally on your machine. 
+
+
+This guide will refer to the following files from that repo: *Vagrantfile, build.sh, env.sh, and update.sh*.
+
+
+
+
+
+
+
diff --git a/docs/reference/vppvagrant/vppVagrantfile.rst b/docs/reference/vppvagrant/vppVagrantfile.rst
new file mode 100644
index 00000000000..d3c705542bd
--- /dev/null
+++ b/docs/reference/vppvagrant/vppVagrantfile.rst
@@ -0,0 +1,14 @@
+.. _vppVagrantfile:
+
+Vagrant File
+============
+
+This is the Vagrantfile provided in the `Git VPP repo <https://github.com/FDio/vpp/blob/master/extras/vagrant/Vagrantfile>`_.
+
+.. literalinclude:: Vagrantfile
+   :language: Ruby
+   :emphasize-lines: 4-17, 20-21, 57-71
+
+
+
+.. toctree::