Using Vagrant to Test Traffic Server

The Apache Traffic Server™ project’s official repository includes a Vagrantfile, intended to ease the process of creating environments suitable for building and testing Traffic Server, where all the necessary dependencies are installed automatically for a variety of operating systems and common distribution releases.

Vagrant is a tool for building complete development environments. With an easy-to-use workflow and focus on automation, Vagrant lowers development environment setup time, increases development/production parity, and makes the “works on my machine” excuse a relic of the past.

—VagrantUp website

Vagrant can be used in combination with any of the popular configuration management and automation tools, such as Chef, Puppet, Ansible, and more. The Vagrantfile included in the Traffic Server repository happens to make use of Puppet.

Installing Vagrant and Dependencies

VirtualBox

The virtualization software VirtualBox is required to create and run the virtual machines created by the included project Vagrantfile.

VirtualBox can be obtained by free from the official website, and many distributions provide their own packages as well. No special configuration of the software is required.

Vagrant

A fairly recent version of Vagrant is necessary to use the included Vagrantfile. While older versions of Vagrant could be installed through the Ruby Gems facility, modern versions are only provided as distribution specific packages.

NFS Server

The project Vagrantfile uses the NFS shared folders support of VirtualBox to mount the same directory in which the Vagrantfile is located on your host machine as a network directory inside the virtual machine. For this to work, your host machine must have an NFS server installed and running, and the user under which you run the vagrant commands must have sudo permissions to modify the NFS exports configuration and restart the NFS service.

The virtual machine created by Vagrant will still function without a working NFS server on your host machine, but you will not be able to access the shared folder which includes the entire Traffic Server source tree. You may opt to modify the Vagrantfile to use a method other than NFS, as per the Vagrant documentation.

Managing Virtual Machines

Listing Available Machines

The included Vagrantfile defines many variations of operating systems, releases, and architectures. To see a complete list of the virtual machine options available to you, run the command vagrant status from within the same directory as the Vagrantfile. The command may take a few moments to run as the configurations defined in the Vagrantfile are evaluated, and calls are made to the underlying VirtualBox utilities to check for the existence and operational state of each possibility. You should expect to see output along the lines of:

  1. $ vagrant status
  2. Current machine states:
  4. saucy32                   not created (virtualbox)
  5. raring32                  not created (virtualbox)
  6. quantal32                 not created (virtualbox)
  7. precise32                 not created (virtualbox)
  8. trusty32                  not created (virtualbox)
  9. saucy64                   not created (virtualbox)
  10. raring64                  not created (virtualbox)
  11. quantal64                 not created (virtualbox)
  12. precise64                 not created (virtualbox)
  13. trusty64                  running (virtualbox)
  14. freebsd                   not created (virtualbox)
  15. omnios                    not created (virtualbox)
  16. lucid64                   not created (virtualbox)
  17. fedora18                  not created (virtualbox)
  18. centos63                  not created (virtualbox)
  19. centos59                  not created (virtualbox)
  20. centos64                  not created (virtualbox)
  21. debian7                   not created (virtualbox)
  22. sles11                    not created (virtualbox)
  23. oel63                     not created (virtualbox)
  25. This environment represents multiple VMs. The VMs are all listed
  26. above with their current state. For more information about a specific
  27. VM, run `vagrant status NAME`.

Creating and Destroying

Creation and destruction of virtual machines with Vagrant is very simple. To bring a new virtual machine into existence, run the following command from the same directory in which the Vagrantfile is located:

  1. vagrant up <name>

Where <name> should be the specific operating system release you wish to use for the virtual machine. For example, to test Traffic Server in a CentOS 6.4 environment, you would run:

  1. vagrant up centos64

Running the vagrant up command for a virtual machine which does not exist yet (or has previously been deleted) will create a brand new virtual machine, using the appropriate image (called a basebox in Vagrant parlance), as well as provision the machine according to any configuration management rules specified in the Vagrantfile.

Similarly, you may destroy the virtual machine when you are finished by running the command:

  1. vagrant destroy <name>

Or if you wish to only stop the virtual machine temporarily without deleting it, you may run:

  1. vagrant halt <name>

A halted virtual machine is started back up with the same vagrant up command shown earlier. The difference is that Vagrant will recognize the box already exists and do nothing more than start the vm process and configure the virtual networking interfaces on your host. Any configuration management hooks in the Vagrantfile will be skipped.

Logging In

Logging into a virtual machine created with Vagrant may be accomplished in a couple different ways. The easiest is to let Vagrant itself figure out where the machine is and how to properly authenticate you to it:

  1. vagrant ssh <name>

Using that command from within the same directory as the Vagrantfile allows you to skip figuring out what virtual network interface has been attached to the machine, what local port may be assigned to handle SSH forwarding, and so on. As long as the virtual machine was already running, you will be quickly dropped into a local shell in the virtual machine as the vagrant user.

Important

Vagrant by default uses a widely-shared private RSA key on newly created virtual machines (that are built on public basebox images). The default user on these baseboxes is also configured for password-less sudo permissions. This is very clearly insecure, but Vagrant is designed for local testing and development, not production (or other public) uses, so the project has made the philosophical trade-off in favor of ease of use.

Alternatively, you may SSH directly to the virtual machine. Because the virtual machines are configured to use only the private virtual network layer provided by VirtualBox, you cannot directly. Instead, VirtualBox has created a local port mapping automatically which should be used. There is no fixed, pre-determined port mapping that will be universally valid, as Vagrant and VirtualBox may be used together to run an arbitrary number of virtual machines simultaneously, each provisioned in any order, and defined by any number and variety of Vagrantfiles.

The correct way to determine what port Vagrant and VirtualBox have used to map to a given virtual machine is to run the following command from within the same directory as your Vagrantfile:

  1. vagrant ssh-config <name>

That will output a configuration block, suitable for inclusion in your local ~/.ssh/config file. Note specifically, in addition to the port, the path to the private key you will need to use as your identity when attempting to log into the virtual machine.

Shared Host Folders

VirtualBox provides a facility for mounting directories from your host machine as filesystems inside the virtual machines. The Traffic Server Vagrantfile makes use of this feature to mount its own source tree in a predictable location in the virtual environment.

Multiple methods are available for this, including NFS, CIFS, and simulated block devices. The Traffic Server project opts to use NFS for its simplicity, speed, support for features such as symlinks, and wide interoperability across the various guest operating systems included in the Vagrantfile. Within the included Vagrantfile, you can see the following line:

  1. config.vm.synced_folder ".", "/opt/src/trafficserver.git", :nfs => true

This directs VirtualBox to mount the directory in which the Traffic Server Vagrantfile resides as an NFS mount inside the virtual machine at the path /opt/src/trafficserver.git. Additional host directories may be mounted in the same manner should the need arise.

Forwarding Custom Ports

Building Traffic Server Inside Vagrant

Producing Traffic Server builds from within the Vagrant managed virtual machines is effectively no different than in any other environment. The same directory in which the Vagrantfile exists will be mounted via NFS inside the virtual machine at the path /opt/src/trafficserver.git.

Note

If you have run autoconf or configure from outside the virtual machine environment against the same Git working copy as is mounted inside the virtual machine, you will encounter failures should you attempt to run any of the Make targets inside the VM. Any build related commands should be run inside of the virtual machine. Additionally, if you are running more than one virtual machine simultaneously, remember that they are each using the same NFS export on your host machine.