Vagrant Kickstarter

What?

The English dictionary defines the word vagrant as:

A person without a settled home or regular work who wanders from place to place and lives by begging

Vagrant is a “meta product” for building and managing your virtual environments. It has no “settled home”, as the dictionary states - it allows you the option of using any of the popular virtualization providers out there such as VirtualBox, VMware, AWS, etc. It does this by creating a level of abstraction using a templating engine that uses JSON files to lift some of the commonly shared tasks and have them in a central, provider-agnostic, high-level and easy to maintain set of files.

Why?

Previously we would spin up VMs using applications such as VirtualBox, VMware, etc. The process of spinning up a VM included steps specific to VirtualBox or VMware. This resulted in more maintainance and complexity especially when you want to test your application on multiple platforms and platform versions.

Vagrant creates a level of abstraction to pull common elements from different platforms/providers introduces a templating engine that uses JSON files to describe your desired state for the VM, to the point where it creates a level of abstraction to help create a VM while being provider-agnostic.

Terminology

TODO

Commands

Below are the general commands you will need to know and will use most often.

vagrant up

Starts the machine.

NOTE: For Windows machines, you’ll need to enable hardware virtualization in the BIOS to be able to start a new Vagrant machine.

NOTE: Use vagrant up --debug to debug any issues with starting a machine. You will get a massive amount of output so best to pipe it to a file and examine it afterwards.

vagrant halt

Stops the machine.

vagrant reload

Stops the machine, reloads the configuration of the machine and then starts it again.

Useful when you change the Vagrantfile. For example, you change the CPU or Memory of the machine.

vagrant ssh

Perform SSH connection to the machine. Typically you will ssh using vagrant as the user.

If you configure you vagrant machines with your own key (instead of the insecure vagrant key that is the default) then you will need to ssh to the machine using the following syntax to point Vagrant to the specific private key.

vagrant ssh [name|id] [-- extra_ssh_args]

Here is a specific example:

vagrant ssh web -- -i ~/.ssh/id_rsa

vagrant status

Scans all defined Vagrant machines that are defined in the Vagrantfile and shows their status.

vagrant global-status

Lists all known vagrant machines from any folder on your current system. This is very useful to cleanup old vagrant boxes. Use the following command to prune the old systems.

vagrant global-status --prune

Debugging

Whenever you hit an issue with using Vagrant, use the --debug option to gather very detailed information.

For example, when running vagrant up you can save the output to a log file to review. This is recommended because an enormous amount of information is produced in debug mode.

vagrant up --debug &> vagrant.log

Scan for sensitive information! Vagrant debug logs include information about your system including environment variables and user information. If you store sensitive information in the environment or in your user account, please scan or scrub the debug log of this information before uploading the contents to the public Internet.

Submit debug logs using GitHub Gist. If you plan on submitting a bug report or issue that includes debug-level logs, please use a service like Gist. Do not paste the raw debug logs into an issue as it makes it very difficult to scroll and parse the information.

For more information reference Vagrant Debugging

Packer

You can also create your own Vagrant boxes using the powerful yet simple Packer tool. I highly recommend getting familiar with this tool as it makes it really easy to build a new Vagrant box using multiple virtualization providers and a simple JSON configuration file.

My favorite box creation templates are from boxcutter. Create fresh Vagrant boxes using these Packer templates. BoxCutter has community-driven templates and tools for creating cloud, virtual machines, containers and metal operating system environments

Boxes

Vagrant requires a box or image of an operating system in order to start your virtual machines. You can find great example boxes from the following places, however my recommendation is to create your own boxes using Packer. This lets you control what is inside the box. I find many boxes online have a lot of unnecessary junk installed that we all do not need. I prefer a minimal box that I can build upon.

Nevertheless, as a kickstarter you can try these boxes just so you can get a feel for Vagrant.

vagrantup.com

Search Vagrant’s official cloud for submitted boxes.

vagrantbox.es

Download boxes from vagrantbox.es

Plugins

Vagrant allows you to install plugins that bring extra functionality and integration to ease your daily life. Here are some of the most useful plugins. This website maintains a bigger list of Vagrant plugins if you wish to explore other ones. However, these are the ones I believe are the best from my experience with Vagrant.

vagrant-vbguest

A Vagrant plugin to keep your VirtualBox Guest Additions up to date.

vagrant-scp

A Vagrant plugin to copy files to a Vagrant VM via SCP

vagrant-libvirt

A Vagrant plugin to add support for the libvirt provider.

vagrant-rhn-satellite

A Vagrant plugin that allows registration with a Red Hat Network Satellite server as part of the provisioning process.

vagrant-registration

A Vagrant plugin that registers your machines for updates on systems with a subscription model (like Red Hat Enterprise Linux, RHEL). This plugin would run register action on vagrant up before any provisioning and unregister on vagrant halt or vagrant destroy. The actions then call the registration capabilities that have to be provided for the given OS. The plugin is designed in a registration-manager agnostic way, which means, that the plugin itself, depends neither on any OS nor on the way of registration. However it currently only supports RHEL’s Subscription Manager and rhn_register.

Note, use the following workaround when using this plugin with RHEL 7.5. This is currently an open issue.

vagrant-list

A Vagrant plugin that adds a list command to the vagrant command line interface to list known Virtual Machines - the full list extracted from Virtualbox (not just the short list based on your Vagrantfile). Very useful to see the big picture of what is running on your laptop.

In the example here, it first lists ALL machines and then it lists the RUNNING machines.

> vagrant list
ALL:
96a0619a-467b-4338-888e-83da58cbae5c: redhat (Red Hat (64-bit))
818177c0-f1eb-47da-aad3-fa128b5e70e5: minishift (Linux 2.6 / 3.x / 4.x (64-bit))
4544aa29-b002-4ff2-9f47-f4d71e0bd15d: vm (Oracle (64-bit))
RUNNING:
4544aa29-b002-4ff2-9f47-f4d71e0bd15d: vm (Oracle (64-bit))

vagrant-hostmanager

A Vagrant plugin that manages hosts files within a multi-machine environment on both the guest and host machines.

Providers

Vagrant has a variety of virtualization providers. You can find the full list on their website but here is more detailed information you might be interested in reading.

Oracle VirtualBox

Oracle VM VirtualBox: Networking options and how-to manage them. By: Simon Coter | Director of Product Management https://blogs.oracle.com/scoter/networking-in-virtualbox-v2

Guest Additions is an addon that is really important to install on your Vagrant box so you can interact with the machine and enable shared folders.

Check currently installed version of Guest Additions by logging into the machine and ls /opt will show you the version.

$ ls /opt/
VBoxGuestAdditions-5.2.8

NOTE: The installation of VirtualBox Guest Additions requires some basic packages to exist on the machine or it will fail to install. The installation script from the ISO requires which and tar to exist. Make sure these are installed on your machine. The error messages are otherwise not clear about this.

LXC

Install the Vagrant plugin that is an LXC provider.

How to enable X-Forwarding from Vagrant box?

If you want to run graphical applications from your Vagrant box and display them on your host machine (instead of running a GUI Vagrant box which uses more resources) then following the instructions here.

X-Forwarding from Vagrant Box

How do I run graphical programs remotely from a Linux server?

About the XQuartz software

How to create a Vagrant box from a VirtualBox VM?

For more information, follow this link

How to create a Vagrant base box from an existing box?

Below are the basic steps to create a new Vagrant box from an existing one. Why would you want to do this? For example, you could have a RHEL v7.4 box and you want to upgrade to 7.5 and create a permanent Vagrant box so you can simply reference that box for future use.

Below are the basic steps you can follow.

For more details see this link.

Login

vagrant ssh mybox 

Update

Update packages and perform any upgrades to your software.

# update is safer than upgrade; we may not want to delete obsolete packages
sudo yum -y update
#sudo yum -y upgrade

Provision

Perform any provisioning on the machine that you need.

Secure

Prepare the vagrant ssh key. Run these commands as vagrant user on the machine.

wget --no-check-certificate https://raw.githubusercontent.com/hashicorp/vagrant/master/keys/vagrant.pub -O .ssh/authorized_keys
chmod 700 .ssh
chmod 600 .ssh/authorized_keys
chown -R vagrant:vagrant .ssh

Compress

Make the box as small as possible.

# remove cached packages and header files
sudo yum clean all
# 
sudo dd if=/dev/zero of=/EMPTY bs=1M
sudo rm -f /EMPTY

Clean

Clear the bash history and exit

cat /dev/null > ~/.bash_history && history -c && exit

Repackage

Repackage the VM into a New Vagrant Box

vagrant package --output mynew.box

Register

Register the new box by adding it to current Vagrant boxes.

vagrant box add mynewbox mynew.box

Option 1: Keep the Vagrantfile

Add entry in the Vagrantfile (include this line to prevent inserting key)

config.ssh.insert_key = false

Option 2: Remove the Vagrantfile

vagrant destroy
rm Vagrantfile

Start

Start your new machine to verify everything has worked.

vagrant up mynew

Resources

This project contains a preconfigured Vagrant environment for running various systems in a single command:
Vagrant Sandbox

A curated list of awesome Vagrant resources, plugins, tutorials and other nice things.
Awesome Vagrant

Vagrant Listings - plugins, boxes, box configs, etc. Website

Good examples of using Vagrant to startup various software.