Vagrant Simplified

The Step-by-Step Process

I'm almost to the point where most Web tutorials start, which is to create a VM with Vagrant. Now that you know what Vagrant is doing, the process is far more interesting and less mysterious. Here is the step-by-step process:

1) Install VirtualBox and Vagrant:

On a Debian-based distro like Ubuntu, you simply type:

sudo apt-get install vagrant virtualbox

and allow the programs to be installed. There's no need to open VirtualBox, just have it installed.

2) Download a Box File:

This is how you populate the .vagrant.d folder in your home directory with a template or box file. To choose what box you want, head over to, and copy the URL of whatever base you want to start with. Lots of contributed boxes are available, so pick one that makes sense for you, and copy the URL to your clipboard. Then, to get the box to your local cache, type:

vagrant box add NAME

Note that NAME is just an arbitrary name that you pick to name your box. If you go with an Ubuntu 14.04 image, you could name it something like "trusty64" so you can reference it easily later. The command will download the box file and store it with whatever name you chose.

3) Create a Project Folder:

Somewhere on your system, create a folder for the VM. It truly can be anywhere. I usually make it on my desktop at first, so I easily can see it—basically:

mkdir ~/Desktop/myfirstvm

Then, switch into that folder:

cd ~/Desktop/myfirstvm

4) Initialize Your Vagrant Image:

Now you simply type:

vagrant init NAME

The vagrant program will create a Vagrantfile with a default configuration. Basically, it contains information on what box file to use when creating the VM. If you want to do advanced configuration on the Vagrantfile (I'll touch on that later), you can edit it, but by default, it will work with the file untouched.

5) Start Your VM:

The VM configuration file has been created in the myfirstvm folder, but the VM hasn't been created yet. In order to do that, type:

vagrant up

Note that you have to be inside the myfirstvm folder in order to have this work. Because you could have multiple folders with VMs (mysecondvm, for instance), the only way to tell Vagrant what VM you want to start is to be in the correct folder. Vagrant now will create a virtual machine based on the box file you downloaded earlier. The virtual hard drive and all configuration files will be stored in a folder called .vagrant inside the myfirstvm folder (refer back to Figure 1 for details). On the screen, you will see the computer starting, and once it's all set, you have a fully running VM.

6) Do Something with Your VM:

This was another stumbling point for me. I had a running VM, but how to interact with it? Thankfully, Vagrant offers a cool feature, namely SSH. Still inside that myfirstvm folder, type:

vagrant ssh

and you will be logged in via SSH to the running VM! Even though you don't know any passwords on the machine, you always can access it via the vagrant ssh command because Vagrant automatically creates a keypair that allows you to log in without entering a password. Once you're logged in, you can do whatever you want on the system, including changing passwords, installing software and so on.

7) Manipulate Your VM:

After you exit out of your VM, you'll drop back into your local machine inside the myfirstvm folder. The VM still is running, but you can do other things with Vagrant:

  • vagrant halt — shuts down the VM.

  • vagrant suspend — pauses the VM.

  • vagrant resume — resumes a paused VM.

  • vagrant destroy — erases the VM (not the Vagrantfile).

Where to Go from Here

I hope that makes the Vagrant workflow clear. If it seems simple enough, but not terribly useful, that's about all the basics will get you. Although it's cool to be able to create and destroy VMs so quickly, by itself, the process isn't very useful. Thankfully, Vagrant bakes in a few other awesome features. I already mentioned the vagrant ssh command that allows you to SSH in to the VM instantly, but that is only the tip of the iceberg.

First, you have the /vagrant folder inside the VM. This is a folder that is mounted automatically inside the running VM, and it points to the project folder itself on the main system. So any files you store in "myfirstvm" alongside the Vagrantfile will be accessible from inside the VM in the /vagrant folder. What makes that useful is that you can destroy the VM, create a new VM, and the files in your project folder won't be erased. That is convenient if you want to have persistent data that isn't destroyed when you do a vagrant destroy, but it's even more useful when you combine it with the scripting capability of the Vagrantfile itself.

Admittedly, it gets a little complicated, but the Vagrantfile can be edited using basic Ruby language to automate the creation and bootup of the VM. Here's a simple example of an edited Vagrantfile:

# Sample Vagrantfile with startup script
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| = "NAME"
config.vm.provision :shell, path: ""

The only line I added was the config.vm.provision line. The other lines were created automatically when I initially typed vagrant init. Basically, what the provision statement does is tell Vagrant that once it starts the VM to execute the script. Where does it find the file? In that shared space, namely the "myfirstvm" folder. So create a file in your myfirstvm folder alongside the Vagrantfile itself called

# This is the file called by Vagrantfile
apt-get update
apt-get install -y apache2

Make sure the file is executable:

chmod +x

Then, have Vagrant create a new VM. If you haven't "destroyed" the existing VM, do that, and then type vagrant up to create a new one. This time, you should see the machine get created and booted, but you also should see the system download and install Apache, because it executes the file on boot!

That Was the Light-Bulb Moment for Me

Once I understood how Vagrant can call a script when it creates the VM, I started to realize just how powerful and automated Vagrant can be. And truly, that's just scratching the surface of the things you can do with the Vagrantfile commands. Using that file, you can customize the settings of the VM itself (RAM, CPU and so on); you can create port-forward settings so you can access the Vagrant VM's ports by connecting to your local system's ports (that's actually how vagrant ssh works); and you can configure a VM fully by running a program like Chef when the VM is created.

Vagrant isn't the perfect tool for every job, but if you need a fast, highly configurable virtual machine that can be automated and scripted, it might be the right tool for you. Once I understood how Vagrant worked, it seemed much less like a magic button and much more like an awesome tool. And if you totally mess up your configuration files while you're experimenting? Just erase the files in your /home/user/.vagrant.d/ folder and start with a fresh project folder. All the configuration is done inside the Vagrantfile itself, and even that is created for you automatically when you type vagrant init.

If you want to learn more about the various advanced options Vagrant offers, check out its very nicely organized documentation site: At the very least, try the example I showed here. It's really cool to see how fast and automated Vagrant makes the entire virtualization experience.


Shawn is Associate Editor here at Linux Journal, and has been around Linux since the beginning. He has a passion for open source, and he loves to teach. He also drinks too much coffee, which often shows in his writing.