Difference between revisions of "Libvirt"

From ArchWiki
Jump to: navigation, search
m (Remove gap.)
(UEFI Support: changed {{accuracy}} to ovmf from ovmf-git, as it now exists in extra.)
 
(270 intermediate revisions by 41 users not shown)
Line 1: Line 1:
[[Category:Virtualization]]{{DISPLAYTITLE:libvirt}}
+
{{DISPLAYTITLE:libvirt}}
{{Article summary start}}
+
[[Category:Virtualization]]
{{Article summary text|This article does not try to cover everything about libvirt, just the things that were not intuitive at first or not well documented.}}
+
[[ja:libvirt]]
{{Article summary heading|Related}}
+
[[zh-CN:Libvirt]]
{{Article summary wiki|QEMU}}
+
{{Related articles start}}
{{Article summary wiki|KVM}}
+
{{Related|:Category:Hypervisors}}
{{Article summary wiki|VirtualBox}}
+
{{Related|:PCI passthrough via OVMF}}
{{Article summary wiki|Xen}}
+
{{Related articles end}}
{{Article summary wiki|VMware}}
+
{{Article summary end}}
+
libvirt is a virtualization API and a daemon for managing virtual machines (VMs) -- remote or locally, using multiple virtualization back-ends ([[QEMU]]/[[KVM]], [[VirtualBox]], [[Xen]], etc).
+
  
==Installing==
+
Libvirt is collection of software that provides a convenient way to manage virtual machines and other virtualization functionality, such as storage and network interface management. These software pieces include a long term stable C API, a daemon (libvirtd), and a command line utility (virsh). A primary goal of libvirt is to provide a single way to manage multiple different virtualization providers/hypervisors, such as the [[QEMU|KVM/QEMU]], [[Xen]], [[LXC]], [http://openvz.org OpenVZ] or [[VirtualBox]] [[:Category:Hypervisors|hypervisors]] ([http://libvirt.org/drivers.html among others]).
For servers you need the following packages from the [[Official Repositories|official Arch Linux repositories]]:  
+
* {{Pkg|libvirt}}
+
* {{Pkg|urlgrabber}} (required by {{Pkg|virtinst}})
+
* {{Pkg|qemu}} (optional if not using [[KVM]])
+
* {{Pkg|dnsmasq}} (optional)
+
* {{Pkg|bridge-utils}} (optional)
+
  
For GUI management tools, you also need all of the following from the official Arch Linux repositories:
+
Some of the major libvirt features are:
* {{Pkg|virtviewer}}
+
*'''VM management''': Various domain lifecycle operations such as start, stop, pause, save, restore, and migrate. Hotplug operations for many device types including disk and network interfaces, memory, and cpus.
* {{Pkg|virtinst}}
+
*'''Remote machine support''': All libvirt functionality is accessible on any machine running the libvirt daemon, including remote machines. A variety of network transports are supported for connecting remotely, with the simplest being SSH, which requires no extra explicit configuration.
* {{Pkg|virt-manager}}
+
*'''Storage management''': Any host running the libvirt daemon can be used to manage various types of storage: create file images of various formats (qcow2, vmdk, raw, ...), mount NFS shares, enumerate existing LVM volume groups, create new LVM volume groups and logical volumes, partition raw disk devices, mount iSCSI shares, and much more.
 +
*'''Network interface management''': Any host running the libvirt daemon can be used to manage physical and logical network interfaces. Enumerate existing interfaces, as well as configure (and create) interfaces, bridges, vlans, and bond devices.
 +
*'''Virtual NAT and Route based networking''': Any host running the libvirt daemon can manage and create virtual networks. Libvirt virtual networks use firewall rules to act as a router, providing VMs transparent access to the host machines network.
  
===Building libvirt for Xen===
+
== Installation ==
The [[PKGBUILD]] for both {{AUR|libvirt-git}} in the [[Arch User Repository|AUR]] and {{Pkg|libvirt}} in the [[Official Repositories|official repositories]] currently disables [[Xen]] support with the {{ic|--without-xen}} flag during the make process. If you want to use libvirt for managing Xen, you will need to [https://projects.archlinux.org/svntogit/community.git/tree/libvirt/repos/community-x86_64/ grab the whole file set] to enable Xen support and build your own libvirt package using the [[Arch Build System]]. Furthermore, you need to make sure you have {{AUR|libxenctrl}} installed. If {{AUR|xen}} is installed, you don't need to install {{AUR|libxenctrl}}.
+
  
The alternative XenAPI driver is lacking a package at the moment? (2010-05-23, friesoft)
+
Because of its daemon/client architecture, libvirt needs only be installed on the machine which will host the virtualized system. Note that the server and client can be the same physical machine.
  
==Configuration==
+
=== Server ===
  
===Run daemon===
+
[[Install]] the {{pkg|libvirt}} package, as well as at least one hypervisor:
  
Change default user and group in /etc/libvirt/qemu.conf. (nobody:nobody by default)
+
* As of 2015-02-01, {{ic|libvirtd}} '''requires''' {{Pkg|qemu}} to be installed on the system to start (see {{Bug|41888}}). Fortunately, the [http://libvirt.org/drvqemu.html libvirt KVM/QEMU driver] is the primary ''libvirt'' driver and if [[QEMU#Enabling_KVM|KVM is enabled]], fully virtualized, hardware accelerated guests will be available. See the [[QEMU]] article for more informations.
  
[[Daemon#Performing daemon actions manually|Start the libvirtd daemon]] and add {{ic|libvirtd}} to your [[Daemon#Starting on Boot|DAEMONS array]] so it starts automatically on boot.
+
* Other [http://libvirt.org/drivers.html supported hypervisors] include [[LXC]], [[VirtualBox]] and [[Xen]]. See the respective articles for installation instructions. With respect to  {{ic|libvirtd}} installation note:
 +
** The [http://libvirt.org/drvlxc.html libvirt LXC driver] has no dependency on the [[LXC]] userspace tools provided by {{Pkg|lxc}}, therefore there is no need to install the package if planning on using the driver.
 +
** [[Xen]] support is available, but not by default. You need to use the [[ABS]] to modify {{Pkg|libvirt}}'s [[PKGBUILD]] and build it without the {{ic|--without-xen}} option. As VirtualBox in turn has no planned stable support for Xen, you might as well replace it with {{ic|--without-vbox}}.
  
It seems like you have to start {{ic|dbus}} and {{ic|avahi-daemon}} before starting {{ic|libvirtd}}.
+
For network connectivity, install:
  
{{Note|The Avahi daemon is used for local discovery of libvirt hosts via multicast-DNS. To disable this functionality, set {{ic|1=mdns_adv = 0}} in {{ic|/etc/libvirt/libvirtd.conf}}.}}
+
* {{Pkg|ebtables}} '''and''' {{Pkg|dnsmasq}} for the [http://wiki.libvirt.org/page/VirtualNetworking#The_default_configuration default] NAT/DHCP networking.
 +
* {{Pkg|bridge-utils}} for bridged networking.
 +
* {{Pkg|openbsd-netcat}} for remote management over [[SSH]].
  
===PolicyKit authorization===
+
=== Client ===
To allow a non-root user to manage virtual machines, you need to create the following file (for polkit >= 0.107 only):
+
  
{{hc|/etc/polkit-1/rules.d/50-org.libvirt.unix.manage.rules|<nowiki>
+
The client is the user interface that will be used to manage and access the virtual machines.
 +
 
 +
* ''virsh'' is a command line program for managing and configuring domains; it is included in the {{Pkg|libvirt}} package.
 +
* {{Pkg|virt-manager}} is a graphical user interface for managing virtual machines.
 +
* {{Pkg|virtviewer}} is a lightweight interface for interacting with the graphical display of virtualized guest OS.
 +
* {{Pkg|gnome-boxes}} is a simple GNOME 3 application to access remote or virtual systems.
 +
* {{AUR|virt-manager-qt5}}
 +
* {{AUR|libvirt-sandbox}} is an application sandbox toolkit.
 +
 
 +
A list of libvirt-compatible software can be found [http://libvirt.org/apps.html here].
 +
 
 +
== Configuration ==
 +
 
 +
For '''''system'''''-level administration (i.e. global settings and image-''volume'' location), libvirt minimally requires [[#Set up authentication|setting up authorization]], and [[#Daemon|starting the daemon]].
 +
 
 +
{{Note|For user-'''''session''''' administration, daemon setup and configuration is ''not'' required; authorization, however, is limited to local abilities; the front-end will launch a local instance of the '''libvirtd''' daemon.}}
 +
 
 +
=== Set up authentication ===
 +
 
 +
From [http://libvirt.org/auth.html#ACL_server_config libvirt: Connection authentication]:
 +
:The libvirt daemon allows the administrator to choose the authentication mechanisms used for client connections on each network socket independently. This is primarily controlled via the libvirt daemon master config file in {{ic|/etc/libvirt/libvirtd.conf}}. Each of the libvirt sockets can have its authentication mechanism configured independently. There is currently a choice of {{ic|none}}, {{ic|polkit}} and {{ic|sasl}}.
 +
 
 +
Because {{Pkg|libvirt}} pulls {{Pkg|polkit}} as a dependency during installation, [[#Using polkit|polkit]] is used as the default value for the {{ic|unix_sock_auth}} parameter ([http://libvirt.org/auth.html#ACL_server_polkit source]). [[#Authenticate with file-based permissions|File-based permissions]] remain nevertheless available.
 +
 
 +
==== Using polkit ====
 +
{{Note|A system reboot may be required before authenticating with {{ic|polkit}} works correctly.}}
 +
 
 +
The ''libvirt'' daemon provides two [[Polkit#Actions|polkit actions]] in {{ic|/usr/share/polkit-1/actions/org.libvirt.unix.policy}}:
 +
* {{ic|org.libvirt.unix.manage}} for full management access (RW daemon socket), and
 +
* {{ic|org.libvirt.unix.monitor}} for monitoring only access (read-only socket).
 +
 
 +
The default policy for the RW daemon socket will require to authenticate as an admin. This is akin to [[sudo]] auth, but does not require that the client application ultimately run as root. Default policy will still allow any application to connect to the RO socket.
 +
 
 +
Arch defaults to consider anybody in the {{ic|wheel}} group as an administrator: this is defined in {{ic|/etc/polkit-1/rules.d/50-default.rules}} (see [[Polkit#Administrator identities]]). Therefore there is no need to create a new group and rule file '''if your user is a member of the {{ic|wheel}} group''': upon connection to the RW socket (e.g. via {{Pkg|virt-manager}}) you will be prompted for your user's password.
 +
 
 +
{{Note|Prompting for a password relies on the presence of an [[Polkit#Authentication_agents|authentication agent]] on the system. Console users may face an issue with the default {{ic|pkttyagent}} agent which may or may not work properly.}}
 +
 
 +
{{Tip|If you want to configure passwordless authentication, see [[Polkit#Bypass password prompt]].}}
 +
 
 +
As of libvirt 1.2.16 (commit:[http://libvirt.org/git/?p=libvirt.git;a=commit;h=e94979e901517af9fdde358d7b7c92cc055dd50c]), members of the {{ic|libvirt}} group have passwordless access to the RW daemon socket by default. The easiest way to ensure your user has access is to ensure the libvirt group exists and they are a member of it. If you wish to change the group authorized to access the RW daemon socket to be the kvm group, create the following file:
 +
 
 +
{{hc|/etc/polkit-1/rules.d/50-libvirt.rules|<nowiki>
 +
/* Allow users in kvm group to manage the libvirt
 +
daemon without authentication */
 
polkit.addRule(function(action, subject) {
 
polkit.addRule(function(action, subject) {
 
     if (action.id == "org.libvirt.unix.manage" &&
 
     if (action.id == "org.libvirt.unix.manage" &&
         subject.user == "<replace with user name>") {
+
         subject.isInGroup("kvm")) {
 
             return polkit.Result.YES;
 
             return polkit.Result.YES;
 
     }
 
     }
});
+
});</nowiki>
</nowiki>}}
+
}}
  
Alternatively, you can grant only the monitoring rights with {{ic|org.libvirt.unix.monitor}}.
+
Then [[Users_and_groups#Other_examples_of_user_management|add yourself]] to the {{ic|kvm}} group and relogin. Replace ''kvm'' with any group of your preference just make sure it exists and that your user is a member of it (see [[Users and groups]] for more information).
  
For more information, see [http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuring_management_access_via_PolicyKit the libvirt wiki].
+
Do not forget to relogin for group changes to take effect.
  
===Unix file-based permissions===
+
==== Authenticate with file-based permissions ====
{{Note|This is an alternative to [[#PolicyKit authentication|PolicyKit authentication]].}}
+
If you wish to use Unix file-based permissions to allow some non-root users to use libvirt, you can modify the configuration files.
+
  
First, you will need to create the {{ic|libvirt}} [[Users and Groups|group]] and add any users you want to have access to libvirt to that group.
+
To define file-based permissions for users in the ''libvirt'' group to manage virtual machines, uncomment and define:
# groupadd libvirt
+
# gpasswd -a ''[username]'' libvirt
+
  
Any users that are currently logged in will need to log out and log back in to update their groups. Alternatively, the user can use the following command in the shell they will be launching libvirt from to update the group:
+
{{hc|/etc/libvirt/libvirtd.conf|<nowiki>
  $ newgrp libvirt
+
#unix_sock_group = "libvirt"
 +
#unix_sock_ro_perms = "0777" # set to 0770 to deny non-group libvirt users
 +
#unix_sock_rw_perms = "0770"
 +
#auth_unix_ro = "none"
 +
#auth_unix_rw = "none"
 +
</nowiki>}}
  
Uncomment the following lines in {{ic|/etc/libvirt/libvirtd.conf}} (they are not all in the same location in the file):
+
While some guides mention changed permissions of certain libvirt directories to ease management, keep in mind permissions are lost on package update.  To edit these system directories, root user is expected.
  
 +
=== Daemon ===
 +
 +
[[Start]] both {{ic|libvirtd.service}} and {{ic|virtlogd.service}}. Optionally [[enable]] {{ic|libvirtd.service}}. There is no need to enable {{ic|virtlogd.service}}, since {{ic|libvirtd.service}}, when enabled, also enables the {{ic|virtlogd.socket}} and {{ic|virtlockd.socket}} [[Systemd#Using_units|units]].
 +
 +
=== Unencrypt TCP/IP sockets ===
 +
 +
{{Warning|This method is used to help remote domain, connection speed for trusted networks.  This is the least secure connection method.  This should ''only'' be used for testing or use over a secure, private, and trusted network. SASL is not enabled here, so all TCP traffic is ''cleartext''. For real world ''always'' use enable SASL.}}
 +
 +
Edit {{ic|/etc/libvirt/libvirtd.conf}}:
 
{{hc|/etc/libvirt/libvirtd.conf|<nowiki>
 
{{hc|/etc/libvirt/libvirtd.conf|<nowiki>
#unix_sock_group = "libvirt"
+
listen_tls = 0
#unix_sock_ro_perms = "0777"
+
listen_tcp = 1
#unix_sock_rw_perms = "0770"
+
auth_tcp=none
#auth_unix_ro = "none"
+
#auth_unix_rw = "none"
+
 
</nowiki>}}
 
</nowiki>}}
  
{{Note|You may also wish to change {{ic|unix_sock_ro_perms}} from {{ic|0777}} to {{ic|0770}} to disallow read-only access to people who are not members of the {{ic|libvirt}} group.}}
+
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}}:
  
===Enable KVM acceleration for QEMU===
+
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}
{{Note|[[KVM]] will conflict with [[VirtualBox]]. You cannot use KVM and VirtualBox at the same time.}}
+
  
Running virtual machines with the usual [[QEMU]] emulation (i.e. without KVM)), will be '''painfully slow'''. You definitely want to enable KVM support if your CPU supports it. To find out, run the following command:
+
=== Access virtual machines using their hostnames ===
egrep --color "vmx|svm" /proc/cpuinfo
+
  
If that command generates output, then your CPU supports hardware acceleration via KVM; if that command does ''not'' generate output, then you ''cannot use KVM''.
+
For host access to guests on non-isolated, bridged networks, enable the {{ic|libvirt}} NSS module provided by {{Pkg|libvirt}}.
  
To enable KVM, you need to load the {{ic|kvm-amd}} or {{ic|kvm-intel}} kernel module depending on your CPU. In recent Linux kernels, these modules are loaded automatically.
+
Edit {{ic|/etc/nsswitch.conf}}:
 
+
{{hc|/etc/nsswitch.conf|<nowiki>
If KVM is ''not'' working, you will find the following message in your {{ic|/var/log/libvirt/qemu/VIRTNAME.log}}:
+
hosts: files libvirt dns myhostname
{{hc|/var/log/libvirt/qemu/VIRTNAME.log|<nowiki>
+
Could not initialize KVM, will disable KVM support
+
 
</nowiki>}}
 
</nowiki>}}
  
More info is available from the [http://www.linux-kvm.org/page/FAQ official KVM FAQ]
+
{{Note|While commands such as {{ic|ping}} and {{ic|ssh}} should work with virtual machine hostnames, commands such as {{ic|host}} and {{ic|nslookup}} may fail or produce unexpected results because they rely on DNS. Use {{ic|getent hosts <vm-hostname>}} instead.}}
  
===Stopping / resuming guest at host shutdown / startup ===
+
== Test ==
Running guests may be suspended (or shutdown) at host shutdown automatically using the libvirt-guests service. On the other hand, at host startup, this same daemon will resume (startup) the suspended (shutdown) guests automatically.
+
Check /etc/conf.d/libvirtd-guests for libvirt-guests options.
+
  
==Usage==
+
To test if libvirt is working properly on a ''system'' level:
  
===Installing a new VM===
+
$ virsh -c qemu:///system
To create a new VM, you need some sort of installation media, which is usually a standard {{ic|.iso}} file. Copy it to the {{ic|/var/lib/libvirt/images/}} directory (alternatively, you can create a new ''storage pool'' directory in virt-manager and copy it there).
+
  
{{Note|[[SELinux]] requires that virtual machines be stored in {{ic|/var/lib/libvirt/images/}} by default. If you use SELinux and are having issues with virtual machines, ensure that your VMs are in that directory or ensure that you have added the correct labeling to the non-default directory that you used.}}
+
To test if libvirt is working properly for a user-''session'':
  
Then run {{ic|virt-manager}}, connect to the server, right click on the connection and choose '''New'''. Choose a name, and select '''Local install media'''. Just continue with the wizard.
+
$ virsh -c qemu:///session
  
On the '''4th step''', you may want to uncheck ''Allocate entire disk now'' -- this way you will save space when your VM is not using all of its disk. However, this can cause increased fragmentation of the disk, and you ''must'' pay attention to the total available disk space on the VM host because it is much easier to over-allocate disk space to VMs.
+
== Management ==
  
On the '''5th step''', open '''Advanced options''' and make sure that ''Virt Type'' is set to '''kvm'''. If the kvm choice is not available, see section [[#Enable KVM acceleration for QEMU|Enable KVM acceleration for QEMU]] above.
+
Libvirt management is done mostly with three tools: {{Pkg|virt-manager}} (GUI), {{ic|virsh}}, and {{ic|guestfish}} (which is part of {{AUR|libguestfs}}).
  
===Creating a storage pool in virt-manager===
+
=== virsh ===
First, connect to an existing server. Once you are there, right click and choose '''Details'''. Go to '''Storage''' and press the '''+''' icon at the lower left. Then just follow the wizard. :)
+
  
===Using VirtualBox with virt-manager===
+
The virsh program is for managing guest ''domains'' (virtual machines) and works well for scripting, virtualization administration. Though most virsh commands require root privileges to run due to the communication channels used to talk to the hypervisor, typical management, creation, and running of domains (like that done with VirtualBox) can be done as a regular user.
{{Note|[[VirtualBox]] support in libvirt is not quite stable yet and may cause your libvirtd to crash. Usually this is harmless and everything will be back once you restart the daemon.}}
+
  
virt-manager does not let you to add any VirtualBox connections from the GUI. However, you can launch it from the command line:
+
Virsh includes an interactive terminal that can be entered if no commands are passed (options are allowed though): {{ic|virsh}}. The interactive terminal has support for tab completion.
  virt-manager -c vbox:///system
+
  
Or if you want to manage a remote system over SSH:
+
From the command line:
virt-manager -c vbox+ssh://username@host/system
+
  
==Remote access to libvirt==
+
$ virsh [option] <command> [argument]...
  
===Using unencrypted TCP/IP socket (most simple, least secure)===
+
From the interactive terminal:
{{Warning|This should ''only'' be used for testing or use over a secure, private, and trusted network.}}
+
  
Edit {{ic|/etc/libvirt/libvirtd.conf}}:
+
virsh # <command> [argument]...
{{hc|/etc/libvirt/libvirtd.conf|<nowiki>
+
 
listen_tls = 0
+
Help is available:
listen_tcp = 1
+
 
auth_tcp=none
+
$ virsh help [option*] or [group-keyword*]
 +
 
 +
=== Storage pools ===
 +
 
 +
A pool is a location where storage ''volumes'' can be kept.  What libvirt defines as ''volumes'' others may define as "virtual disks" or "virtual machine images".  Pool locations may be a directory, a network filesystem, or partition (this includes a [[LVM]]).  Pools can be toggled active or inactive and allocated for space.
 +
 
 +
On the ''system''-level, {{ic|/var/lib/libvirt/images/}} will be activated by default; on a user-''session'', {{ic|virt-manager}} creates {{ic|$HOME/VirtualMachines}}.
 +
 
 +
Print active and inactive storage pools:
 +
 
 +
$ virsh pool-list --all
 +
 
 +
==== Create a new pool using virsh ====
 +
 
 +
If wanted to ''add'' a storage pool, here are examples of the command form, adding a directory, and adding a LVM volume:
 +
 
 +
$ virsh pool-define-as name type [source-host] [source-path] [source-dev] [source-name] [<target>] [--source-format format]
 +
$ virsh pool-define-as ''poolname'' dir - - - - /home/''username''/.local/libvirt/images
 +
$ virsh pool-define-as ''poolname'' fs - -  ''/dev/vg0/images'' - ''mntpoint''
 +
 
 +
The above command defines the information for the pool, to build it:
 +
 
 +
$ virsh pool-build    ''poolname''
 +
$ virsh pool-start    ''poolname''
 +
$ virsh pool-autostart ''poolname''
 +
 
 +
To remove it:
 +
 
 +
$ virsh pool-undefine  ''poolname''
 +
 
 +
{{Tip|For LVM storage pools:
 +
* It is a good practice to dedicate a volume group to the storage pool only.
 +
* Choose a LVM volume group that differs from the pool name, otherwise when the storage pool is deleted the LVM group will be too.
 +
}}
 +
 
 +
==== Create a new pool using virt-manager ====
 +
 
 +
First, connect to a hypervisor (e.g. QEMU/KVM ''system'', or user-''session'').  Then, right-click on a connection and select ''Details''; select the ''Storage'' tab, push the ''+'' button on the lower-left, and follow the wizard.
 +
 
 +
=== Storage volumes ===
 +
 
 +
Once the pool has been created, volumes can be created inside the pool.  ''If building a new domain (virtual machine), this step can be skipped as a volume can be created in the domain creation process.''
 +
 
 +
==== Create a new volume with virsh ====
 +
 
 +
Create volume, list volumes, resize, and delete:
 +
$ virsh vol-create-as      ''poolname'' ''volumename'' 10GiB --format aw|bochs|raw|qcow|qcow2|vmdk
 +
$ virsh vol-upload  --pool ''poolname'' ''volumename'' ''volumepath''
 +
$ virsh vol-list          ''poolname''
 +
$ virsh vol-resize  --pool ''poolname'' ''volumename'' 12GiB
 +
$ virsh vol-delete  --pool ''poolname'' ''volumename''
 +
$ virsh vol-dumpxml --pool ''poolname'' ''volumename''  # for details.
 +
 
 +
==== virt-manager backing store type bug ====
 +
 
 +
On newer versions of {{ic|virt-manager}} you can now specify a backing store to use when creating a new disk. This is very useful, in that you can have new domains be based on base images saving you both time and disk space when provisioning new virtual systems. There is a bug (https://bugzilla.redhat.com/show_bug.cgi?id=1235406) in the current version of {{ic|virt-manager}} which causes {{ic|virt-manager}} to choose the wrong type of the backing image in the case where the backing image is a {{ic|qcow2}} type. In this case, it will errantly pick the backing type as {{ic|raw}}. This will cause the new image to be unable to read from the backing store, and effectively remove the utility of having a backing store at all.
 +
 
 +
There is a workaround for this issue. {{ic|qemu-img}} has long been able to do this operation directly. If you wish to have a backing store for your new domain before this bug is fixed, you may use the following command.
 +
 
 +
$ qemu-img create -f qcow2 -o backing_file=<path to backing image>,backing_fmt=qcow2 <disk name> <disk size>
 +
 
 +
Then you can use this image as the base for your new domain and it will use the backing store as a COW volume saving you time and disk space.
 +
 
 +
=== Domains ===
 +
 
 +
Virtual machines are called ''domains''.  If working from the command line, use {{ic|virsh}} to list, create, pause, shutdown domains, etc.  {{ic|virt-viewer}} can be used to view domains started with {{ic|virsh}}.  Creation of domains is typically done either graphically with {{ic|virt-manager}} or with {{ic|virt-install}} (a command line program that is part of the {{pkg|virt-manager}} package).
 +
 
 +
Creating a new domain typically involves using some installation media, such as an {{ic|.iso}} from the storage pool or an optical drive.
 +
 
 +
Print active and inactive domains:
 +
 
 +
# virsh list --all
 +
 
 +
{{note|[[SELinux]] has a built-in exemption for libvirt that allows volumes in {{ic|/var/lib/libvirt/images/}} to be accessed.  If using SELinux and there are issues with the volumes, ensure that volumes are in that directory, or ensure that other storage pools are correctly labeled.}}
 +
 
 +
==== Create a new domain using virt-install ====
 +
 
 +
For an extremely detailed domain (virtual machine) setup, it is easier to [[#Create a new domain using virt-manager]].  However, basics can easily be done with {{ic|virt-install}} and still run quite well.  Minimum specifications are {{ic|--name}}, {{ic|--memory}}, guest storage ({{ic|--disk}}, {{ic|--filesystem}}, or {{ic|--nodisks}}), and an install method (generally an {{ic|.iso}} or CD). See {{ic|man virt-install}} for more details and information about unlisted options.
 +
 
 +
Arch Linux install (two GiB, qcow2 format volume create; user-networking):
 +
 
 +
$ virt-install  \
 +
  --name arch-linux_testing \
 +
  --memory 1024            \
 +
  --vcpus=2,maxvcpus=4      \
 +
  --cpu host                \
 +
  --cdrom $HOME/Downloads/arch-linux_install.iso \
 +
  --disk size=2,format=qcow2  \
 +
  --network user            \
 +
  --virt-type kvm
 +
 
 +
Fedora testing (Xen hypervisor, non-default pool, do not originally view):
 +
 
 +
$ virt-install  \
 +
  --connect xen:///    \
 +
  --name fedora-testing \
 +
  --memory 2048        \
 +
  --vcpus=2            \
 +
  --cpu=host            \
 +
  --cdrom /tmp/fedora20_x84-64.iso      \
 +
  --os-type=linux --os-variant=fedora20 \
 +
  --disk pool=testing,size=4            \
 +
  --network bridge=br0                  \
 +
  --graphics=vnc                        \
 +
  --noautoconsole
 +
$ virt-viewer --connect xen:/// fedora-testing
 +
 
 +
Windows:
 +
 
 +
$ virt-install \
 +
  --name=windows7          \
 +
  --memory 2048            \
 +
  --cdrom /dev/sr0          \
 +
  --os-variant=win7        \
 +
  --disk /mnt/storage/domains/windows7.qcow2,size=20GiB \
 +
  --network network=vm-net  \
 +
  --graphics spice
 +
 
 +
{{Tip|Run {{ic|1=osinfo-query --fields=name,short-id,version os}} to get argument for {{ic|--os-variant}}; this will help define some specifications for the domain.  However, {{ic|--memory}} and {{ic|--disk}} will need to be entered; one can look within the appropriate {{ic|/usr/share/libosinfo/db/oses/''os''.xml}} if needing these specifications.  After installing, it will likely be preferable to install the [http://www.spice-space.org/download.html Spice Guest Tools] that include the [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Virtualization_Host_Configuration_and_Guest_Installation_Guide/form-Virtualization_Host_Configuration_and_Guest_Installation_Guide-Para_virtualized_drivers-Mounting_the_image_with_virt_manager.html VirtIO drivers]. For a Windows VirtIO network driver there is also {{Aur|virtio-win}}. These drivers are referenced by a {{ic|1=<model type='virtio' />}} in the guest's {{ic|.xml}} configuration section for the device. A bit more information can also be found on the [[QEMU#Preparing_a_Windows_guest|QEMU article]].}}
 +
 
 +
Import existing volume:
 +
 
 +
$ virt-install  \
 +
  --name demo  \
 +
  --memory 512 \
 +
  --disk /home/user/VMs/mydisk.img \
 +
  --import
 +
 
 +
==== Create a new domain using virt-manager ====
 +
 
 +
First, connect to the hypervisor (e.g. QEMU/KVM ''system'' or user ''session''), right click on a connection and select ''New'', and follow the wizard.
 +
 
 +
* On the ''fourth step'', de-selecting ''Allocate entire disk now'' will make setup quicker and can save disk space in the interum; ''however'', it may cause volume fragmentation over time.
 +
* On the ''fifth step'', open ''Advanced options'' and make sure that ''Virt Type'' is set to ''kvm'' (this is usually the preferred method).  If additional hardware setup is required, select the ''Customize configuration before install'' option.
 +
 
 +
==== Manage a domain ====
 +
 
 +
Start a domain:
 +
 
 +
$ virsh start ''domain''
 +
$ virt-viewer --connect qemu:///session ''domain''
 +
 
 +
Gracefully attempt to shutdown a domain; force off a domain:
 +
 
 +
$ virsh shutdown ''domain''
 +
$ virsh destroy  ''domain''
 +
 
 +
Autostart domain on libvirtd start:
 +
 
 +
$ virsh autostart ''domain''
 +
$ virsh autostart ''domain'' --disable
 +
 
 +
Shutdown domain on host shutdown:
 +
 
 +
: Running domains can be automatically suspended/shutdown at host shutdown using the {{ic|libvirt-guests.service}} systemd service. This same service will resume/startup the suspended/shutdown domain automatically at host startup.  Read {{ic|/etc/conf.d/libvirt-guests}} for service options.
 +
 
 +
Edit a domain's XML configuration:
 +
 
 +
$ virsh edit ''domain''
 +
 
 +
{{note|Virtual Machines started directly by QEMU are not managable by libvirt tools.}}
 +
 
 +
=== Networks ===
 +
 
 +
A [https://jamielinux.com/docs/libvirt-networking-handbook/ decent overview of libvirt networking].
 +
 
 +
By default, when the {{ic|libvirtd}} systemd service is started, a NAT bridge is created called ''default'' to allow external network connectivity (warning see: [[#"default" network bug]]). For other network connectivity needs, four network types exist that can be created to connect a domain to:
 +
 
 +
* bridge — a virtual device; shares data directly with a physical interface.  Use this if the host has ''static'' networking, it does not need to connect other domains, the domain requires full inbound and outbound trafficking, and the domain is running on a ''system''-level. See [[Network bridge]] on how to add a bridge additional to the default one. After creation, it needs to be specified in the respective guest's {{ic|.xml}} configuration file. 
 +
* network — a virtual network; has ability to share with other domains.  Use a virtual network if the host has ''dynamic'' networking (e.g. NetworkManager), or using wireless.
 +
* macvtap — connect directly to a host physical interface.
 +
* user — local ability networking.  Use this only for a user ''session''.
 +
 
 +
{{ic|virsh}} has the ability to create networking with numerous options for most users, however, it is easier to create network connectivity with a graphic user interface (like {{ic|virt-manager}}), or to do so on [[#Create a new domain using virt-install|creation with virt-install]].
 +
 
 +
{{note|libvirt handles DHCP and DNS with {{pkg|dnsmasq}}, launching a separate instance for every virtual network.  It also adds iptables rules for proper routing, and enables the {{ic|ip_forward}} kernel parameter.}}
 +
 
 +
=== Snapshots ===
 +
 
 +
Snapshots take the disk, memory, and device state of a domain at a point-of-time, and save it for future use.  They have many uses, from saving a "clean" copy of an OS image to saving a domain's state before a potentially destructive operation.  Snapshots are identified with a unique name.
 +
 
 +
Snapshots are saved within the volume itself and the volume must be the format: qcow2 or raw.  Snapshots use deltas so they have the potentiality to not take much space.
 +
 
 +
==== Create a snapshot ====
 +
 
 +
{{Out of date|Some of this data appears to be dated.}}
 +
 
 +
Once a snapshot is taken it is saved as a new block device and the original snapshot is taken offline.  Snapshots can be chosen from and also merged into another (even without shutting down the domain).
 +
 
 +
Print a running domain's volumes (running domains can be printed with {{ic|virsh list}}):
 +
 
 +
{{hc|# virsh domblklist ''domain''|<nowiki>
 +
Target    Source
 +
------------------------------------------------
 +
vda        /vms/domain.img
 
</nowiki>}}
 
</nowiki>}}
  
{{Warning|We do not enable SASL here, so all TCP traffic is cleartext! For real world use, ''always'' enable SASL.}}
+
To see a volume's physical properties:
  
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}}
+
{{hc|# qemu-img info /vms/domain.img|<nowiki>
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}
+
image: /vms/domain.img
 +
file format: qcow2
 +
virtual size: 50G (53687091200 bytes)
 +
disk size: 2.1G
 +
cluster_size: 65536
 +
</nowiki>}}
  
===Using SSH===
+
Create a disk-only snapshot (the option {{ic|--atomic}} will prevent the volume from being modified if snapshot creation fails):
The {{Pkg|openbsd-netcat}} package is needed for remote management over [[SSH]].
+
  
To connect to the remote system using {{ic|virsh}}:
+
  # virsh snapshot-create-as ''domain'' snapshot1 --disk-only --atomic
  $ virsh -c qemu+ssh://''username''@''host/IP address''/system
+
  
If something goes wrong, you can get some logs using:
+
List snapshots:
$ LIBVIRT_DEBUG=1 virsh -c qemu+ssh://''username''@''host/IP address''/system
+
  
To display the graphical console for a virtual machine:
+
{{hc|# virsh snapshot-list ''domain''|<nowiki>
  $ virt-viewer --connect qemu+ssh://''username''@''host/IP address''/system myvirtualmachine
+
Name                Creation Time            State
 +
  ------------------------------------------------------------
 +
snapshot1          2012-10-21 17:12:57 -0700 disk-snapshot
 +
</nowiki>}}
  
To display the virtual machine desktop management tool:
+
One can they copy the original image with {{ic|1=cp --sparse=true}} or {{ic|rsync -S}} and then merge the the original back into snapshot:
  $ virt-manager -c qemu+ssh://''username''@''host/IP address''/system
+
 
 +
# virsh blockpull --domain ''domain'' --path /vms/''domain''.snapshot1
 +
 
 +
{{ic|domain.snapshot1}} becomes a new volume.  After this is done the original volume ({{ic|domain.img}} and snapshot metadata can be deleted.  The {{ic|virsh blockcommit}} would work opposite to {{ic|blockpull}} but it seems to be currently under development (including {{ic|snapshot-revert feature}}, scheduled to be released sometime next year.
 +
 
 +
=== Other management ===
 +
 
 +
Connect to non-default hypervisor:
 +
 
 +
$ virsh --connect xen:///
 +
virsh # uri
 +
xen:///
 +
 
 +
Connect to the QEMU hypervisor over SSH; and the same with logging:
 +
 
 +
$ virsh --connect qemu+ssh://''username''@''host''/system
 +
$ LIBVIRT_DEBUG=1 virsh --connect qemu+ssh://''username''@''host''/system
 +
 
 +
Connect a graphic console over SSH:
 +
 
 +
  $ virt-viewer  --connect qemu+ssh://''username''@''host''/system ''domain''
 +
$ virt-manager --connect qemu+ssh://''username''@''host''/system ''domain''
  
 
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}
 
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}
  
===Using Python===
+
Connect to the VirtualBox hypervisor (''VirtualBox support in libvirt is not stable yet and may cause libvirtd to crash''):
The {{Pkg|libvirt}} package comes with a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}
+
 
 +
$ virsh --connect vbox:///system
 +
 
 +
Network configurations:
 +
 
 +
$ virsh -c qemu:///system net-list --all
 +
$ virsh -c qemu:///system net-dumpxml default
 +
 
 +
== Python connectivity code ==
 +
 
 +
The {{Pkg|libvirt-python}} package provides a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}.
  
 
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}
 
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}
Line 173: Line 437:
 
  import libvirt
 
  import libvirt
 
  if (__name__ == "__main__"):
 
  if (__name__ == "__main__"):
     conn = libvirt.open("qemu+ssh://xxx/system")
+
     <nowiki>conn = libvirt.open("qemu+ssh://xxx/system")</nowiki>
 
     print "Trying to find node on xxx"
 
     print "Trying to find node on xxx"
 
     domains = conn.listDomainsID()
 
     domains = conn.listDomainsID()
Line 183: Line 447:
 
             break
 
             break
  
==Bridged Networking==
+
== UEFI Support ==
To use ''physical Ethernet'' from your virtual machines, you have to create a ''bridge'' between your physical Ethernet device (here ''eth0'') and the virtual Ethernet device the VM is using.
+
  
===Host configuration===
+
{{Accuracy|Packages from different distribution. We have {{pkg|ovmf}}.}}
libvirt creates the bridge ''virbr0'' for NAT networking, so use another name such as ''br0'' or ''virbr1''.
+
You have to create a new [https://wiki.archlinux.org/index.php/Netcfg#net-profiles Netcfg Profile] to configure the bridge, for example (with DHCP configuration):
+
  
{{hc|/etc/network.d/br0|<nowiki>
+
For UEFI support you need to install the OVMF packages [https://www.kraxel.org/repos/jenkins/edk2/ Gerd Hoffman's repository].
INTERFACE="br0"
+
 
CONNECTION="bridge"
+
Download and extract edk2.git-ovmf-x64 to /usr.
DESCRIPTION="KVM Bridge connection"
+
BRIDGE_INTERFACES="eth0"
+
IP="dhcp"
+
## sets forward delay time
+
#FWD_DELAY=0
+
## sets max age of hello message
+
#MAX_AGE=10
+
</nowiki>}}
+
  
{{Tip|It is recommended that you enable [[Wikipedia:Spanning_Tree_Protocol|Spanning Tree Protocol]] (STP) on the virtual bridge (e.g. ''br0'') that you create to avoid any potential bridging loops. You can automatically enable STP by appending {{ic|1=POST_UP="brctl stp $INTERFACE on"}} to the netcfg profile.}}
+
[[Install]] {{Pkg|rpmextract}}.
  
===Guest configuration===
+
{{bc|# rpmextract.sh edk2.git-ovmf-x64-0-20150223.b877.ga8577b3.noarch.rpm
Now we have to activate the ''bridge interface'' in our ''VMs''.
+
# cp -R ./usr/share/* /usr/share}}
If have a recent Linux machine, you can use this code in the ''.xml'' file:
+
  
  [...]
+
Then you will have to source the OVMF files in {{ic|1=/etc/libvirt/qemu.conf}}.
  <interface type='bridge'>
+
Set the following details:
    <source bridge='br0'/>
+
nvram = [
    <mac address='24:42:53:21:52:49'/>
+
  "/usr/share/edk2.git/ovmf-x64/OVMF_CODE-pure-efi.fd:/usr/share/edk2.git/ovmf-x64/OVMF_VARS-pure-efi.fd",
    <model type='virtio' />
+
]
  </interface>
+
Then restart libvirtd:
  [...]
+
systemctl restart libvirtd.service
  
This code activates a ''virtio'' device on the machine so, in Windows you will have to install an additional driver (you can find it here [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers Windows KVM VirtIO drivers]) or remove the line {{ic|<model type<nowiki>=</nowiki>'virtio' />}}:
+
== See also ==
  
  [...]
+
* [http://libvirt.org/drvqemu.html Official libvirt web site]
  <interface type='bridge'>
+
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/index.html Red Hat  Virtualization Deployment and Administration Guide]
    <source bridge='br0'/>
+
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Tuning_and_Optimization_Guide/index.html Red Hat Virtualization Tuning and Optimization Guide]
    <mac address='24:42:53:21:52:49'/>
+
* [http://docs.slackware.com/howtos:general_admin:kvm_libvirt Slackware KVM and libvirt]
  </interface>
+
* [http://www-01.ibm.com/support/knowledgecenter/linuxonibm/liaat/liaatkvm.htm IBM KVM]
  [...]
+
* [https://jamielinux.com/docs/libvirt-networking-handbook/ libvirt Networking Handbook]

Latest revision as of 14:38, 10 July 2016

Libvirt is collection of software that provides a convenient way to manage virtual machines and other virtualization functionality, such as storage and network interface management. These software pieces include a long term stable C API, a daemon (libvirtd), and a command line utility (virsh). A primary goal of libvirt is to provide a single way to manage multiple different virtualization providers/hypervisors, such as the KVM/QEMU, Xen, LXC, OpenVZ or VirtualBox hypervisors (among others).

Some of the major libvirt features are:

  • VM management: Various domain lifecycle operations such as start, stop, pause, save, restore, and migrate. Hotplug operations for many device types including disk and network interfaces, memory, and cpus.
  • Remote machine support: All libvirt functionality is accessible on any machine running the libvirt daemon, including remote machines. A variety of network transports are supported for connecting remotely, with the simplest being SSH, which requires no extra explicit configuration.
  • Storage management: Any host running the libvirt daemon can be used to manage various types of storage: create file images of various formats (qcow2, vmdk, raw, ...), mount NFS shares, enumerate existing LVM volume groups, create new LVM volume groups and logical volumes, partition raw disk devices, mount iSCSI shares, and much more.
  • Network interface management: Any host running the libvirt daemon can be used to manage physical and logical network interfaces. Enumerate existing interfaces, as well as configure (and create) interfaces, bridges, vlans, and bond devices.
  • Virtual NAT and Route based networking: Any host running the libvirt daemon can manage and create virtual networks. Libvirt virtual networks use firewall rules to act as a router, providing VMs transparent access to the host machines network.

Installation

Because of its daemon/client architecture, libvirt needs only be installed on the machine which will host the virtualized system. Note that the server and client can be the same physical machine.

Server

Install the libvirt package, as well as at least one hypervisor:

  • As of 2015-02-01, libvirtd requires qemu to be installed on the system to start (see FS#41888). Fortunately, the libvirt KVM/QEMU driver is the primary libvirt driver and if KVM is enabled, fully virtualized, hardware accelerated guests will be available. See the QEMU article for more informations.
  • Other supported hypervisors include LXC, VirtualBox and Xen. See the respective articles for installation instructions. With respect to libvirtd installation note:
    • The libvirt LXC driver has no dependency on the LXC userspace tools provided by lxc, therefore there is no need to install the package if planning on using the driver.
    • Xen support is available, but not by default. You need to use the ABS to modify libvirt's PKGBUILD and build it without the --without-xen option. As VirtualBox in turn has no planned stable support for Xen, you might as well replace it with --without-vbox.

For network connectivity, install:

Client

The client is the user interface that will be used to manage and access the virtual machines.

  • virsh is a command line program for managing and configuring domains; it is included in the libvirt package.
  • virt-manager is a graphical user interface for managing virtual machines.
  • virtviewer is a lightweight interface for interacting with the graphical display of virtualized guest OS.
  • gnome-boxes is a simple GNOME 3 application to access remote or virtual systems.
  • virt-manager-qt5AUR
  • libvirt-sandboxAUR is an application sandbox toolkit.

A list of libvirt-compatible software can be found here.

Configuration

For system-level administration (i.e. global settings and image-volume location), libvirt minimally requires setting up authorization, and starting the daemon.

Note: For user-session administration, daemon setup and configuration is not required; authorization, however, is limited to local abilities; the front-end will launch a local instance of the libvirtd daemon.

Set up authentication

From libvirt: Connection authentication:

The libvirt daemon allows the administrator to choose the authentication mechanisms used for client connections on each network socket independently. This is primarily controlled via the libvirt daemon master config file in /etc/libvirt/libvirtd.conf. Each of the libvirt sockets can have its authentication mechanism configured independently. There is currently a choice of none, polkit and sasl.

Because libvirt pulls polkit as a dependency during installation, polkit is used as the default value for the unix_sock_auth parameter (source). File-based permissions remain nevertheless available.

Using polkit

Note: A system reboot may be required before authenticating with polkit works correctly.

The libvirt daemon provides two polkit actions in /usr/share/polkit-1/actions/org.libvirt.unix.policy:

  • org.libvirt.unix.manage for full management access (RW daemon socket), and
  • org.libvirt.unix.monitor for monitoring only access (read-only socket).

The default policy for the RW daemon socket will require to authenticate as an admin. This is akin to sudo auth, but does not require that the client application ultimately run as root. Default policy will still allow any application to connect to the RO socket.

Arch defaults to consider anybody in the wheel group as an administrator: this is defined in /etc/polkit-1/rules.d/50-default.rules (see Polkit#Administrator identities). Therefore there is no need to create a new group and rule file if your user is a member of the wheel group: upon connection to the RW socket (e.g. via virt-manager) you will be prompted for your user's password.

Note: Prompting for a password relies on the presence of an authentication agent on the system. Console users may face an issue with the default pkttyagent agent which may or may not work properly.
Tip: If you want to configure passwordless authentication, see Polkit#Bypass password prompt.

As of libvirt 1.2.16 (commit:[1]), members of the libvirt group have passwordless access to the RW daemon socket by default. The easiest way to ensure your user has access is to ensure the libvirt group exists and they are a member of it. If you wish to change the group authorized to access the RW daemon socket to be the kvm group, create the following file:

/etc/polkit-1/rules.d/50-libvirt.rules
/* Allow users in kvm group to manage the libvirt
daemon without authentication */
polkit.addRule(function(action, subject) {
    if (action.id == "org.libvirt.unix.manage" &&
        subject.isInGroup("kvm")) {
            return polkit.Result.YES;
    }
});

Then add yourself to the kvm group and relogin. Replace kvm with any group of your preference just make sure it exists and that your user is a member of it (see Users and groups for more information).

Do not forget to relogin for group changes to take effect.

Authenticate with file-based permissions

To define file-based permissions for users in the libvirt group to manage virtual machines, uncomment and define:

/etc/libvirt/libvirtd.conf
#unix_sock_group = "libvirt"
#unix_sock_ro_perms = "0777"  # set to 0770 to deny non-group libvirt users
#unix_sock_rw_perms = "0770"
#auth_unix_ro = "none"
#auth_unix_rw = "none"

While some guides mention changed permissions of certain libvirt directories to ease management, keep in mind permissions are lost on package update. To edit these system directories, root user is expected.

Daemon

Start both libvirtd.service and virtlogd.service. Optionally enable libvirtd.service. There is no need to enable virtlogd.service, since libvirtd.service, when enabled, also enables the virtlogd.socket and virtlockd.socket units.

Unencrypt TCP/IP sockets

Warning: This method is used to help remote domain, connection speed for trusted networks. This is the least secure connection method. This should only be used for testing or use over a secure, private, and trusted network. SASL is not enabled here, so all TCP traffic is cleartext. For real world always use enable SASL.

Edit /etc/libvirt/libvirtd.conf:

/etc/libvirt/libvirtd.conf
listen_tls = 0
listen_tcp = 1
auth_tcp=none

It is also necessary to start the server in listening mode by editing /etc/conf.d/libvirtd:

/etc/conf.d/libvirtd
LIBVIRTD_ARGS="--listen"

Access virtual machines using their hostnames

For host access to guests on non-isolated, bridged networks, enable the libvirt NSS module provided by libvirt.

Edit /etc/nsswitch.conf:

/etc/nsswitch.conf
hosts: files libvirt dns myhostname
Note: While commands such as ping and ssh should work with virtual machine hostnames, commands such as host and nslookup may fail or produce unexpected results because they rely on DNS. Use getent hosts <vm-hostname> instead.

Test

To test if libvirt is working properly on a system level:

$ virsh -c qemu:///system

To test if libvirt is working properly for a user-session:

$ virsh -c qemu:///session

Management

Libvirt management is done mostly with three tools: virt-manager (GUI), virsh, and guestfish (which is part of libguestfsAUR).

virsh

The virsh program is for managing guest domains (virtual machines) and works well for scripting, virtualization administration. Though most virsh commands require root privileges to run due to the communication channels used to talk to the hypervisor, typical management, creation, and running of domains (like that done with VirtualBox) can be done as a regular user.

Virsh includes an interactive terminal that can be entered if no commands are passed (options are allowed though): virsh. The interactive terminal has support for tab completion.

From the command line:

$ virsh [option] <command> [argument]...

From the interactive terminal:

virsh # <command> [argument]...

Help is available:

$ virsh help [option*] or [group-keyword*]

Storage pools

A pool is a location where storage volumes can be kept. What libvirt defines as volumes others may define as "virtual disks" or "virtual machine images". Pool locations may be a directory, a network filesystem, or partition (this includes a LVM). Pools can be toggled active or inactive and allocated for space.

On the system-level, /var/lib/libvirt/images/ will be activated by default; on a user-session, virt-manager creates $HOME/VirtualMachines.

Print active and inactive storage pools:

$ virsh pool-list --all

Create a new pool using virsh

If wanted to add a storage pool, here are examples of the command form, adding a directory, and adding a LVM volume:

$ virsh pool-define-as name type [source-host] [source-path] [source-dev] [source-name] [<target>] [--source-format format]
$ virsh pool-define-as poolname dir - - - - /home/username/.local/libvirt/images
$ virsh pool-define-as poolname fs - -  /dev/vg0/images - mntpoint

The above command defines the information for the pool, to build it:

$ virsh pool-build     poolname
$ virsh pool-start     poolname
$ virsh pool-autostart poolname

To remove it:

$ virsh pool-undefine  poolname
Tip: For LVM storage pools:
  • It is a good practice to dedicate a volume group to the storage pool only.
  • Choose a LVM volume group that differs from the pool name, otherwise when the storage pool is deleted the LVM group will be too.

Create a new pool using virt-manager

First, connect to a hypervisor (e.g. QEMU/KVM system, or user-session). Then, right-click on a connection and select Details; select the Storage tab, push the + button on the lower-left, and follow the wizard.

Storage volumes

Once the pool has been created, volumes can be created inside the pool. If building a new domain (virtual machine), this step can be skipped as a volume can be created in the domain creation process.

Create a new volume with virsh

Create volume, list volumes, resize, and delete:

$ virsh vol-create-as      poolname volumename 10GiB --format aw|bochs|raw|qcow|qcow2|vmdk
$ virsh vol-upload  --pool poolname volumename volumepath
$ virsh vol-list           poolname
$ virsh vol-resize  --pool poolname volumename 12GiB
$ virsh vol-delete  --pool poolname volumename
$ virsh vol-dumpxml --pool poolname volumename  # for details.

virt-manager backing store type bug

On newer versions of virt-manager you can now specify a backing store to use when creating a new disk. This is very useful, in that you can have new domains be based on base images saving you both time and disk space when provisioning new virtual systems. There is a bug (https://bugzilla.redhat.com/show_bug.cgi?id=1235406) in the current version of virt-manager which causes virt-manager to choose the wrong type of the backing image in the case where the backing image is a qcow2 type. In this case, it will errantly pick the backing type as raw. This will cause the new image to be unable to read from the backing store, and effectively remove the utility of having a backing store at all.

There is a workaround for this issue. qemu-img has long been able to do this operation directly. If you wish to have a backing store for your new domain before this bug is fixed, you may use the following command.

$ qemu-img create -f qcow2 -o backing_file=<path to backing image>,backing_fmt=qcow2 <disk name> <disk size>

Then you can use this image as the base for your new domain and it will use the backing store as a COW volume saving you time and disk space.

Domains

Virtual machines are called domains. If working from the command line, use virsh to list, create, pause, shutdown domains, etc. virt-viewer can be used to view domains started with virsh. Creation of domains is typically done either graphically with virt-manager or with virt-install (a command line program that is part of the virt-manager package).

Creating a new domain typically involves using some installation media, such as an .iso from the storage pool or an optical drive.

Print active and inactive domains:

# virsh list --all
Note: SELinux has a built-in exemption for libvirt that allows volumes in /var/lib/libvirt/images/ to be accessed. If using SELinux and there are issues with the volumes, ensure that volumes are in that directory, or ensure that other storage pools are correctly labeled.

Create a new domain using virt-install

For an extremely detailed domain (virtual machine) setup, it is easier to #Create a new domain using virt-manager. However, basics can easily be done with virt-install and still run quite well. Minimum specifications are --name, --memory, guest storage (--disk, --filesystem, or --nodisks), and an install method (generally an .iso or CD). See man virt-install for more details and information about unlisted options.

Arch Linux install (two GiB, qcow2 format volume create; user-networking):

$ virt-install  \
  --name arch-linux_testing \
  --memory 1024             \ 
  --vcpus=2,maxvcpus=4      \
  --cpu host                \
  --cdrom $HOME/Downloads/arch-linux_install.iso \
  --disk size=2,format=qcow2  \
  --network user            \
  --virt-type kvm

Fedora testing (Xen hypervisor, non-default pool, do not originally view):

$ virt-install  \
  --connect xen:///     \
  --name fedora-testing \
  --memory 2048         \
  --vcpus=2             \
  --cpu=host            \
  --cdrom /tmp/fedora20_x84-64.iso      \
  --os-type=linux --os-variant=fedora20 \
  --disk pool=testing,size=4            \
  --network bridge=br0                  \
  --graphics=vnc                        \
  --noautoconsole
$ virt-viewer --connect xen:/// fedora-testing

Windows:

$ virt-install \
  --name=windows7           \
  --memory 2048             \
  --cdrom /dev/sr0          \
  --os-variant=win7         \
  --disk /mnt/storage/domains/windows7.qcow2,size=20GiB \
  --network network=vm-net  \
  --graphics spice
Tip: Run osinfo-query --fields=name,short-id,version os to get argument for --os-variant; this will help define some specifications for the domain. However, --memory and --disk will need to be entered; one can look within the appropriate /usr/share/libosinfo/db/oses/os.xml if needing these specifications. After installing, it will likely be preferable to install the Spice Guest Tools that include the VirtIO drivers. For a Windows VirtIO network driver there is also virtio-winAUR. These drivers are referenced by a <model type='virtio' /> in the guest's .xml configuration section for the device. A bit more information can also be found on the QEMU article.

Import existing volume:

$ virt-install  \
  --name demo  \
  --memory 512 \
  --disk /home/user/VMs/mydisk.img \
  --import

Create a new domain using virt-manager

First, connect to the hypervisor (e.g. QEMU/KVM system or user session), right click on a connection and select New, and follow the wizard.

  • On the fourth step, de-selecting Allocate entire disk now will make setup quicker and can save disk space in the interum; however, it may cause volume fragmentation over time.
  • On the fifth step, open Advanced options and make sure that Virt Type is set to kvm (this is usually the preferred method). If additional hardware setup is required, select the Customize configuration before install option.

Manage a domain

Start a domain:

$ virsh start domain
$ virt-viewer --connect qemu:///session domain

Gracefully attempt to shutdown a domain; force off a domain:

$ virsh shutdown domain
$ virsh destroy  domain

Autostart domain on libvirtd start:

$ virsh autostart domain
$ virsh autostart domain --disable

Shutdown domain on host shutdown:

Running domains can be automatically suspended/shutdown at host shutdown using the libvirt-guests.service systemd service. This same service will resume/startup the suspended/shutdown domain automatically at host startup. Read /etc/conf.d/libvirt-guests for service options.

Edit a domain's XML configuration:

$ virsh edit domain
Note: Virtual Machines started directly by QEMU are not managable by libvirt tools.

Networks

A decent overview of libvirt networking.

By default, when the libvirtd systemd service is started, a NAT bridge is created called default to allow external network connectivity (warning see: #"default" network bug). For other network connectivity needs, four network types exist that can be created to connect a domain to:

  • bridge — a virtual device; shares data directly with a physical interface. Use this if the host has static networking, it does not need to connect other domains, the domain requires full inbound and outbound trafficking, and the domain is running on a system-level. See Network bridge on how to add a bridge additional to the default one. After creation, it needs to be specified in the respective guest's .xml configuration file.
  • network — a virtual network; has ability to share with other domains. Use a virtual network if the host has dynamic networking (e.g. NetworkManager), or using wireless.
  • macvtap — connect directly to a host physical interface.
  • user — local ability networking. Use this only for a user session.

virsh has the ability to create networking with numerous options for most users, however, it is easier to create network connectivity with a graphic user interface (like virt-manager), or to do so on creation with virt-install.

Note: libvirt handles DHCP and DNS with dnsmasq, launching a separate instance for every virtual network. It also adds iptables rules for proper routing, and enables the ip_forward kernel parameter.

Snapshots

Snapshots take the disk, memory, and device state of a domain at a point-of-time, and save it for future use. They have many uses, from saving a "clean" copy of an OS image to saving a domain's state before a potentially destructive operation. Snapshots are identified with a unique name.

Snapshots are saved within the volume itself and the volume must be the format: qcow2 or raw. Snapshots use deltas so they have the potentiality to not take much space.

Create a snapshot

Tango-view-refresh-red.pngThis article or section is out of date.Tango-view-refresh-red.png

Reason: Some of this data appears to be dated. (Discuss in Talk:Libvirt#)

Once a snapshot is taken it is saved as a new block device and the original snapshot is taken offline. Snapshots can be chosen from and also merged into another (even without shutting down the domain).

Print a running domain's volumes (running domains can be printed with virsh list):

# virsh domblklist domain
 Target     Source
 ------------------------------------------------
 vda        /vms/domain.img

To see a volume's physical properties:

# qemu-img info /vms/domain.img
 image: /vms/domain.img
 file format: qcow2
 virtual size: 50G (53687091200 bytes)
 disk size: 2.1G
 cluster_size: 65536

Create a disk-only snapshot (the option --atomic will prevent the volume from being modified if snapshot creation fails):

# virsh snapshot-create-as domain snapshot1 --disk-only --atomic

List snapshots:

# virsh snapshot-list domain
 Name                 Creation Time             State
 ------------------------------------------------------------
 snapshot1           2012-10-21 17:12:57 -0700 disk-snapshot

One can they copy the original image with cp --sparse=true or rsync -S and then merge the the original back into snapshot:

# virsh blockpull --domain domain --path /vms/domain.snapshot1

domain.snapshot1 becomes a new volume. After this is done the original volume (domain.img and snapshot metadata can be deleted. The virsh blockcommit would work opposite to blockpull but it seems to be currently under development (including snapshot-revert feature, scheduled to be released sometime next year.

Other management

Connect to non-default hypervisor:

$ virsh --connect xen:///
virsh # uri
xen:///

Connect to the QEMU hypervisor over SSH; and the same with logging:

$ virsh --connect qemu+ssh://username@host/system
$ LIBVIRT_DEBUG=1 virsh --connect qemu+ssh://username@host/system

Connect a graphic console over SSH:

$ virt-viewer  --connect qemu+ssh://username@host/system domain
$ virt-manager --connect qemu+ssh://username@host/system domain
Note: If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in FS#30748 and FS#22068.

Connect to the VirtualBox hypervisor (VirtualBox support in libvirt is not stable yet and may cause libvirtd to crash):

$ virsh --connect vbox:///system

Network configurations:

$ virsh -c qemu:///system net-list --all
$ virsh -c qemu:///system net-dumpxml default

Python connectivity code

The libvirt-python package provides a python2 API in /usr/lib/python2.7/site-packages/libvirt.py.

General examples are given in /usr/share/doc/libvirt-python-your_libvirt_version/examples/

Unofficial example using qemu and openssh:

#! /usr/bin/env python2
# -*- coding: utf-8 -*-
import socket
import sys
import libvirt
if (__name__ == "__main__"):
   conn = libvirt.open("qemu+ssh://xxx/system")
   print "Trying to find node on xxx"
   domains = conn.listDomainsID()
   for domainID in domains:
       domConnect = conn.lookupByID(domainID)
       if domConnect.name() == 'xxx-node':
           print "Found shared node on xxx with ID " + str(domainID)
           domServ = domConnect
           break

UEFI Support

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Packages from different distribution. We have ovmf. (Discuss in Talk:Libvirt#)

For UEFI support you need to install the OVMF packages Gerd Hoffman's repository.

Download and extract edk2.git-ovmf-x64 to /usr.

Install rpmextract.

# rpmextract.sh edk2.git-ovmf-x64-0-20150223.b877.ga8577b3.noarch.rpm
# cp -R ./usr/share/* /usr/share

Then you will have to source the OVMF files in /etc/libvirt/qemu.conf. Set the following details:

nvram = [
  "/usr/share/edk2.git/ovmf-x64/OVMF_CODE-pure-efi.fd:/usr/share/edk2.git/ovmf-x64/OVMF_VARS-pure-efi.fd",
]

Then restart libvirtd:

systemctl restart libvirtd.service

See also