Vagrant virtualization - introduction guide

Updated: September 26, 2015

If you thought your life was boring and you did not have enough virtualization software to play and tinker with, then you will be most pleased with today's content. A whole article dedicated to Vagrant, a wrapper software for virtualization deployment and testing.

The idea is as follows: you hide away the nitty gritty commands and present a unified interface, and then tie in some buzzwords like cloud and whatnot, and it becomes a hot new technology that everyone talks about. Pretty much like OpenStack, OpenShift, OpenCloud, and other fancy names. In fact, if you also manage to toss in more name droppers like PostgreSQL, Jenkins and Node.js, you win extra points for being modern and hip and cool. But all sarcasm aside, let's see what this tool can do, and if it's of any use, value and fun.

Get CoreOS

Words are very necessary

Just a bit of intro, to give you some context. Vagrant was originally designed to simplify software testing, development and management of virtualization resources in mixed, rapid environments. Initially, it could only work with VirtualBox, which is not exactly the choice hypervisor in the industry, but recently, the program also supports other technologies, like VMware, KVM and friends, and it does come with some nice integration tricks.

In a nutshell, the modus operandi is that you use vagrant commands rather than native commands. You may have multiple hypervisors, and they will all have different syntaxes, which can be sort of an overhead. This is why you use Vagrant, and hide the ugly stuff behind a layer of hopefully flexible abstraction. But enough with boring words, let's get practical and learn through our hands and feet.

Setting up

To make it more interesting, I'm NOT going to demonstrate this on Linux. Wait, w00t. We will use Windows, just to add a bit variety. In followup articles, and trust me, there will be many, we will go back to Linux, but here, I want to show you that conceptually, it really makes no difference.

Begin install

Then, being all excited and whatnot, open a Powershell window, and start typing some commands. For example, you may want to run Vagrant, and this is done by running:

vagrant up

However, if you have not prepared and initialized the work environment, you will get some rather ugly errors:

Up error

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe up
A Vagrant environment or target machine is required to run this
command. Run `vagrant init` to create a new Vagrant environment. Or, get an ID of a target machine from `vagrant global-status` to run this command on. A final option is to change to a directory with a Vagrantfile and to try again.

After you initialize the environment, you can start working in earnest.

Successful init

But again, we must contend with some ugly errors:

Base image missing

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Box 'base' could not be found. Attempting to find and install...
    default: Box Provider: virtualbox
    default: Box Version: >= 0
==> default: Adding box 'base' (v0) for provider: virtualbox
    default: Downloading: base
An error occurred while downloading the remote file. The error
message, if any, is reproduced below. Please fix this error and try again.

Couldn't open file /HashiCorp/Vagrant/bin/base
PS C:\HashiCorp\Vagrant\bin>

By default, the Windows version of Vagrant will try to start a virtual machine from a base image. That image will not be available, which is why the up command is going to fail when you run it without any preparations beforehand.

Therefore, the first thing is to pull some images. Much like Docker, Vagrant comes with its own online repository, where basic templates are stored. You can manually grab and install operating systems, but that's missing the point of the aforementioned abstraction. Let's grab an image, for example:

vagrant box add hashicorp/base

Get new box

If you specify a non-existent image, you will get more errors:

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe box add hashicorp/base
The box 'hashicorp/base' could not be found or could not be accessed in the remote catalog. If this is a private box on HashiCorp's Atlas, please verify you're logged in via `vagrant login`. Also, please double-check the name. The expanded
URL and error message are shown below:

URL: [""]
Error: The requested URL returned error: 404 Not Found

But you do expect the base image. There are various online references to why this problem happens, and it comes down to the default declaration in the configuration file. If you change it to one of the available images and download it, you will resolve the issue. Indeed, in the Vagrantfile, you will need to edit the default entry. Replace the string base with whatever you want to use as the default image when you start Vagrant. This can be Ubuntu, Fedora, CoreOS, or anything of that sort.

# Every Vagrant development environment requires a box. You can search for boxes at = "base"

For our exercise, and there's a very good future reason for this, we will test the somewhat less obvious choice of the CoreOS image (yungsang/coreos). Grab the image.

Get CoreOS

Downloading CoreOS

Verify that it has indeed been added to the catalog:

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe box list
ubuntu/trusty64 (virtualbox, 20150506.0.0)
yungsang/coreos (virtualbox, 1.3.8)

Then run Vagrant again. CoreOS will start, including user and network setup, and a few other details. After a while, the system will be running. You can now try to connect to the host using SSH. By default, each running instance will be assigned a port on the localhost. In our case, the SSH service for our box is running on port 2222 on This is very similar to what we've seen with Docker. Again, the repo concept, the networking, very much identical. Hint, there's a good reason for this.

Bringing CoreOS up

CoreOS, booting

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'yungsang/coreos'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'yungsang/coreos' is up to date...
==> default: Setting the name of the VM: bin_default_1431611566870_38538
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
    default: Adapter 1: nat
==> default: Forwarding ports...
    default: 22 => 2222 (adapter 1)
==> default: Running 'pre-boot' VM customizations...
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address:
    default: SSH username: core
    default: SSH auth method: private key
    default: Warning: Connection timeout. Retrying...
==> default: Machine booted and ready!

Connect to the virtual machine

Our virtual machine is running. Great. You can check with vagrant status:


You can use the vagrant ssh or vagrant rdp wrapper command to step into the running virtual machine. There are other, more advanced ways to do this, but we will discuss that in a followup tutorial, which focuses on networking and clusters.

For Windows clients, you can use RDP, but this won't work in our case, because RDP is not available inside CoreOS. I am not sure if VNC is an option, but that's something I have to test yet. Similarly, SSH poses a problem, because Windows does not ship with a default SSH agent, and if you do have PuTTY installed, it might not be in the path.

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe rdp default
==> default: Detecting RDP info...
RDP connection information for this machine could not be
detected. This is typically caused when we can't find the IP
or port to connect to for RDP. Please verify you're forwarding
an RDP port and that your machine is accessible.

PS C:\HashiCorp\Vagrant\bin> .\vagrant.exe ssh default -- -A
`ssh` executable not found in any directories in the %PATH% variable. Is an SSH client installed? Try installing Cygwin, MinGW or Git, all of which contain an SSH client. Or use your favorite SSH client with the following authentication information shown below:

Port: 2222
Username: core
Private key: C:/Users/<user>/.vagrant.d/insecure_private_key

Then, you will also need, if you're working on Windows, to convert the OpenSSH key into PuTTY format or similar. Again, not something most people will ever encounter in their Vagrant adventures, but it's useful to see similar problems tackled in many different ways.

SSH works

CoreOS running

At this point, we've successfully launched our first Vagrant VM instance, using VirtualBox as the provider, but that's something that we've not encountered anywhere during our testing. Well, sort of. But we did not need to use any explicit VirtualBox commands, or worry about XML files and whatnot. This is just the beginning, but it's also the end of our tutorial for today. We conclude on a high note.

More reading

Should you fancy a bit of text:

Introducing Vagrant, a Linux Journal article

Crash course on Vagrant

Docker networking thingie


Vagrant seems like an interesting concept, although it may not be the best way to solve challenges in your environment. If you want to really master virtualization, and you need to control every fact of your setup, then you need to invest the necessary time, blood and patience in learning everything bottom up. Because otherwise, you won't really be able to solve any issues when they come up, and they will, or understand the technology.

But it's an interesting spin, and we shall yet see how far we can take Vagrant on our virtual journey. Well, at the very least, we handled the program setup issues and the initial configuration, we learned how to pull images and start them, did some basic checks, and worked around network connectivity. Quite useful. More to come, for sure, including the very important plugins framework, which extends the connectivity piece for VMware, LXC, libvirt, plus advanced networking, cluster setups, and whatnot. Stay tuned for updates.


You may also like: