Getting Started With Libvirt

Libvirt is a toolkit to interact with the virtualization capabilities of recent versions of Linux (and other OSes). This driver Salt cloud provider is currently geared towards libvirt with qemu-kvm.


  • libvirt >= 1.2.18 (older might work)

Provider Configuration

For every KVM host a provider needs to be set up. The provider currently maps to one libvirt daemon (e.g. one KVM host).

Set up the provider cloud configuration file at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf.

# Set up a provider with qemu+ssh protocol
  driver: libvirt
  url: qemu+ssh://

# Or connect to a local libvirt instance
  driver: libvirt
  url: qemu:///system

Cloud Profiles

Virtual machines get cloned from so called Cloud Profiles. Profiles can be set up at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/*.conf:

  • Configure a profile to be used:
  # points back at provider configuration
  provider: local-kvm
  base_domain: base-centos7-64
  ip_source: ip-learning
  ssh_username: root
  password: my-very-secret-password
  # /tmp is mounted noexec.. do workaround
  deploy_command: sh /tmp/.saltcloud/
  script_args: -F
  # grains to add to the minion
    clones-are-awesome: true
  # override minion settings
    master_port: 5506

The profile can be realized now with a salt command:

# salt-cloud -p centos7 my-centos7-clone

This will create an instance named my-centos7-clone on the cloud host. Also the minion id will be set to my-centos7-clone.

If the command was executed on the salt-master, its Salt key will automatically be signed on the master.

Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

# salt my-centos7-clone

Required Settings

The following settings are always required for libvirt:

  provider: local-kvm
  # the domain to clone
  base_domain: base-centos7-64
  # how to obtain the IP address of the cloned instance
  # ip-learning or qemu-agent
  ip_source: ip-learning

The ip_source setting controls how the IP address of the cloned instance is determined. When using ip-learning the IP is requested from libvirt. This needs a recent libvirt version and may only work for NAT networks. Another option is to use qemu-agent this requires that the qemu-agent is installed and configured to run at startup in the base domain.

Optional Settings

# Username and password
ssh_username: root
password: my-secret-password

# Cloning strategy: full or quick
clone_strategy: quick

The clone_strategy controls how the clone is done. In case of full the disks are copied creating a standalone clone. If quick is used the disks of the base domain are used as backing disks for the clone. This results in nearly instantaneous clones at the expense of slower write performance. The quick strategy has a number of requirements:

  • The disks must be of type qcow2
  • The base domain must be turned off
  • The base domain must not change after creating the clone