Despite its age and familiarity to most nowadays I couldn’t find a straight forward post on how to install and get started using Vagrant. So here’s my notes on doing so in blog post format. Be aware that this is well trodden ground and the Vagrant documentation on their website has a similar set of steps and content. The official site, if not this will get you where you need to be when it comes to getting started with Vagrant.
Our provider choice will be VirtualBox. The provider describes the software in charge of creating then managing the virtual machines comissioned by Vagrant. The two major providers are VirtualBox and VMware, VirtualBox is free and open source, whereas VMware is not.
On Ubuntu you would add this line to the bottom of your
deb http://download.virtualbox.org/virtualbox/debian xenial contrib
xenial for your own distributions release codename.
$ sudo vim /etc/apt/sources.list
You can find this codename if you don’t already know it by running this command; back on the prompt.
For Debian 8 (“Jessie”) and Ubuntu 16.04 (“Xenial”) or later distributions. Download and add the repositories PGP key.
wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -
Update the apt-get package database and install the
$ sudo apt-get update
VirtualBox is now installed and ready to use.
wget command and correct URL for downloading the latest version of Vagrant on Debian (at the time of writing this) - yours may differ.
$ wget https://releases.hashicorp.com/vagrant/2.1.1/vagrant_2.1.1_x86_64.deb ~
To then install the binary as a package on the system, use:
$ sudo dpkg -i vagrant_2.1.1_x86_64.deb
You can remove the Vagrant
.deb build file from your user’s home directory now, after it’s been installed.
Make a temporary test directory, and change into it, before continuing.
$ mkdir ~/vagrant-test && cd vagrant-test
To test the install, you can download and run a basic Vagrant box as a VM by running the next set of commands.
So we’re clear, here’s a good definition of a what a Vagrant “box” actually is:
“A package containing a representation of a virtual machine running a specific operating system. To be more simple, it is a base image of any Operating System or Kernel. It may be for a specific Provider.”
The box is the image, and from this image a virtual machine (VM) is created on the localhost.
The basic Vagrant configuration for this VM will be based in one file, the
This file is placed in the
~/vagrant-test directory via:
$ vagrant init ubuntu/xenial64
There are a wide variety of different box types (various OS images) listed on Hashi corp’s Atlas index.
After issuing the next command Vagrant will start to download the box and attempt to create and run a VM through VirtualBox.
$ vagrant up
Here’s an example of what the progress output looks like for this:
==> default: Box 'ubuntu/xenial64' could not be found. Attempting to find and install...
You can get an error message here relating to CPU architecture if you use a box that isn’t intended for your host’s operating system.
For example, the first image here requires a 64-bit host operating system, and then the second is for a 32-bit version. The “host” here refers to the machine you installed Vagrant on.
In my example we used the first box, a 64-bit system.
Also if you are running Vagrant itself in a virtual machine (using a hypervisor). Then you’ll need to ensure your hypervisor has “VT-x/AMD-V enabled”.
To enable this you’ll have to do something along the lines of:
- Power off the host virtual machine.
- Edit the individual virtual machine’s settings.
- Go to the CPU/processors section.
- Enable “VT-x/AMD-V” / “Virtualise Intel VR-x/EPT and AMD-V/RVI”
- Then power on the virtual machine again.
vagrant upin your Vagrant testing directory.
Here is what the setting looks like when using VMware Workstation as your hypervisor.
Once a box is installed and configured to run in a VM (like in step 2), you connect to the VM through an SSH tunnel created by Vagrant.
To connect to the newly running VM with Vagrant use:
$ vagrant ssh
The prompt now shows you are connected to your new VM!
exit or use
CTRL + D to leave the VM’s command line and return to your host.
These are the commands you’ll find yourself using when working with Vagrant. They use subsets of subcommands - which may seem confusing at first glance. The first is
box and has several susbets. Not all however have them.
List all the boxes you currently have installed on the host.
$ vagrant box list
Remove an already existing box from Vagrant.
$ vagrant box remove ubuntu/xenial64
Check updates for all box images on your system.
$ vagrant box update
Many of these commands can have the box named appended to them. In order to single them out.
The Vagrant documentation sums this command up pretty well:
“This command stops the running machine Vagrant is managing and destroys all resources that were created during the machine creation process. After running this command, your computer should be left at a clean state, as if you never created the guest machine in the first place.”
Use it to destroy your created virual machines e.g.
$ vagrant destroy ubuntu/xenial64
This command shuts down the running virtual machine Vagrant is currently managing; you can add a machine name/ID to target specific VM’s
$ vagrant halt
This is the same as a
vagrant halt but restarts the VM after halting - like with
$ vagrant reload
This allows you to list all the Vagrant guest ports that are mapped to the host ports.
$ vagrant port
Useful for displaying the output of the Vagrant host side SSH configuration file.
$ vagrant ssh-config
Should there ever be any SSH connection issues to a VM. The connection log can be seen by appending
--debug to the command.
$ vagrant ssh --debug
--debugflag can be added onto most Vagrant commands to see the internal operations being carried out.
Checking the status of the current Vagrant virtual machine is possible by entering:
$ vagrant status
A global version also exists.
$ vagrant global-status
--prune flag updates the cache for this - thereby removing any old, dead entries from the output.
$ vagrant global-status --prune
Looking back to the
Vagrantfile configuration. We can see that there are different options on offer to configure the resultant VM(s).
One to highlight is the VM name that is assigned to both the provider (VirtualBox) and internal Vagrant machine “name”.
This is the code to explicitly define it in both instances, if you ever want to:
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
Line 3 determines the
"name" listed when issuing:
Whilst line 5/6 ensures VirtualBox names and displays the VM properly in its GUI.
A nice addition to Vagrant is shell auto completion (Bash shell) for when typing in the above commands. An up to date (at the time of writing this) repo which provides this is located here:
This is a fork of Kura’s old repo; thanks go to him for maintaining this up until now. Here’s the provided “easiest” method of downloading this functionality to your Linux/Unix host system.
wget the script file in the above repo.
$ wget -q https://raw.github.com/brbsix/vagrant-bash-completion/master/vagrant-bash-completion/etc/bash_completion.d/vagrant
Add the newly downloaded file to the system Bash completion directory - whilst modifying the file’s permissions.
$ sudo install -m 0644 vagrant /etc/bash_completion.d/
Now either close and re-open your terminal, or
source in the new
/etc/bash_completion.d/vagrant bash completion file. To get the new auto-completion working.
Erika Heidi has recently revisited and updated her great in-depth book dedicated to Vagrant. For a full run down of Vagrant and how to add configuration management tools into the mix. I’d highly recommend this book.
There’s an accompanying blog post from February 2017 that she’s put together on recent Vagrant usage and trends. It’s quite short and worth reading if you’re interested.
The infographic (which I’ll leave here) is the main takeaway from the post:
Vagrant is a slightly ageing software in the sense that many prefer more recent tools like Docker. It does however still have its uses and is quite well adopted these days, so it’s more than worth understanding at least the basics.
Enjoy your time with Vagrant.
- Stack Overflow - Running Vagrant Inside VMWare VM – As mentioned in step 2.
- Stack Overflow - Vagrant ssh authentication failure – An issue that seems to occur with the official Vagrant Ubuntu images.
- Stack Overflow - How to change Vagrant ‘default’ machine name? – Complex but comprehensive thread for this.
- Stack Overflow - Removing list of vms in vagrant cache – For when the status output is not accurate/updating.
- “Warning: Authentication failure. Retrying…” – A very detailed long-term GitHub thread detailing the aforementioned issue.
Easily deploy an SSD cloud server on Digital Ocean in 55 seconds. Sign up using my link and receive $10.00 in free credit: https://www.digitalocean.com/?refcode=e91058dbfc7b
– Scarlz: @5car1z