Skip to content


Niklas Baumstark edited this page Jan 26, 2015 · 4 revisions

System Requirement

Arch Linux

  • 64-bit OS is recommended
  • Keep it up-to-date. Here are the package versions most recently tested for vagrant-kvm:
    • core/linux 3.14-4
    • extra/qemu 1.7.0-2
    • community/libvirt 1.2.3-3
    • core/bridge-utils 1.5-2
    • extra/dnsmasq 2.69-2
    • core/nfs-utils 1.2.9-5


We recommend Vagrant 1.5.2 or newer.

Because Vagrant 1.5 changed the structure of the boxes directory, we do not recommend to run vagrant-kvm with an older version of Vagrant (prior to 1.5.2).

Processor(s) that is capable to run KVM

  • Intel processor(s) with the Intel VT and the Intel 64 extensions
  • or, AMD processor(s) with the AMD-V and the AMD64 extensions


Install Prerequisites

Install the packages required to install and run vagrant-kvm.

sudo pacman -Sy
sudo pacman -S --noconfirm qemu libvirt bridge-utils dnsmasq ebtables
sudo pacman -S --noconfirm gcc make

Just for sure, reboot your system after installation.

Start libvirt Services

Enable libvirt services at system start up.

sudo systemctl enable libvirtd.service libvirt-guests.service

Start libvirt services.

sudo systemctl start libvirtd.service libvirt-guests.service

Add o+x Permission to Your Home Directory

The default home directory permission may prevent a virtual machine (qemu-system-x86_64) to access the libvirt storage pool in .vagrant.d directory (Issue #163). Give it x permission for users in other groups.

chmod o+x $HOME

Configure PolicyKit for non-Root Access to libvirt Service

Arch Linux uses PolicyKit to manage access to libvirt, and by default, it will require root privilege. You can add the following polkit rule to allow users in virt group to access libvirt in user privilege.

Add /etc/polkit-1/rules.d/10.virt.rules with the following contents.

polkit.addRule(function(action, subject) {
  polkit.log("action=" + action);
  polkit.log("subject=" + subject);
  var now = new Date();
  polkit.log("now=" + now)
  if (( == "org.libvirt.unix.manage"
        || == "org.libvirt.unix.monitor")
      && subject.isInGroup("virt")) {
    return polkit.Result.YES;
  return null;

Then restart polkit service.

sudo systemctl restart polkit.service

Create virt group and add your user to the group.

sudo groupadd virt
sudo usermod -a -G virt ~~username~~

Logout and login again so that PolicyKit will recognize your group.

Install Vagrant

Vagrant is available via community repository. We recommend Vagrant 1.5.2 or newer.

sudo pacman -S --noconfirm vagrant

Install vagrant-kvm Plugin

Disable the curl Libraries Embedded in Vagrant

Vagrant is shipped with embedded curl libraries and this will prevent to install ruby-libvirt, a ruby gem that vagrant-kvm depends on. (Issue #161 (Comment)).

To workaround this, temporary disable the curl libraries by renaming them.

sudo mv /opt/vagrant/embedded/lib/{,.backup}
sudo mv /opt/vagrant/embedded/lib/{,.backup}
sudo mv /opt/vagrant/embedded/lib/{,.backup}
sudo mv /opt/vagrant/embedded/lib/pkgconfig/libcurl.pc{,.backup}

Install vagrant-kvm Plugin

Install vagrant-kvm plugin:

vagrant plugin install vagrant-kvm

Verify that you have installed vagrant-kvm 0.1.7 or newer. The versions prior to 0.1.7 will not work with Vagrant 1.5 or newer.

vagrant plugin list

Enable the curl Libraries

Finally, rename the curl libraries back to their original names.

sudo mv /opt/vagrant/embedded/lib/{.backup,}
sudo mv /opt/vagrant/embedded/lib/{.backup,}
sudo mv /opt/vagrant/embedded/lib/{.backup,}
sudo mv /opt/vagrant/embedded/lib/pkgconfig/libcurl.pc{.backup,}

(Optional) Set vagrant-kvm as the Default Vagrant Provider

If you want to make vagrant-kvm as the default Vagrant provider, add the following line to your shell's init script (e.g. .bashrc).


(Optional) Build and Install a Development Version

You can test a development version of vagrant-kvm.

Install Prerequisites

sudo pacman -S --noconfirm ruby libxml2 libxslt git

Build and Install vagrant-kvm

Build the gem.

git clone
cd vagrant-kvm
gem build vagrant-kvm.gemspec

Next disable the embedded curl libraries like a regular installation.

Then install vagrant-kvm.

vagrant plugin install vagrant-kvm-x.y.z.gem

Finally enable the embedded cur libraries.

Using Vagrant Synced Folder

As of vagrant-kvm 0.1.7, you can use NFS or RSync for synced folders.

  • NFS

    • This is the default synced folder type in vagrant-kvm 0.1.7.
    • Unlike RSync, the contents of the folder will be always synchronized between the host and guest in both direction.
    • Requires both the host and guest to have NFS libraries installed in advance.
    • root privilege will be required to start a VM. (Your user has to be a sudoer.)
    • For more information, see NFS - Synced Folders - Vagrant Documentation
  • RSync

    • This is a new synced folder type introduced by Vagrant 1.5.
    • You can use RSync by specifying config.vm.synced_folder "~~host folder~~", "~~guest mount point~~", type: "rsync" in Vagrantfile.
    • It only does one time, one way sync from the host to the guest being started by Vagrant.
    • Does not require any additional libraries. Vagrant will install rsync on a guest when necessary.
    • For more information, see RSync - Synced Folders - Vagrant Documentation

Future versions of vagrant-kvm will support another type 9p (virtfs) as the default synced folder type. 9p will have less performance overhead than NFS and also will not require root privilege.

Configure NFS Server

Install and Start NFS Server

sudo pacman -S --noconfirm nfs-utils
sudo systemctl enable nfsd.service
sudo systemctl start nfsd.service

Enable NFSv3 Protocol

Vagrant will try to start NFS related services when necessary. However arch host plugin in Vagrant 1.5.2 only starts the services to enable NFSv4 protocol, and this will cause a problem because NFS synced folder uses NFSv3 protocol as the default.

To solve this, start the services for NFSv3 protocol by yourself.

sudo systemctl enable rpc-mountd.service rpc-statd.service
sudo systemctl start rpc-mountd.service rpc-statd.service

Allow Access to the NFS Related Service Ports

By default, Vagrant uses UDP protocol for NFS share. If you have firewall installed, make sure NFS related UDP ports can be accessed.

If you are using firewalld to configure the firewall, please refer to the Fedora configuration as an example.

Next Step

  • (TODO) Try out an existing Vagrant KVM box.

  • (TODO) Or, convert an existing Vagrant (VirtualBox) box or create your own.

You can’t perform that action at this time.