Vagrant VM Manager

Vagrant cheatsheet — manage reproducible VM environments. vagrant up, vagrant ssh, vagrant halt, vagrant destroy, vagrant provision. Define everything in a Vagrantfile.

8 min read

What it is

Vagrant is a tool for building and managing virtual machine environments in a single workflow. You reach for Vagrant when you need reproducible development environments that are isolated from your host system.

Installation

Linux

sudo apt update
sudo apt install vagrant
# or for Fedora/CentOS/RHEL
sudo dnf install vagrant
# or for Arch Linux
sudo pacman -S vagrant

macOS

Download the .dmg file from the Vagrant website (https://www.vagrantup.com/downloads) and drag the Vagrant application to your Applications folder.

Windows

Download the .msi installer from the Vagrant website (https://www.vagrantup.com/downloads) and run it.

Note: Vagrant requires a virtualization provider like VirtualBox, VMware, or Hyper-V to be installed and configured on your system. VirtualBox is the default and most common choice.

Core Concepts

Box: A Vagrant "box" is a pre-packaged base image for a virtual machine. It’s like a template that Vagrant uses to create new VMs. Boxes can be downloaded from the Vagrant Cloud or created by users.
Vagrantfile: This is a Ruby file that defines your Vagrant environment. It specifies the box to use, network configurations, shared folders, provisioning steps, and more.
Provider: The underlying virtualization software (e.g., VirtualBox, VMware, Hyper-V) that Vagrant uses to run the virtual machine.
Provisioning: The process of automatically installing software, configuring services, and setting up the guest machine after it’s created. Vagrant supports shell scripts, Ansible, Chef, Puppet, and more for provisioning.
Guest Machine: The actual virtual machine running the operating system defined by the box.

Commands / Usage

Environment Initialization

vagrant init <box_name> Initializes a new Vagrant environment in the current directory. It creates a Vagrantfile using the specified base box.
```
vagrant init ubuntu/focal64
```
Creates a Vagrantfile configured to use the ubuntu/focal64 box from Vagrant Cloud.
vagrant init <box_name> -m Initializes a new Vagrant environment with a minimal Vagrantfile.
```
vagrant init generic/ubuntu2004 --minimal
```
Creates a Vagrantfile with only the essential configuration.

Machine Management

vagrant up Starts and provisions the Vagrant environment. If the machine doesn’t exist, it will be created.
```
vagrant up
```
Starts the VM defined in the current directory’s Vagrantfile.
vagrant up <machine-name> Starts a specific machine in a multi-machine environment.
```
vagrant up webserver
```
Starts only the machine named webserver.
vagrant halt Shuts down the Vagrant machine gracefully.
```
vagrant halt
```
Shuts down the VM.
vagrant suspend Saves the current state of the machine to disk, allowing for a very fast resume.
```
vagrant suspend
```
Suspends the VM, saving its current state.
vagrant resume Restores a suspended machine to its previous state.
```
vagrant resume
```
Resumes a suspended VM.
vagrant reload Reboots the Vagrant machine. If the Vagrantfile has changed, it will reload the configuration and re-provision.
```
vagrant reload
```
Reboots the VM and reloads the configuration.
vagrant reload --provision Reboots the Vagrant machine and forces re-provisioning.
```
vagrant reload --provision
```
Reboots the VM and runs all provisioners again.
vagrant destroy Stops and deletes the Vagrant machine, removing all associated files.
```
vagrant destroy
```
Stops and removes the VM.
vagrant destroy -f Stops and deletes the Vagrant machine without prompting for confirmation.
```
vagrant destroy -f
```
Forcefully stops and removes the VM.
vagrant status Shows the current status of the Vagrant machines.
```
vagrant status
```
Displays the current state (running, stopped, etc.) of the VM.
vagrant global-status Shows the status of all Vagrant environments on your system.
```
vagrant global-status
```
Lists all Vagrant projects and their statuses.

SSH and Access

vagrant ssh Connects to the Vagrant machine via SSH.
```
vagrant ssh
```
Opens an SSH session to the VM.
vagrant ssh -c "command" Executes a command on the Vagrant machine via SSH without opening an interactive session.
```
vagrant ssh -c "sudo apt update && sudo apt install -y nginx"
```
Updates package lists and installs Nginx on the VM.
vagrant ssh-config Outputs SSH configuration details for connecting to the machine.
```
vagrant ssh-config
```
Prints host, port, user, and identity file for SSH connection.

Box Management

vagrant box list Lists all the Vagrant boxes currently installed on your system.
```
vagrant box list
```
Shows all downloaded Vagrant base images.
vagrant box add <box_name> <box_url> Adds a new Vagrant box to your local machine.
```
vagrant box add ubuntu/focal64 https://app.vagrantup.com/ubuntu/focal64/0/virtualbox.box
```
Downloads and adds the specified Ubuntu 20.04 box for VirtualBox.
vagrant box remove <box_name> Removes a Vagrant box from your local machine.
```
vagrant box remove ubuntu/focal64
```
Removes the ubuntu/focal64 box.
vagrant box update Checks for updates for all installed boxes.
```
vagrant box update
```
Checks for newer versions of your installed Vagrant boxes.

Provisioning

vagrant provision Runs the provisioners defined in the Vagrantfile on an already running machine.
```
vagrant provision
```
Executes the provisioning steps defined in the Vagrantfile.
vagrant provision --provision-with <provisioner_name> Runs only a specific provisioner (e.g., shell, ansible).
```
vagrant provision --provision-with shell
```
Runs only the shell provisioners.

Plugins

vagrant plugin list Lists all installed Vagrant plugins.
```
vagrant plugin list
```
Shows currently installed Vagrant plugins.
vagrant plugin install <plugin_name> Installs a new Vagrant plugin.
```
vagrant plugin install vagrant-vbguest
```
Installs the vagrant-vbguest plugin, which helps keep VirtualBox Guest Additions up-to-date.
vagrant plugin uninstall <plugin_name> Uninstalls a Vagrant plugin.
```
vagrant plugin uninstall vagrant-vbguest
```
Uninstalls the vagrant-vbguest plugin.

Networking

vagrant port Lists the port forwarding information for the Vagrant machine.
```
vagrant port
```
Shows which host ports are forwarded to which guest ports.

Multi-Machine Environments

vagrant up <machine-name> Starts a specific machine in a multi-machine environment.
```
vagrant up database
```
Starts only the database machine.
vagrant ssh <machine-name> Connects to a specific machine in a multi-machine environment.
```
vagrant ssh webserver
```
Opens an SSH session to the webserver machine.
vagrant halt <machine-name> Shuts down a specific machine in a multi-machine environment.
```
vagrant halt app_server
```
Shuts down the app_server machine.
vagrant destroy <machine-name> Stops and deletes a specific machine in a multi-machine environment.
```
vagrant destroy worker_node -f
```
Forcefully destroys the worker_node machine.

Common Patterns

Setting up a web server with Nginx: Create a Vagrantfile with a basic Ubuntu box and add a shell provisioner to install and configure Nginx.

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/focal64"

  config.vm.network "forwarded_port", guest: 80, host: 8080

  config.vm.provision "shell", inline: <<-SHELL
    sudo apt update
    sudo apt install -y nginx
    sudo systemctl start nginx
    sudo systemctl enable nginx
  SHELL
end

Then run:

vagrant up

Access Nginx at http://localhost:8080.

Sharing your project directory: By default, Vagrant shares your project directory (where the Vagrantfile is) to /vagrant inside the guest machine. You can customize this.
```
# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/focal64"
  config.vm.synced_folder "./app", "/var/www/html"
end
```
This shares the local ./app directory to /var/www/html on the guest.

Using multiple machines: Define multiple VMs in a single Vagrantfile.

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.define "web" do |web|
    web.vm.box = "ubuntu/focal64"
    web.vm.network "private_network", ip: "192.168.33.10"
  end

  config.vm.define "db" do |db|
    db.vm.box = "ubuntu/focal64"
    db.vm.network "private_network", ip: "192.168.33.11"
  end
end

Then manage them individually:

vagrant up web
vagrant ssh db
vagrant halt web

Running a Docker container on a Vagrant VM: Provision a Vagrant VM to install Docker and run a container.

# Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/focal64"
  config.vm.network "forwarded_port", guest: 80, host: 8080

  config.vm.provision "shell", inline: <<-SHELL
    sudo apt update
    sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
    sudo apt update
    sudo apt install -y docker-ce
    sudo usermod -aG docker vagrant # Add vagrant user to docker group
  SHELL
end

After vagrant up, SSH into the VM and run Docker commands:

vagrant ssh
sudo docker run -d -p 80:80 nginx
exit

Access Nginx at http://localhost:8080.

Using Vagrant Cloud for boxes: Search for boxes on https://app.vagrantup.com/boxes/search and use their names (e.g., hashicorp/bionic64, centos/7).
```
vagrant init hashicorp/bionic64
vagrant up
```

Gotchas

Provider Compatibility: Ensure the box you download is compatible with your installed virtualization provider (VirtualBox, VMware, etc.). Boxes are often specific to a provider.
Synced Folder Performance: Default synced folders (especially on macOS and Windows) can be slow due to filesystem synchronization overhead. Consider using NFS for Linux guests or synced_folder options like rsync for better performance.
Guest Additions/VMware Tools: For optimal performance and features (like seamless mouse integration, shared clipboard, better resolution), ensure the appropriate guest additions (VirtualBox) or VMware Tools are installed and up-to-date on the guest. The vagrant-vbguest plugin helps with this for VirtualBox.
Port Conflicts: If you try to forward a host port that is already in use, vagrant up will fail. Check vagrant port to see existing forwards and choose available host ports.
Vagrantfile Syntax: The Vagrantfile is a Ruby file. Syntax errors will prevent Vagrant from starting your environment.
vagrant destroy is Permanent: vagrant destroy removes the VM and all its data. If you need to preserve data, ensure it’s in a synced folder or managed externally.
Provisioner Idempotency: Ensure your provisioners are idempotent – meaning running them multiple times has the same effect as running them once. This is crucial for vagrant reload --provision and vagrant provision.
Network Configuration: Be mindful of the network types (private_network, public_network, forwarded_port). private_network creates a host-only network, useful for host-guest communication without exposing the VM to the external network. forwarded_port maps a port on the host to a port on the guest.