Revision as of 20:02, 5 May 2016

Intro

This page tries to give you a quick start guide for Pulling, Building, Running, Hacking, and Pushing VPP Code.

Pulling

fd.io uses Gerrit, a code review front end on git You can pull and push code via ssh or https. ssh is recommended.

Pulling anonymously (https)

You can pull the code anonymously using:

git clone https://gerrit.fd.io/r/vpp

This is the fastest way to get the code, but you cannot *push* anonymously, and so you are going to have to establish an account when you get to the point of pushing code.

Pulling code via ssh

The recommended way to pull code is via ssh, especially if you intend to develop and submit changes. This requires you to setup an account and set up gerrit.

Setting up an account

fd.io uses the Linux Foundations identity system. If you do not already have an LF account, proceed to: https://identity.linuxfoundation.org/ to create one. If you do, you can use your Linux Foundation username and password for all logins at fd.io.

Setting up Gerrit

Make sure you have registered your ssh key with gerrit.

Pulling the code

Type the following git command (replacing USERNAME with your Linux Foundation username):

git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git

Building

Linux

VPP can be built, packaged and run on either Debian based (Ubuntu,etc) or RPM based (Centos,etc) out of the box.

Building the first time

In order to insure up to date instructions for setting up and building the first time, VPP has a script

build-root/vagrant/build.sh

which installs any dependencies, builds the proper packaging for your local Linux distribution, and installs those packages. Simply running this script should get you going fast. It is the same file used to install dependencies, build, and install packages when the vagrant environment is used. It is also a useful place to crib from for how to do those individual steps.

Subsequent Builds

Once you've gone through your first build successfully, there are detailed instructions on building, installing, and testing packages here: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package

Mac OS

Building the First Time

If you are working on a Mac, you will want to stand up a Linux VM.

If you have a Linux VM already, please feel free to simply utilize the Linux' instructions.

If you do not yet have a Linux VM, VPP provides a 'vagrant' setup to help you quickly and simply get one. For more information about using Vagrant on a command-line interface (CLI), see: https://docs.vagrantup.com/v2/cli/index.html

Setting Up Vagrant

Follow the instructions for setting up Vagrant

Choosing alternate hypervisor, distribution, and number of NICs (optional)

By default vagrant will use the Virtualbox provider, and boot an Ubuntu 14.04 VM, and with two extra 'NICs' you can use to try out with VPP.

You can change this by setting environment variables.

Alternate Linux distro environment variable

To boot a Centos 7 VM (rather than the default Ubuntu 14.04 VM)

export VPP_VAGRANT_DISTRO=centos7

Alternate hypervisor environment variable

To use VMWare Fusion as your alternate vagrant provider:

export VAGRANT_DEFAULT_PROVIDER=vmware_fusion

Note: If you use vmware please see Vagrant VMWare Provider, and be aware you will have to purchase the VMWare Vagrant plugin.

Alternate number of extra NICs environment variable

To have a different number of external NICs to use with VPP other than the default of 2 (five in this example): export VPP_VAGRANT_NICS=5

Starting Vagrant

To start your Vagrant VM:

cd build-root/vagrant vagrant up

This will result in a bunch of output as the VM is provisioned, vpp is built, and the vpp packages are installed on the VM and run. Once it completes, you can access the VM with:

vagrant ssh

Which will ssh you into your Vagrant VM.

Subsequent Builds

From your vagrant VM, to perform subsequent builds: cd /vpp which will take you to the top of your vpp tree, and then follow the Linux instructions for subsequent builds.

Running

Running from package installation

The process for starting vpp varies between systems using upstart (Ubuntu 14.04) and systems using systemd (Centos 7 and Ubuntu 16.04).

Running vpp upstart systems (Ubuntu 14.04)

sudo start vpp

Running vpp on systemd systems (Centos 7, Ubuntu 16.04)

sudo service vpp start

Taking vpp for a spin

• Create a tuntap interface and trace a basic ping command
• Try out some of the other use cases