Vagrant

Author Svea Anijago, TS 66, 08.05.2015

Vagrant is a command line utility that runs the virtual machine without a UI. It is used to manage virtual machines life cycle and to build complete development environments. It is a liberally licensed open source project that is written in Ruby and can also be used with other programming languages (Java, C#, Python, PHP, JavaScript). It was created in January 2010 by Mitchell Hasimoto, who in November 2012 founded HashiCorp to back up Vagrant development full time.

In Vagrant, virtual machines are provisioned on top of VirtualBox, VMware, KVM, AWS, LXC. To automatically install and configure software on machines, provisioning tools like shell scripts, Chef, Salt, Puppet or Ansible can be used. From 1.6, Vagrant natively supports Docker containers, which in some cases can serve as a substitute for a fully virtualized operating system. [1] [2]

Background

Vagrantfile [3] is a very flexible configuration format. It marks the root directory of the project and describes the machine and resources needed to run the project and what software needs to be installed and how to access it. The syntax used in Vagrantfiles is Ruby. One Vagrantfile per project is used and it is supposed to be committed to version control to allow other developers involved in the project to check out the code. The package format for Vagrant environments are boxes [4] that can be used on any platform that Vagrant supports. Vagrant uses these base images to clone a virtual machine. As a multi-machine environment, Vagrant is able to define and control multiple guest machines per Vagrantfile. The machines work together or are associated with each other.

Backwards compatibility

Full backwards compatibility[5] is provided by Vagrant 1.1+ for Vagrant 1.0.x Vagrantfiles that do not use plugins. Backwards compatibility for 1.x is not guaranteed and syntax stability is not certain before 2.0 which is to have stable backwards compatible Vagrantfile format.

Installing

Vagrants latest versions for Mac OS X, Windows, Debian and Centos can be installed by using installation package from their homepage. There is also possibility to get older version from Vagrants releases services. It will isolate dependencies and their configurations in a single consistent environment. Using single Vagrantfile the whole working environment is installed and configured. [6]

To have a fully functioning virtual machine in VirtualBox running Ubuntu 12.04 LTS 64-bit, following two commands need to be used to place a Vagrantfile to users directory and install virtual environment:

vagrant init hashicorp/precise64

vagrant up

hashicorp/precise64 downloads a box named "hashicorp/precise64" from HashiCorp's Atlas box catalog that stores all the host boxes. Boxes can be downloaded from HashiCorp's Atlas or added from a local file, custom URL or other. They are named using username e.g “hashicorp” and box name “precise64” that are separated with slash. Box names can be also specified with URL or local file paths.

Accessing virtual machine is done with SSH session and user is located in /home/vagrant

vagrant ssh

Synced Folders

Using synced folders [7], files are automatically synced with the guest machine. By default the project directory in Vagrantfile is shared to /vagrant directory on guest machine, that is different than the /home/vagrant where user is located when using vagrant ssh

Command-line interface

All available subcommands[8] are displayed to user running vagrant command

• Box

vagrant box is used to manage boxes with sub-commands:add, list, remove, update, outdated, repackage. So that multiple Vagrant environments could use a box, it needs to be added to Vagrant and then stored under specific name with command: vagrant box add Current users boxes are stored globally and projects only use the box as an initial image to clone from but do not modify the actual base image, so that using same hashicorp/precise64 box and adding files on one project does not affect others.

• Connect

vagrant connect is used to enable access to shared environments and complements the vagrant share command.

• Destroy

vagrant destroy command stops the running virtual machine and destroys all resources created during machine creation process.

• Global-status

vagrant global-status tells the state of all active Vagrant environments in the system for current logged in user.

• Halt

vagrant halt shuts down the currently running machine that is managed by Vagrant. At first it is attempted to shut the machine down by running guest OS shutdown mechanism, if this is not successful the -- force flag is stated and the machine is shut off.

• Init

vagrant init [box-name] [box-url] initializes current directory to be a Vagrant environment by creating and initial Vagrantfile if it doesn’t already exist. The first argument will prepopulate the config.vm.box and second argument config.vm.box_url setting in the created Vagrantfile.

• Login

vagrant login command is used to authenticate with the HashiCorp’s Atlas server. If user is not accessing protected boxes or using Vagrant Share, no login is needed.

• Package

vagrant package command packages currently running VirtualBox environment into a re-usable box. This can be used with other providers based on the providers implementation and if they support it.

• Plugin

vagrant plugin is used to manage plugins along with subcommands: install, license, list, update, uninstall.

Installing a plugin from a known gem source with given name, usually from RubyGems: vagrant plugin install new-plugin

Installing a plugin from a local file source: vagrant plugin install /path/to/new-plugin.gem

• Port

vagrant port displays full list of guest ports mapped to the host machine ports. If multi-machine Vagrantfile is used, name of the machine must be specified with vagrant port my-machine

• Powershell

vagrant powershell opens a PowerShell prompt into a running Vagrant machine and will only work if the machine supports PowerShell.

• Provision

vagrant provision runs configured provisioners against the running Vagrant managed machine.

• RDP

vagrant rdp starts RDP client for a remote desktop session with the guest. Typically only Windows Vagrant environments support remote desktop. Raw arguments are passed through to RDP client by appending it after a --: vagrant rdp -- /span that on Windows will execute mstsc.exe /span config.rdp allowing RDP to span on multiple desktops.

• Reload

vagrant reload is the equivalent of running vagrant halt followed by vagrant up commands. This is usually required for the changes made in the Vagrantfile to take effect. vagrant reload is needed after making modifications to the Vagrantfile.

• Resume

vagrant resume resumes a Vagrant machine that has been suspended with vagrant suspend command.

• Share

vagrant share command loads the Vagrant Share session so that users Vagrant environment can be shared with anyone to enable collaboration directly in users Vagrant environment.

• Snapshot

vagrant snapshot is used to manage snapshots with guest machine and are recorded a point-in-time state. This is not provided by every provider. Snapshot sub-commands include push, pop, save, restore, list, delete.

• SSH

vagrant ssh will SSH into a running Vagrant machine and give user access to a shell. An argument after -- in command line is passed directly to ssh executable. That allows for example reverse tunneling down into the ssh program. If command runs in the background, it will be terminated almost immediately since when Vagrant executes the command, it is executed within the context of a shell. If shell is exited, all child processes also exit. To prevent this, process needs to be detached from shell.

• SSH-config

vagrant ssh-config will output valid configuration for an SSH config file to SSH into the running Vagrant machine from ssh directly.

• Status

vagrant status will tell the state of the machines Vagrant is managing.

• Suspend

vagrant suspend suspends the guest machine rather than doing a full boot and saves the exact point-in-time state of the machine. This mostly requires extra disk space storing all the contents of RAM in guest machine not host machine or CPU cycles while it is in suspended.

• Up

vagrant up is the most important command in Vagrants since it creates and configures guest machine as specified in Vagrantfile.

• Version

vagrant version displays the version of Vagrant that is installed and the latest version of Vagrant that is currently available,for this a network call must be made. vagrant -- version is for checking only the latest version installed.

Vagrant share

vagrant share has three primary modes or features that are not mutually exclusive:

• HTTP sharing creates a publicly accessible URL endpoint to access HTTP server running in Vagrant environment. It is enabled by default when vagrant share is used. Accessing party does not need to have Vagrant installed in order to view. [9]

Using HTTP sharing

• SSH sharing allows instant SSH access to used Vagrant environment by anyone by running vagrant connect --ssh on the remote side.[10] By default SSH sharing is disabled as a security measure. To enable SSH sharing, supply the --ssh flag when calling vagrant share. If SSH sharing is enabled, a brand new key pair for SSH access is generated. Public key portion is automatically inserted to Vagrant machine and private key portion is uploaded to server managing the Vagrant shares. Private key is encrypted using a password that user will be prompted for and that is never transmitted across the network by Vagrant.

When running vagrant share --ssh it will output the name of the share:

Using SSH sharing

After that, anyone can SSH directly to named Vagrant environment by running vagrant connect --ssh NAME where NAME is the name of the previously share output.

Accessing someones Vagrant envionment with SSH in terminal

The default behavior is that the private key is encrypted, the connecting person will be prompted for the password to decrypt the private key.

• General sharing allows anyone to access any exposed port of Vagrant environment by running vagrant connect on the remote side.

Provisioning

Provisioners in Vagrant are for automatical software install anf configuration altering. Each provisioner is configured within Vagrantfile using config.vm.provision method call

Vagrant.configure("2") do |config|
  # ... other configuration

  config.vm.provision "shell", inline: "echo hello"
end

Each provisioner has a type that is used as the first parameter, then follows basic key/value for configuring that specific provisioner. Instead Ruby block for a syntax can also be used.[11]

See Also

• Vagrant Homepage
• Using Vagrant and Ansible
• Starting with Vagrant on Ubuntu 14.10 - A Beginner's Guide

References

1. Mitchell Hashimoto (2014-05-06). "Vagrant 1.6". Retrieved 2016-04-29.
2. "Introducing Vagrant". Linux Journal. 14 November 2012. Retrieved 2016-05-06.
3. Vagrantfile. Vagrant Documentation. Retrieved 2016-05-06.
4. Boxes. Vagrant Documentation. Retrieved 2016-05-06.
5. Backwards Compatibility Vagrant Documentation. Retrieved 2016-05-04.
6. Project Setup. Vagrant Documentation. Retrieved 2016-02-29.
7. Synced Folders. Vagrant Documentation. Retrieved 2016-04-27.
8. Command-line Interface. Vagrant Documentation. Retrieved 2016-05-05.
9. HTTP Sharing. Vagrant Documentation. Retrieved 2016-05-06.
10. SSH Sharing. Vagrant Documentation. Retrieved 2016-05-08.
11. Provisioning. Vagrant Documentation. Retrieved 2016-05-08.