Vagrant is an application that manages virtualized environments (boxes) allowing to control the creation and provisionning of virtual machines, which may share some resources (folders) with the host.

Vagrant supports different virtualization engines (providers), among which VirtualBox is historically the most popular.

Installation

Installation with libvirt

Libvirt is a good provider for Vagrant because it's faster than VirtualBox and it's in the main repository. Install it as follow:

sudo apt install vagrant-libvirt libvirt-daemon-system

Ensure your user is a member of the libvirt group (this is needed to manage libvirt via the qemu:///system uri, which is the default for vagrant-libvirt)

sudo usermod --append --groups libvirt $USER

logout and login so that your group membership applies

# should return libvirt
groups | grep -o libvirt

start your first vagrant environment

vagrant init debian/buster64
vagrant up --provider=libvirt
vagrant ssh

Debian Vagrant base box

There is an ongoing effort to provide Teams/Cloud/VagrantBaseBoxes for Vagrant's cloud backend.

Creating Debian vagrant boxes

You also may wish to create your own Debian boxes, Debian currently uses fai-diskimage to build the boxes hosted on the Vagrant cloud.

Troubleshooting

On vagrant up various errors can happen:

Vagrant from Debian 11 or previous versions hang on "default: Waiting for SSH to become available..."

This is caused by a bug in Vagrant in the handling of ssh-rsa keys: Vagrant always try to connect to the VM using SHA-1 algorithm, although this algorithm has been removed from OpenSSH. A workaround is to install the Vagrant version from testing / Debian 12, see that comment in the Debian Bug Tracker System

Errors on NFS mount on Debian 8 and 9 boxes

During the vagrant up process you can get this error on Debian 8 as well as in Debian 9:

The following SSH command responded with a non-zero exit status.
Vagrant assumes that this means the command failed!

mount -o vers=4 192.168.121.1:/home/jhon/projects/foo /vagrant
result=$?
if test $result -eq 0; then
if test -x /sbin/initctl && command -v /sbin/init && /sbin/init 2>/dev/null --version | grep upstart; then
/sbin/initctl emit --no-wait vagrant-mounted MOUNTPOINT=/vagrant
fi
else
exit $result
fi

Stdout from the command:

Stderr from the command:

mount.nfs: access denied by server while mounting 192.168.121.1:/home/jhon/projects/foo

First of all ensure that your NFS daemon is running:

sudo systemctl status nfs-common
sudo systemctl status nfs-kernel-server

Then copy from the above error the mount command and try running it on yourself, but downgrading the NFS version (the vers):

vagrant ssh
sudo mount -o vers=3 192.168.121.1:/home/jhon/projects/foo /vagrant

If it works manually, than you can fix it adding this line into your Vagrantfile:

config.vm.synced_folder ".", "/vagrant", nfs_version: "3"

Hang on "Waiting for domain to get an IP address..."

If vagrant seems to hang forever on this step:

Waiting for domain to get an IP address...

it might be worth killing that process (with control-c), then destroying the VM and starting again:

vagrant destroy
vagrant up

It's unclear why, but sometimes this process doesn't succesfully complete in libvirt. It might be worth starting virt-manager to confirm the VM is running.

Failure to start on NFS

If you get this error message:

It appears your machine doesn't support NFS, or there is not an
adapter to enable NFS on this machine for Vagrant. Please verify
that `nfsd` is installed on your machine, and try again. If you're
on Windows, NFS isn't supported. If the problem persists, please
contact Vagrant support.

It's possible (and understandable) you haven't setup NFS (or haven't set it up correctly). A fairly simple workaround is to use *another* folder sharing plugin. There are multiple synced folder mechanisms in Vagrant. Unfortunately, changing the plugin requires you to edit the Vagrantfile (as opposed to just using a commandline argument). To switch to rsync, for example, you can simply use:

  config.vm.synced_folder ".", "/vagrant", type: "rsync"

in your Vagrantfile. Note that this will not reflect changes in realtime between the VM and the host until you run the vagrant rsync command. The vagrant rsync-auto command can also do that in the background.

You can also use the "9p" (and virtiofs) module with:

config.vm.synced_folder './', '/vagrant', type: '9p', disabled: false, accessmode: "squash", owner: "1000"

See also the libvirt synced folders documentation.