Vagrant is one of the developer tools when working with KVM. It enables developers and system administrators to quickly build and manage virtual machine environments in a single workflow. It focuses on automation to lower the time required to bring up your development environment, while ensuring it’s portable, reproducible and disposable.

Vagrant by default support VirtualBox, Hyper-V, and Docker. However, alternative providers can be installed to support other virtualization platforms such as KVM and VMware.

In this section we discuss how you can utilize existing KVM hypervisor to run vagrant boxes and have isolated virtualized environments. But before another provider can be used, it must be installed. These vagtant providers are installed via the Vagrant plugin system.

To have a working vagrant setup with libvirt, the vagrant-libvirt has to be installed configured. Of course Vagrant is the main dependency that we must install before the plugin.

Installation of Vagrant

Vagrant has to be installed as the first dependency. This can be done from an upstream repository or from official binary files.

• Install on Debian / Ubuntu:

wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vagrant
vagrant --version

• Install on RHEL / Rocky / AlmaLinux / CentOS:

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum -y install vagrant
vagrant --version

• Install on Fedora:

sudo dnf install -y dnf-plugins-core
sudo dnf config-manager addrepo --from-repofile=https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
sudo dnf -y install vagrant
vagrant --version

• Install on Amazon Linux:

sudo yum install -y yum-utils shadow-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
sudo yum -y install vagrant
vagrant --version

• Install on SUSE / openSUSE:

VER=$(curl -s https://api.github.com/repos/hashicorp/vagrant/releases/latest|grep tag_name|cut -d '"' -f 4|sed 's/v//')
wget https://releases.hashicorp.com/vagrant/${VER}/vagrant-${VER}-1.x86_64.rpm
sudo zypper in vagrant-${VER}-1.x86_64.rpm

To know if the installation succeeded, check the version of vagrant installed.

vagrant --version

To see all commonly used vagrant command options:

vagrant --help

To get help page on any individual command run:

vagrant <command> -h
# Example
vagrant box -h

Installation of Vagrant-libvirt plugin

Vagrant-libvirt is plugin for Vagrant that adds a Libvirt provider to Vagrant, allowing Vagrant to control and provision machines via Libvirt toolkit.

The installation of vagrant-libvirt has the following dependencies:

• Vagrant
• Libvirt (and QEMU) – Refer to the chapter on KVM installation
• GCC and Make

Confirm KVM is functional in your system

systemctl status libvirtd

If not running, follow our installation chapter for a detailed how-to.

Add your user to the libvirt group:

sudo usermod -aG libvirt $(whoami)
newgrp libvirt

Install on Ubuntu / Debian

Remove distro provided vagrant-libvirt plugin if installed since it could be oldest version.

sudo apt purge vagrant-libvirt
sudo apt hold vagrant-libvirt

Next install dependencies required

sudo apt update
sudo apt install -y build-essential libvirt-daemon-system \
  ebtables libguestfs-tools ruby-fog-libvirt libvirt-dev ruby-dev

Install dependencies required, then libvirt vagrant plugin by running the following commands.

sudo gem install nokogiri
vagrant plugin install pkg-config vagrant-libvirt vagrant-mutate

Confirm the installation was successful by checking the list of installed plugins:

vagrant plugin list

Install on Rocky / AlmaLinux

Begin with the installation of dependencies:

• Rocky / AlmaLinux / CentOS Stream 9:

sudo dnf config-manager --set-enabled crb
sudo yum -y install ruby libvirt-devel
sudo yum -y groupinstall "Development Tools"

• Rocky / AlmaLinux 8

sudo dnf config-manager --set-enabled powertools
sudo yum -y install ruby libvirt-devel
sudo yum -y groupinstall "Development Tools"

Install libvirt vagrant plugin

sudo gem install nokogiri
vagrant plugin install pkg-config vagrant-libvirt vagrant-mutate

Confirm the installation was successful by checking the list of installed plugins:

vagrant plugin list

If your installation succeeded, there should be vagrant-libvirt in output:

pkg-config (1.5.9, global)
vagrant-libvirt (0.12.2, global)

Install on openSUSE

Get the latest stable release version number of vagrant:

VER=$(curl -s https://api.github.com/repos/hashicorp/vagrant/releases/latest|grep tag_name|cut -d '"' -f 4|sed 's/v//')

Pull the rpm package from vagrant binary downloads page.

wget https://releases.hashicorp.com/vagrant/${VER}/vagrant-${VER}-1.x86_64.rpm

Install downloaded package using zypper command line utility.

sudo zypper install --allow-unsigned-rpm --no-confirm vagrant-${VER}-1.x86_64.rpm

Here’s our next guide on creating VMs with Vagrant on KVM.

• Running Virtual Machines with Vagrant on KVM

Vagrant management commands with examples

This section highlights commonly used vagrant commands to help you work more efficiently with Vagrant and Libvirt.

Print vagrant version

Print the current version of installed vagrant

vagrant version

Manage vagrant boxes

Download vagrant box

vagrant box add --provider libvirt <box-name-or-url>

List downloaded boxes

vagrant box list

Delete vagrant box

vagrant box remove <box>

Prune older boxes

vagrant box prune

Update a specific box

# Inf Vagrantfile
vagrant box update

# Named box
vagrant box update --box <box>

Repackage box

vagrant box repackage <name> <provider> <version>

Validate Vagrantfile

Validate the configurations in your Vagrantfile by running:

vagrant validate

Start / provision vagrant machine

Start and provision the vagrant environment

vagrant up

To provision the vagrant machine use

vagrant provision

Display information about machines

Display information about all known Vagrant environments on the machine

vagrant global-status

Connect to machine via SSH

To connect to a single instance machine defined in a Vagrantfile

vagrant ssh

If there are multiple machines, specify the name

vagrant ssh <name|id>

It’s also possible to output OpenSSH valid configuration to connect to the machine

vagrant ssh-config

Suspend vagrant machine

A vagrant machine can be suspended by executing the command:

vagrant suspend

Restart vagrant machine

Restart a vagrant machine and load new Vagrantfile configuration

vagrant reload

Resume suspended machine

To resume a suspended vagrant machine, run:

vagrant resume

Stopping Vagrant machine(s)

vagrant halt

VM snapshots management

Create a VM snapshot

vagrant snapshot save <vm-name> <snapshot-name>

List snapshots

vagrant snapshot list <vm-name>

Restore snapshot

vagrant snapshot restore <vm-name> <snapshot>

Delete snapshot

vagrant snapshot delete <vm-name> <snapshot>

• Destroy vagrant machine(s)

vagrant destroy

Agree to destroy the VM using y key:

    ubuntu24: Are you sure you want to destroy the 'ubuntu24' VM? [y/N] y
==> ubuntu24: Removing domain...
==> ubuntu24: Deleting the machine folder

• Remove vagrant boxe(s)

vagrant box remove <box-name>

• Stop and delete all traces of the vagrant machine

# Gracefully
vagrant destroy --graceful <name>

# Forcefully
vagrant destroy --force <name>