<ul id="toc"></ul>
- <h2><a name="intro">Access control introduction</a></h2>
+ <h2><a id="intro">Access control introduction</a></h2>
<p>
In a default configuration, the libvirtd daemon has three levels
<code>getattr</code> permission.
</p>
- <h2><a name="drivers">Access control drivers</a></h2>
+ <h2><a id="drivers">Access control drivers</a></h2>
<p>
The access control framework is designed as a pluggable
the libvirtd daemon be restarted.
</p>
- <h2><a name="perms">Objects and permissions</a></h2>
+ <h2><a id="perms">Objects and permissions</a></h2>
<p>
Libvirt applies access control to all the main object
<ul id="toc"></ul>
- <h2><a name="intro">Introduction</a></h2>
+ <h2><a id="intro">Introduction</a></h2>
<p>
A default install of libvirt will typically use
object.
</p>
- <h2><a name="perms">Permission names</a></h2>
+ <h2><a id="perms">Permission names</a></h2>
<p>
The libvirt <a href="acl.html#perms">object names and permission names</a>
permissions default to deny access.
</p>
- <h2><a name="attrs">Object identity attributes</a></h2>
+ <h2><a id="attrs">Object identity attributes</a></h2>
<p>
To allow polkit authorization rules to be written to match
of object being checked
</p>
- <h3><a name="object_connect">virConnectPtr</a></h3>
+ <h3><a id="object_connect">virConnectPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_domain">virDomainPtr</a></h3>
+ <h3><a id="object_domain">virDomainPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_interface">virInterfacePtr</a></h3>
+ <h3><a id="object_interface">virInterfacePtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_network">virNetworkPtr</a></h3>
+ <h3><a id="object_network">virNetworkPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_node_device">virNodeDevicePtr</a></h3>
+ <h3><a id="object_node_device">virNodeDevicePtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_nwfilter">virNWFilterPtr</a></h3>
+ <h3><a id="object_nwfilter">virNWFilterPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_secret">virSecretPtr</a></h3>
+ <h3><a id="object_secret">virSecretPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_storage_pool">virStoragePoolPtr</a></h3>
+ <h3><a id="object_storage_pool">virStoragePoolPtr</a></h3>
<table class="acl">
<thead>
<tr>
</tbody>
</table>
- <h3><a name="object_storage_vol">virStorageVolPtr</a></h3>
+ <h3><a id="object_storage_vol">virStorageVolPtr</a></h3>
<table class="acl">
<thead>
<tr>
</table>
- <h2><a name="user">User identity attributes</a></h2>
+ <h2><a id="user">User identity attributes</a></h2>
<p>
At this point in time, the only attribute provided by
</p>
- <h2><a name="checks">Writing access control policies</a></h2>
+ <h2><a id="checks">Writing access control policies</a></h2>
<p>
If using versions of polkit prior to 0.106 then it is only
for a more complex example.
</p>
- <h3><a name="exconnect">Example: restricting ability to connect to drivers</a></h3>
+ <h3><a id="exconnect">Example: restricting ability to connect to drivers</a></h3>
<p>
Consider a local user <code>berrange</code>
});
</pre>
- <h3><a name="exdomain">Example: restricting access to a single domain</a></h3>
+ <h3><a id="exdomain">Example: restricting access to a single domain</a></h3>
<p>
Consider a local user <code>berrange</code>
<ul id="toc"></ul>
- <h2><a name="Objects">Objects Exposed</a></h2>
+ <h2><a id="Objects">Objects Exposed</a></h2>
<p> As defined in the <a href="goals.html">goals section</a>, the libvirt
API is designed to expose all the resources needed to manage the
virtualization support of recent operating systems. The first object
set of nodes.</p></li>
</ul>
- <h2><a name="Functions">Functions and Naming Conventions</a></h2>
+ <h2><a id="Functions">Functions and Naming Conventions</a></h2>
<p> The naming of the functions present in the library is usually
composed by a prefix describing the object associated to the function
and a verb describing the action on that object.</p>
<p> For more in-depth details of the storage related APIs see
<a href="storage.html">the storage management page</a>.
</p>
- <h2><a name="Drivers">The libvirt Drivers</a></h2>
+ <h2><a id="Drivers">The libvirt Drivers</a></h2>
<p>Drivers are the basic building block for libvirt functionality
to support the capability to handle specific hypervisor driver calls.
Drivers are discovered and registered during connection processing as
the various functions and support found in each driver by the version
support was added into libvirt.
</p>
- <h2><a name="Remote">Daemon and Remote Access</a></h2>
+ <h2><a id="Remote">Daemon and Remote Access</a></h2>
<p>Access to libvirt drivers is primarily handled by the libvirtd
daemon through the <a href="remote.html">remote</a> driver via an
<a href="internals/rpc.html">RPC</a>. Some hypervisors do support
<li>unlocks the remote driver.</li>
</ol>
- <h3><a name="serverdispatch">Implement the server side dispatcher</a></h3>
+ <h3><a id="serverdispatch">Implement the server side dispatcher</a></h3>
<p>
Implementing the server side of the remote function call is simply a
<p class="example">See <a href="api_extension/0005-implement-the-remote-protocol.patch">0005-implement-the-remote-protocol.patch</a></p>
- <h2><a name="internaluseapi">Use the new API internally</a></h2>
+ <h2><a id="internaluseapi">Use the new API internally</a></h2>
<p>
Sometimes, a new API serves as a superset of existing API, by
<p class="example">See <a href="api_extension/0006-make-old-API-trivially-wrap-to-new-API.patch">0006-make-old-API-trivially-wrap-to-new-API.patch</a></p>
- <h2><a name="virshuseapi">Expose the new API in virsh</a></h2>
+ <h2><a id="virshuseapi">Expose the new API in virsh</a></h2>
<p>
All new API should be manageable from the virsh command line
<p class="example">See <a href="api_extension/0007-add-virsh-support.patch">0007-add-virsh-support.patch</a></p>
- <h2><a name="driverimpl">Implement the driver methods</a></h2>
+ <h2><a id="driverimpl">Implement the driver methods</a></h2>
<p>
So, after all that, we get to the fun part. All functionality in
adding.
</p>
- <h3><a name="commonimpl">Implement common handling</a></h3>
+ <h3><a id="commonimpl">Implement common handling</a></h3>
<p>
If the new API is applicable to more than one driver, it may
<p class="example">See <a href="api_extension/0008-support-new-xml.patch">0008-support-new-xml.patch</a></p>
- <h3><a name="drivercode">Implement driver handling</a></h3>
+ <h3><a id="drivercode">Implement driver handling</a></h3>
<p>
The remaining patches should only touch one driver at a time.
<ul id="toc"></ul>
- <h2><a name="add">Add an application</a></h2>
+ <h2><a id="add">Add an application</a></h2>
<p>
To add an application not listed on this page, send a message
<img src="logos/logo-square-powered-256.png" alt="libvirt powered"/>
</p>
- <h2><a name="clientserver">Client/Server applications</a></h2>
+ <h2><a id="clientserver">Client/Server applications</a></h2>
<dl>
<dt><a href="http://archipelproject.org">Archipel</a></dt>
</dd>
</dl>
- <h2><a name="command">Command line tools</a></h2>
+ <h2><a id="command">Command line tools</a></h2>
<dl>
<dt><a href="http://libguestfs.org">guestfish</a></dt>
</dd>
</dl>
- <h2><a name="configmgmt">Configuration Management</a></h2>
+ <h2><a id="configmgmt">Configuration Management</a></h2>
<dl>
<dt><a href="https://wiki.lcfg.org/bin/view/LCFG/LcfgLibvirt">LCFG</a></dt>
</dd>
</dl>
- <h2><a name="continuousintegration">Continuous Integration</a></h2>
+ <h2><a id="continuousintegration">Continuous Integration</a></h2>
<dl>
<dt><a href="http://buildbot.net/buildbot/docs/current/Libvirt.html">BuildBot</a></dt>
</dd>
</dl>
- <h2><a name="conversion">Conversion</a></h2>
+ <h2><a id="conversion">Conversion</a></h2>
<dl>
<dt><a href="http://libguestfs.org/virt-p2v.1.html">virt-p2v</a></dt>
</dd>
</dl>
- <h2><a name="desktop">Desktop applications</a></h2>
+ <h2><a id="desktop">Desktop applications</a></h2>
<dl>
<dt><a href="http://virt-manager.org/">virt-manager</a></dt>
</dd>
</dl>
- <h2><a name="iaas">Infrastructure as a Service (IaaS)</a></h2>
+ <h2><a id="iaas">Infrastructure as a Service (IaaS)</a></h2>
<dl>
<dt><a href="http://cc1.ifj.edu.pl">Cracow Cloud One</a></dt>
</dd>
</dl>
- <h2><a name="libraries">Libraries</a></h2>
+ <h2><a id="libraries">Libraries</a></h2>
<dl>
<dt><a href="http://libguestfs.org">libguestfs</a></dt>
</dd>
</dl>
- <h2><a name="livecd">LiveCD / Appliances</a></h2>
+ <h2><a id="livecd">LiveCD / Appliances</a></h2>
<dl>
<dt><a href="http://et.redhat.com/~rjones/virt-p2v/">virt-p2v</a></dt>
</dd>
</dl>
- <h2><a name="monitoring">Monitoring</a></h2>
+ <h2><a id="monitoring">Monitoring</a></h2>
<dl>
<dt><a href="http://collectd.org/plugins/libvirt.shtml">collectd</a></dt>
<dd>
</dd>
</dl>
- <h2><a name="provisioning">Provisioning</a></h2>
+ <h2><a id="provisioning">Provisioning</a></h2>
<dl>
<dt><a href="http://www.ibm.com/software/tivoli/products/prov-mgr/">Tivoli Provisioning Manager</a></dt>
</dl>
- <h2><a name="web">Web applications</a></h2>
+ <h2><a id="web">Web applications</a></h2>
<dl>
<dt><a href="http://community.abiquo.com/display/AbiCloud">AbiCloud</a></dt>
</dd>
</dl>
- <h2><a name="mobile">Mobile applications</a></h2>
+ <h2><a id="mobile">Mobile applications</a></h2>
<dl>
<dt><a href="https://market.android.com/details?id=vm.manager">VM Manager</a></dt>
</dd>
</dl>
- <h2><a name="other">Other</a></h2>
+ <h2><a id="other">Other</a></h2>
<dl>
<dt><a href="http://cuckoosandbox.org/">Cuckoo Sandbox</a></dt>
<ul id="toc"></ul>
- <h2><a name="Xen">Xen support</a></h2>
+ <h2><a id="Xen">Xen support</a></h2>
<p>When running in a Xen environment, programs using libvirt have to execute
in "Domain 0", which is the primary Linux OS loaded on the machine. That OS
program running as root and providing read_only access to the API, this is
then only useful for reporting and monitoring.</p>
- <h2><a name="QEmu">QEmu and KVM support</a></h2>
+ <h2><a id="QEmu">QEmu and KVM support</a></h2>
<p>The model for QEmu and KVM is completely similar, basically KVM is based
on QEmu for the process controlling a new domain, only small details differs
<p>The code controlling the QEmu process is available in the
<code>qemud/</code> directory.</p>
- <h2><a name="drivers">Driver based architecture</a></h2>
+ <h2><a id="drivers">Driver based architecture</a></h2>
<p>As the previous section explains, libvirt can communicate using different
channels with the current hypervisor, and should also be able to use
<ul id="toc"></ul>
- <h2><a name="intro">Introduction</a></h2>
+ <h2><a id="intro">Introduction</a></h2>
<p>
A number of the libvirt virtualization drivers (QEMU/KVM and LXC) include
the logs will usually end up in <code>/var/log/audit/audit.log</code>
</p>
- <h2><a name="config">Configuration</a></h2>
+ <h2><a id="config">Configuration</a></h2>
<p>
The libvirt audit integration is enabled by default on any host which has
mentioned above.
</p>
- <h2><a name="types">Message types</a></h2>
+ <h2><a id="types">Message types</a></h2>
<p>
Libvirt defines three core audit message types each of which will
<dd>Result of the action, either <code>success</code> or <code>failed</code></dd>
</dl>
- <h3><a name="typecontrol">VIRT_CONTROL</a></h3>
+ <h3><a id="typecontrol">VIRT_CONTROL</a></h3>
<p>
Reports change in the lifecycle state of a virtual machine. The <code>msg</code>
<dd>Namespace ID of the <code>init</code> process in a container. Only if <code>op=init</code> and <code>virt=lxc</code></dd>
</dl>
- <h3><a name="typemachine">VIRT_MACHINE_ID</a></h3>
+ <h3><a id="typemachine">VIRT_MACHINE_ID</a></h3>
<p>
Reports the association of a security context with a guest. The <code>msg</code>
<dd>Security context for the guest disk images and other assigned host resources</dd>
</dl>
- <h3><a name="typeresource">VIRT_RESOURCE</a></h3>
+ <h3><a id="typeresource">VIRT_RESOURCE</a></h3>
<p>
Reports the usage of a host resource by a guest. The fields include will
be generated.
</p>
- <h4><a name="typeresourcevcpu">Virtual CPU</a></h4>
+ <h4><a id="typeresourcevcpu">Virtual CPU</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</dl>
- <h4><a name="typeresourcemem">Memory</a></h4>
+ <h4><a id="typeresourcemem">Memory</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
<dd>Updated memory size in bytes</dd>
</dl>
- <h4><a name="typeresourcedisk">Disk</a></h4>
+ <h4><a id="typeresourcedisk">Disk</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>Updated host file or device path acting as the disk backing file</dd>
</dl>
- <h4><a name="typeresourcenic">Network interface</a></h4>
+ <h4><a id="typeresourcenic">Network interface</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
<dd>Name of the host network interface</dd>
</dl>
- <h4><a name="typeresourcefs">Filesystem</a></h4>
+ <h4><a id="typeresourcefs">Filesystem</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>Updated host directory, file or device path backing the filesystem</dd>
</dl>
- <h4><a name="typeresourcehost">Host device</a></h4>
+ <h4><a id="typeresourcehost">Host device</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>The path of the character device assigned to the guest, if <code>resrc=hostdev</code></dd>
</dl>
- <h4><a name="typeresourcetpm">TPM</a></h4>
+ <h4><a id="typeresourcetpm">TPM</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>The path of the host TPM device assigned to the guest</dd>
</dl>
- <h4><a name="typeresourcerng">RNG</a></h4>
+ <h4><a id="typeresourcerng">RNG</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>Updated path of the host entropy source for the RNG</dd>
</dl>
- <h4><a name="typeresourcechardev">console/serial/parallel/channel</a></h4>
+ <h4><a id="typeresourcechardev">console/serial/parallel/channel</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>Updated path of the backing character device for given emulated device</dd>
</dl>
- <h4><a name="typeresourcesmartcard">smartcard</a></h4>
+ <h4><a id="typeresourcesmartcard">smartcard</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
</dd>
</dl>
- <h4><a name="typeresourceredir">Redirected device</a></h4>
+ <h4><a id="typeresourceredir">Redirected device</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<dd>The device type, only <code>USB redir</code> allowed</dd>
</dl>
- <h4><a name="typeresourcecgroup">Control group</a></h4>
+ <h4><a id="typeresourcecgroup">Control group</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</dl>
- <h4><a name="typeresourceshmem">Shared memory</a></h4>
+ <h4><a id="typeresourceshmem">Shared memory</a></h4>
<p>
The <code>msg</code> field will include the following sub-fields
</p>
<ul id="toc"></ul>
- <h2><a name="Auth_client_config">Client configuration</a></h2>
+ <h2><a id="Auth_client_config">Client configuration</a></h2>
<p>
When connecting to a remote hypervisor which requires authentication,
to storage VNC or SPICE login credentials
</p>
- <h2><a name="ACL_server_config">Server configuration</a></h2>
+ <h2><a id="ACL_server_config">Server configuration</a></h2>
<p>
The libvirt daemon allows the administrator to choose the authentication
mechanisms used for client connections on each network socket independently.
The SASL scheme can be further configured to choose between a large
number of different mechanisms.
</p>
- <h2><a name="ACL_server_unix_perms">UNIX socket permissions/group</a></h2>
+ <h2><a id="ACL_server_unix_perms">UNIX socket permissions/group</a></h2>
<p>
If libvirt does not contain support for PolicyKit, then access control for
the UNIX domain socket is done using traditional file user/group ownership
latter <code>wheel</code> would let any user in the wheel group connect to
the libvirt daemon.
</p>
- <h2><a name="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2>
+ <h2><a id="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2>
<p>
If libvirt contains support for PolicyKit, then access control options are
more advanced. The <code>auth_unix_rw</code> parameter will default to
Further examples of PolicyKit setup can be found on the
<a href="http://wiki.libvirt.org/page/SSHPolicyKitSetup">wiki page</a>.
</p>
- <h2><a name="ACL_server_sasl">SASL pluggable authentication</a></h2>
+ <h2><a id="ACL_server_sasl">SASL pluggable authentication</a></h2>
<p>
Libvirt integrates with the cyrus-sasl library to provide a pluggable authentication
TLS or UNIX socket listeners.
</p>
- <h3><a name="ACL_server_username">Username/password auth</a></h3>
+ <h3><a id="ACL_server_username">Username/password auth</a></h3>
<p>
As noted above, the DIGEST-MD5 mechanism is considered obsolete and should
not be used anymore. To provide a simple username/password auth scheme on
<pre>
# saslpasswd2 -a libvirt -d fred
</pre>
- <h3><a name="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3>
+ <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3>
<p>
The plain TCP listener of the libvirt daemon defaults to using SASL for authentication.
The libvirt SASL config also defaults to GSSAPI, so there is no need to edit the
<ul id="toc"></ul>
- <h2><a name="security">Security Issues</a></h2>
+ <h2><a id="security">Security Issues</a></h2>
<p>
If you think that an issue with libvirt may have security
<a href="securityprocess.html">security process</a> instead.
</p>
- <h2><a name="bugzilla">Bug Tracking</a></h2>
+ <h2><a id="bugzilla">Bug Tracking</a></h2>
<p>
If you are using libvirt binaries from a Linux distribution
first.
</p>
- <h2><a name="general">General libvirt bug reports</a></h2>
+ <h2><a id="general">General libvirt bug reports</a></h2>
<p>
The <a href="http://bugzilla.redhat.com">Red Hat Bugzilla Server</a>
<li><a href="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Virtualization%20Tools&component=libvirt">New libvirt ticket</a></li>
</ul>
- <h2><a name="distribution">Linux Distribution specific bug reports</a></h2>
+ <h2><a id="distribution">Linux Distribution specific bug reports</a></h2>
<ul>
<li>
If you are using binaries from <strong>Fedora</strong>, enter
</ul>
- <h2><a name="quality">How to file high quality bug reports</a></h2>
+ <h2><a id="quality">How to file high quality bug reports</a></h2>
<p>
To increase the likelihood of your bug report being addressed it is
for applying resource management to their virtual machines and containers.
</p>
- <h2><a name="requiredControllers">Required controllers</a></h2>
+ <h2><a id="requiredControllers">Required controllers</a></h2>
<p>
The control groups filesystem supports multiple "controllers". By default
which use them will cease to operate.
</p>
- <h2><a name="currentLayout">Current cgroups layout</a></h2>
+ <h2><a id="currentLayout">Current cgroups layout</a></h2>
<p>
As of libvirt 1.0.5 or later, the cgroups layout created by libvirt has been
in two, one describing systemd hosts and the other non-systemd hosts.
</p>
- <h3><a name="currentLayoutSystemd">Systemd cgroups integration</a></h3>
+ <h3><a id="currentLayoutSystemd">Systemd cgroups integration</a></h3>
<p>
On hosts which use systemd, each consumer maps to a systemd scope unit,
while partitions map to a system slice unit.
</p>
- <h4><a name="systemdScope">Systemd scope naming</a></h4>
+ <h4><a id="systemdScope">Systemd scope naming</a></h4>
<p>
The systemd convention is for the scope name of virtual machines / containers
The scope names map directly to the cgroup directory names.
</p>
- <h4><a name="systemdSlice">Systemd slice naming</a></h4>
+ <h4><a id="systemdSlice">Systemd slice naming</a></h4>
<p>
The systemd convention for slice naming is that a slice should include the
by libvirt will be associated with <code>machine.slice</code> by default.
</p>
- <h4><a name="systemdLayout">Systemd cgroup layout</a></h4>
+ <h4><a id="systemdLayout">Systemd cgroup layout</a></h4>
<p>
Given this, a possible systemd cgroups layout involving 3 qemu guests,
+- machine-lxc\x2dcontainer3.scope
</pre>
- <h3><a name="currentLayoutGeneric">Non-systemd cgroups layout</a></h3>
+ <h3><a id="currentLayoutGeneric">Non-systemd cgroups layout</a></h3>
<p>
On hosts which do not use systemd, each consumer has a corresponding cgroup
+- container3.libvirt-lxc
</pre>
- <h2><a name="customPartiton">Using custom partitions</a></h2>
+ <h2><a id="customPartiton">Using custom partitions</a></h2>
<p>
If there is a need to apply resource constraints to groups of
later in this document did not support customization per guest.
</p>
- <h3><a name="createSystemd">Creating custom partitions (systemd)</a></h3>
+ <h3><a id="createSystemd">Creating custom partitions (systemd)</a></h3>
<p>
Given the XML config above, the admin on a systemd based host would
# systemctl start machine-testing.slice
</pre>
- <h3><a name="createNonSystemd">Creating custom partitions (non-systemd)</a></h3>
+ <h3><a id="createNonSystemd">Creating custom partitions (non-systemd)</a></h3>
<p>
Given the XML config above, the admin on a non-systemd based host
done
</pre>
- <h2><a name="resourceAPIs">Resource management APIs/commands</a></h2>
+ <h2><a id="resourceAPIs">Resource management APIs/commands</a></h2>
<p>
Since libvirt aims to provide an API which is portable across
network interfaces.
</p>
- <h2><a name="legacyLayout">Legacy cgroups layout</a></h2>
+ <h2><a id="legacyLayout">Legacy cgroups layout</a></h2>
<p>
Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
- <h1><a name="installation">libvirt Installation</a></h1>
+ <h1><a id="installation">libvirt Installation</a></h1>
<ul id="toc"></ul>
- <h2><a name="compiling">Compiling a release tarball</a></h2>
+ <h2><a id="compiling">Compiling a release tarball</a></h2>
<p>
libvirt uses the standard configure/make/install steps:
to update your list of installed shared libs.
</p>
- <h2><a name="building">Building from a GIT checkout</a></h2>
+ <h2><a id="building">Building from a GIT checkout</a></h2>
<p>
The libvirt build process uses GNU autotools, so after obtaining a
<ul id="toc"></ul>
- <h2><a name="security">Security Issues</a></h2>
+ <h2><a id="security">Security Issues</a></h2>
<p>
If you think that an issue with libvirt may have security
<a href="securityprocess.html">security process</a> instead.
</p>
- <h2><a name="email">Mailing lists</a></h2>
+ <h2><a id="email">Mailing lists</a></h2>
<p>
There are three mailing-lists:
page.
</p>
- <h2><a name="irc">IRC discussion</a></h2>
+ <h2><a id="irc">IRC discussion</a></h2>
<p>
Some of the libvirt developers may be found on IRC on the <a href="http://oftc.net">OFTC IRC</a>
<ul id="toc"></ul>
- <h2><a name="skills">Contributions required</a></h2>
+ <h2><a id="skills">Contributions required</a></h2>
<p>
The libvirt project is always looking for new contributors to
these help forums.</li>
</ul>
- <h2><a name="comms">Communication</a></h2>
+ <h2><a id="comms">Communication</a></h2>
<p>
For full details on contacting other project contributors
between contributors:
</p>
- <h3><a name="email">Mailing lists</a></h3>
+ <h3><a id="email">Mailing lists</a></h3>
<p>
The project has a number of
to follow the traffic.
</p>
- <h3><a name="irc">Instant messaging / chat</a></h3>
+ <h3><a id="irc">Instant messaging / chat</a></h3>
<p>
Contributors to libvirt are encouraged to join the
with others members.
</p>
- <h2><a name="outreach">Student / outreach coding programs</a></h2>
+ <h2><a id="outreach">Student / outreach coding programs</a></h2>
<p>
Since 2016, the libvirt project directly participates as an
<ul id="toc"></ul>
- <h2><a name="description">Description</a></h2>
+ <h2><a id="description">Description</a></h2>
<p>
The C# libvirt bindings are a class library. They use a Microsoft
<p> </p>
- <h2><a name="requirements">Requirements</a></h2>
+ <h2><a id="requirements">Requirements</a></h2>
<p>
These bindings depend upon the libvirt libraries being installed.
<p> </p>
<!-- 2010-10-19 JC: Commented out until we have C# tarballs to download
- <h2><a name="getting">Getting them</a></h2>
+ <h2><a id="getting">Getting them</a></h2>
<p>
The latest versions of the libvirt C# bindings can be downloaded from:
</ul>
-->
- <h2><a name="git">GIT source repository</a></h2>
+ <h2><a id="git">GIT source repository</a></h2>
<p>
The C# bindings source code is maintained in a <a
href="http://git-scm.com/">git</a> repository available on
<p> </p>
- <h2><a name="usage">Usage</a></h2>
+ <h2><a id="usage">Usage</a></h2>
<p>
The libvirt C# bindings class library exposes the <b>Libvirt</b>
<p> </p>
- <h2><a name="authors">Authors</a></h2>
+ <h2><a id="authors">Authors</a></h2>
<p>
The C# bindings are the work of Arnaud Champion
<p> </p>
- <h2><a name="notes">Test Configuration</a></h2>
+ <h2><a id="notes">Test Configuration</a></h2>
<p>
Testing is performed using the following configurations:
<p> </p>
- <h2><a name="type">Type Coverage</a></h2>
+ <h2><a id="type">Type Coverage</a></h2>
<p>
Coverage of the libvirt types is:
<p> </p>
- <h2><a name="funccover">Function Coverage</a></h2>
+ <h2><a id="funccover">Function Coverage</a></h2>
<p>
Coverage of the libvirt functions is:
<ul id="toc"></ul>
- <h2><a name="releases">Project modules</a></h2>
+ <h2><a id="releases">Project modules</a></h2>
<p>
The libvirt project maintains a number of inter-related modules beyond
<li><a href="https://libvirt.org/sources/">libvirt.org HTTPS server</a></li>
</ul>
- <h2><a name="hourly">Hourly development snapshots</a></h2>
+ <h2><a id="hourly">Hourly development snapshots</a></h2>
<p>
Once an hour, an automated snapshot is made from the git server
<li><a href="http://libvirt.org/sources/libvirt-git-snapshot.tar.xz">libvirt.org HTTP server</a></li>
</ul>
- <h2><a name="schedule">Primary release schedule</a></h2>
+ <h2><a id="schedule">Primary release schedule</a></h2>
<p>
The core libvirt module follows a time based plan, with releases made
independant ad-hoc releases with no fixed time schedle.
</p>
- <h2><a name="numbering">Release numbering</a></h2>
+ <h2><a id="numbering">Release numbering</a></h2>
<p>
Since libvirt 2.0.0, a time based version numbering rule
digits.
</p>
- <h2><a name="maintenance">Maintenance releases</a></h2>
+ <h2><a id="maintenance">Maintenance releases</a></h2>
<p>
In the git repository are several stable maintenance branches
for the core library, matching the
wiki page</a>.
</p>
- <h2><a name="git">GIT source repository</a></h2>
+ <h2><a id="git">GIT source repository</a></h2>
<p>
All modules maintained by the libvirt project have their primary
network and storage driver active.
</p>
- <h2><a name="hypervisor">Hypervisor drivers</a></h2>
+ <h2><a id="hypervisor">Hypervisor drivers</a></h2>
<p>
The hypervisor drivers currently supported by libvirt are:
<li><strong><a href="drvbhyve.html">Bhyve</a></strong> - The BSD Hypervisor</li>
</ul>
- <h2><a name="storage">Storage drivers</a></h2>
+ <h2><a id="storage">Storage drivers</a></h2>
<ul>
<li><strong><a href="storage.html#StorageBackendDir">Directory backend</a></strong></li>
Additional information on bhyve could be obtained on <a href="http://bhyve.org/">bhyve.org</a>.
</p>
-<h2><a name="uri">Connections to the Bhyve driver</a></h2>
+<h2><a id="uri">Connections to the Bhyve driver</a></h2>
<p>
The libvirt bhyve driver is a single-instance privileged driver. Some sample
connection URIs are:
bhyve+ssh://root@example.com/system (remote access, SSH tunnelled)
</pre>
-<h2><a name="exconfig">Example guest domain XML configurations</a></h2>
+<h2><a id="exconfig">Example guest domain XML configurations</a></h2>
<h3>Example config</h3>
<p>
<p>Please refer to the <a href="#uefi">UEFI</a> section for a more detailed explanation.</p>
-<h2><a name="usage">Guest usage / management</a></h2>
+<h2><a id="usage">Guest usage / management</a></h2>
-<h3><a name="console">Connecting to a guest console</a></h3>
+<h3><a id="console">Connecting to a guest console</a></h3>
<p>
Guest console connection is supported through the <code>nmdm</code> device. It could be enabled by adding
<pre>cu -l /dev/nmdm0B</pre>
-<h3><a name="xmltonative">Converting from domain XML to Bhyve args</a></h3>
+<h3><a id="xmltonative">Converting from domain XML to Bhyve args</a></h3>
<p>
The <code>virsh domxml-to-native</code> command can preview the actual
/usr/sbin/bhyve -c 2 -m 214 -A -I -H -P -s 0:0,hostbridge -s 3:0,virtio-net,tap0,mac=52:54:00:5d:74:e3 -s 2:0,virtio-blk,/home/user/vm1.img -s 1,lpc -l com1,/dev/nmdm0A vm1
</pre>
-<h3><a name="zfsvolume">Using ZFS volumes</a></h3>
+<h3><a id="zfsvolume">Using ZFS volumes</a></h3>
<p>It's possible to use ZFS volumes as disk devices <span class="since">since 1.2.8</span>.
An example of domain XML device entry for that will look like:</p>
<p>Please refer to the <a href="storage.html">Storage documentation</a> for more details on storage
management.</p>
-<h3><a name="grubbhyve">Using grub2-bhyve or Alternative Bootloaders</a></h3>
+<h3><a id="grubbhyve">Using grub2-bhyve or Alternative Bootloaders</a></h3>
<p>It's possible to boot non-FreeBSD guests by specifying an explicit
bootloader, e.g. <code>grub-bhyve(1)</code>. Arguments to the bootloader may be
<p>Caveat: <code>bootloader_args</code> does not support any quoting.
Filenames, etc, must not have spaces or they will be tokenized incorrectly.</p>
-<h3><a name="uefi">Using UEFI bootrom, VNC, and USB tablet</a></h3>
+<h3><a id="uefi">Using UEFI bootrom, VNC, and USB tablet</a></h3>
<p><span class="since">Since 3.2.0</span>, in addition to <a href="#grubbhyve">grub-bhyve</a>,
non-FreeBSD guests could be also booted using an UEFI boot ROM, provided both guest OS and
manual page and the <a href="https://wiki.freebsd.org/bhyve">bhyve wiki</a> for more details on using
the <code>vgaconf</code> option.</p>
-<h3><a name="clockconfig">Clock configuration</a></h3>
+<h3><a id="clockconfig">Clock configuration</a></h3>
<p>Originally bhyve supported only localtime for RTC. Support for UTC time was introduced in
<a href="http://svnweb.freebsd.org/changeset/base/284894">r284894</a> for <i>10-STABLE</i> and
</domain>
</pre>
-<h3><a name="e1000">e1000 NIC</a></h3>
+<h3><a id="e1000">e1000 NIC</a></h3>
<p>As of <a href="https://svnweb.freebsd.org/changeset/base/302504">r302504</a> bhyve
supports Intel e1000 network adapter emulation. It's supported in libvirt
connect to a VMware vCenter 2.5/4.x/5.x (VPX).
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
</li>
</ul>
- <h2><a name="prereq">Deployment pre-requisites</a></h2>
+ <h2><a id="prereq">Deployment pre-requisites</a></h2>
<p>
None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
preparations are required on the server side, no libvirtd must be
VMware vSphere API</a>.
</p>
- <h2><a name="uri">Connections to the VMware ESX driver</a></h2>
+ <h2><a id="uri">Connections to the VMware ESX driver</a></h2>
<p>
Some example remote connection URIs for the driver are:
</p>
</p>
- <h3><a name="uriformat">URI Format</a></h3>
+ <h3><a id="uriformat">URI Format</a></h3>
<p>
URIs have this general form (<code>[...]</code> marks an optional part).
</p>
</pre>
- <h4><a name="extraparams">Extra parameters</a></h4>
+ <h4><a id="extraparams">Extra parameters</a></h4>
<p>
Extra parameters can be added to a URI as part of the query string
(the part following <code>?</code>). A single parameter is formed by a
</table>
- <h3><a name="auth">Authentication</a></h3>
+ <h3><a id="auth">Authentication</a></h3>
<p>
In order to perform any useful operation the driver needs to log into
the ESX server. Therefore, only <code>virConnectOpenAuth</code> can be
</p>
- <h3><a name="certificates">Certificates for HTTPS</a></h3>
+ <h3><a id="certificates">Certificates for HTTPS</a></h3>
<p>
By default the ESX driver uses HTTPS to communicate with an ESX server.
Proper HTTPS communication requires correctly configured SSL
</ul>
- <h3><a name="connproblems">Connection problems</a></h3>
+ <h3><a id="connproblems">Connection problems</a></h3>
<p>
There are also other causes for connection problems than the
<a href="#certificates">HTTPS certificate</a> related ones.
</ul>
- <h2><a name="questions">Questions blocking tasks</a></h2>
+ <h2><a id="questions">Questions blocking tasks</a></h2>
<p>
Some methods of the VI API start tasks, for example
<code>PowerOnVM_Task()</code>. Such tasks may be blocked by questions
</p>
- <h2><a name="xmlspecial">Specialties in the domain XML config</a></h2>
+ <h2><a id="xmlspecial">Specialties in the domain XML config</a></h2>
<p>
There are several specialties in the domain XML config for ESX domains.
</p>
- <h3><a name="restrictions">Restrictions</a></h3>
+ <h3><a id="restrictions">Restrictions</a></h3>
<p>
There are some restrictions for some values of the domain XML config.
The driver will complain if this restrictions are violated.
</ul>
- <h3><a name="datastore">Datastore references</a></h3>
+ <h3><a id="datastore">Datastore references</a></h3>
<p>
Storage is managed in datastores. VMware uses a special path format to
reference files in a datastore. Basically, the datastore name is put
</p>
- <h3><a name="macaddresses">MAC addresses</a></h3>
+ <h3><a id="macaddresses">MAC addresses</a></h3>
<p>
VMware has registered two MAC address prefixes for domains:
<code>00:0c:29</code> and <code>00:50:56</code>. These prefixes are
</pre>
- <h3><a name="hardware">Available hardware</a></h3>
+ <h3><a id="hardware">Available hardware</a></h3>
<p>
VMware ESX supports different models of SCSI controllers and network
cards.
</pre>
- <h2><a name="importexport">Import and export of domain XML configs</a></h2>
+ <h2><a id="importexport">Import and export of domain XML configs</a></h2>
<p>
The ESX driver currently supports a native config format known as
<code>vmware-vmx</code> to handle VMware VMX configs.
</p>
- <h3><a name="xmlimport">Converting from VMware VMX config to domain XML config</a></h3>
+ <h3><a id="xmlimport">Converting from VMware VMX config to domain XML config</a></h3>
<p>
The <code>virsh domxml-from-native</code> provides a way to convert an
existing VMware VMX config into a domain XML config that can then be
</pre>
- <h3><a name="xmlexport">Converting from domain XML config to VMware VMX config</a></h3>
+ <h3><a id="xmlexport">Converting from domain XML config to VMware VMX config</a></h3>
<p>
The <code>virsh domxml-to-native</code> provides a way to convert a
domain XML config into a VMware VMX config.
</pre>
- <h2><a name="xmlconfig">Example domain XML configs</a></h2>
+ <h2><a id="xmlconfig">Example domain XML configs</a></h2>
<h3>Fedora11 on x86_64</h3>
<pre>
</pre>
- <h2><a name="migration">Migration</a></h2>
+ <h2><a id="migration">Migration</a></h2>
<p>
A migration cannot be initiated on an ESX server directly, a VMware
vCenter is necessary for this. The <code>vcenter</code> query
</pre>
- <h2><a name="scheduler">Scheduler configuration</a></h2>
+ <h2><a id="scheduler">Scheduler configuration</a></h2>
<p>
The driver exposes the ESX CPU scheduler. The parameters listed below
are available to control the scheduler.
</dl>
- <h2><a name="tools">VMware tools</a></h2>
+ <h2><a id="tools">VMware tools</a></h2>
<p>
Some actions require installed VMware tools. If the VMware tools are
not installed in the guest and one of the actions below is to be
</ul>
- <h2><a name="links">Links</a></h2>
+ <h2><a id="links">Links</a></h2>
<ul>
<li>
<a href="http://www.vmware.com/support/developer/vc-sdk/">
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
The <a href="http://www.microsoft.com/hyper-v-server/">Microsoft Hyper-V</a>
</ul>
- <h2><a name="uri">Connections to the Microsoft Hyper-V driver</a></h2>
+ <h2><a id="uri">Connections to the Microsoft Hyper-V driver</a></h2>
<p>
Some example remote connection URIs for the driver are:
</p>
</p>
- <h3><a name="uriformat">URI Format</a></h3>
+ <h3><a id="uriformat">URI Format</a></h3>
<p>
URIs have this general form (<code>[...]</code> marks an optional part).
</p>
</p>
- <h4><a name="extraparams">Extra parameters</a></h4>
+ <h4><a id="extraparams">Extra parameters</a></h4>
<p>
Extra parameters can be added to a URI as part of the query string
(the part following <code>?</code>). A single parameter is formed by a
</table>
- <h3><a name="auth">Authentication</a></h3>
+ <h3><a id="auth">Authentication</a></h3>
<p>
In order to perform any useful operation the driver needs to log into
the Hyper-V server. Therefore, only <code>virConnectOpenAuth</code> can
integration with control groups and many other features.
</p>
-<h2><a name="cgroups">Control groups Requirements</a></h2>
+<h2><a id="cgroups">Control groups Requirements</a></h2>
<p>
In order to control the resource usage of processes inside containers, the
libvirt <a href="cgroups.html">cgroups documentation</a>.
</p>
-<h2><a name="namespaces">Namespace requirements</a></h2>
+<h2><a id="namespaces">Namespace requirements</a></h2>
<p>
In order to separate processes inside a container from those in the
secure, in the absence of sVirt confinement.</strong>
</p>
-<h2><a name="init">Default container setup</a></h2>
+<h2><a id="init">Default container setup</a></h2>
-<h3><a name="cliargs">Command line arguments</a></h3>
+<h3><a id="cliargs">Command line arguments</a></h3>
<p>
When the container "init" process is started, it will typically
</os>
</pre>
-<h3><a name="envvars">Environment variables</a></h3>
+<h3><a id="envvars">Environment variables</a></h3>
<p>
When the container "init" process is started, it will be given several useful
container init process via the <code>initarg</code> config element.</dd>
</dl>
-<h3><a name="fsmounts">Filesystem mounts</a></h3>
+<h3><a id="fsmounts">Filesystem mounts</a></h3>
<p>
In the absence of any explicit configuration, the container will
</ul>
-<h3><a name="devnodes">Device nodes</a></h3>
+<h3><a id="devnodes">Device nodes</a></h3>
<p>
The container init process will be started with <code>CAP_MKNOD</code>
depending on their configuration.
</p>
-<h2><a name="security">Security considerations</a></h2>
+<h2><a id="security">Security considerations</a></h2>
<p>
The libvirt LXC driver is fairly flexible in how it can be configured,
writing a suitable configuration.
</p>
-<h3><a name="securenetworking">Network isolation</a></h3>
+<h3><a id="securenetworking">Network isolation</a></h3>
<p>
If the guest configuration does not list any network interfaces,
<code><features>....</features></code> element.
</p>
-<h3><a name="securefs">Filesystem isolation</a></h3>
+<h3><a id="securefs">Filesystem isolation</a></h3>
<p>
If the guest configuration does not list any filesystems, then
</p>
-<h3><a name="secureusers">User and group isolation</a></h3>
+<h3><a id="secureusers">User and group isolation</a></h3>
<p>
If the guest configuration does not list any ID mapping, then the
</p>
-<h2><a name="activation">Systemd Socket Activation Integration</a></h2>
+<h2><a id="activation">Systemd Socket Activation Integration</a></h2>
<p>
The libvirt LXC driver provides the ability to pass across pre-opened file
that a container is authorized to use.
</p>
-<h2><a name="exconfig">Example configurations</a></h2>
+<h2><a id="exconfig">Example configurations</a></h2>
<h3>Example config version 1</h3>
<p></p>
</domain>
</pre>
-<h2><a name="capabilities">Altering the available capabilities</a></h2>
+<h2><a id="capabilities">Altering the available capabilities</a></h2>
<p>
By default the libvirt LXC driver drops some capabilities among which CAP_MKNOD.
affect the security of the container and the host.
</p>
-<h2><a name="share">Inherit namespaces</a></h2>
+<h2><a id="share">Inherit namespaces</a></h2>
<p>
Libvirt allows you to inherit the namespace from container/process just like lxc tools
The use of namespace passthrough requires libvirt >= 1.2.19
</p>
-<h2><a name="usage">Container usage / management</a></h2>
+<h2><a id="usage">Container usage / management</a></h2>
<p>
As with any libvirt virtualization driver, LXC containers can be
manual page.
</p>
-<h3><a name="usageSave">Defining (saving) container configuration</a></h3>
+<h3><a id="usageSave">Defining (saving) container configuration</a></h3>
<p>
The <code>virsh define</code> command takes an XML configuration
# virsh -c lxc:/// define myguest.xml
</pre>
-<h3><a name="usageView">Viewing container configuration</a></h3>
+<h3><a id="usageView">Viewing container configuration</a></h3>
<p>
The <code>virsh dumpxml</code> command can be used to view the
# virsh -c lxc:/// dumpxml myguest
</pre>
-<h3><a name="usageStart">Starting containers</a></h3>
+<h3><a id="usageStart">Starting containers</a></h3>
<p>
The <code>virsh start</code> command can be used to start a
</pre>
-<h3><a name="usageStop">Stopping containers</a></h3>
+<h3><a id="usageStop">Stopping containers</a></h3>
<p>
The <code>virsh shutdown</code> command can be used
</pre>
-<h3><a name="usageReboot">Rebooting a container</a></h3>
+<h3><a id="usageReboot">Rebooting a container</a></h3>
<p>
The <code>virsh reboot</code> command can be used
# virsh -c lxc:/// reboot myguest
</pre>
-<h3><a name="usageDelete">Undefining (deleting) a container configuration</a></h3>
+<h3><a id="usageDelete">Undefining (deleting) a container configuration</a></h3>
<p>
The <code>virsh undefine</code> command can be used to delete the
# virsh -c lxc:/// undefine myguest
</pre>
-<h3><a name="usageConnect">Connecting to a container console</a></h3>
+<h3><a id="usageConnect">Connecting to a container console</a></h3>
<p>
The <code>virsh console</code> command can be used to connect
# virsh -c lxc:/// console myguest --devname console1
</pre>
-<h3><a name="usageEnter">Running commands in a container</a></h3>
+<h3><a id="usageEnter">Running commands in a container</a></h3>
<p>
The <code>virsh lxc-enter-namespace</code> command can be used
# virsh -c lxc:/// lxc-enter-namespace myguest -- /bin/ls -al /dev
</pre>
-<h3><a name="usageTop">Monitoring container utilization</a></h3>
+<h3><a id="usageTop">Monitoring container utilization</a></h3>
<p>
The <code>virt-top</code> command can be used to monitor the
# virt-top -c lxc:///
</pre>
-<h3><a name="usageConvert">Converting LXC container configuration</a></h3>
+<h3><a id="usageConvert">Converting LXC container configuration</a></h3>
<p>
The <code>virsh domxml-from-native</code> command can be used to convert
<ul id="toc"/>
- <h2><a name="PCI">PCI host devices</a></h2>
+ <h2><a id="PCI">PCI host devices</a></h2>
<dl>
<dt><code>capability</code></dt>
<dd>
element will be included for each capability the device supports.
</p>
- <h3><a name="SRIOVCap">SR-IOV capability</a></h3>
+ <h3><a id="SRIOVCap">SR-IOV capability</a></h3>
<p>
Single root input/output virtualization (SR-IOV) allows sharing of the
PCIe resources by multiple virtual environments. That is achieved by
...
<device></pre>
- <h3><a name="MDEVCap">MDEV capability</a></h3>
+ <h3><a id="MDEVCap">MDEV capability</a></h3>
<p>
A PCI device capable of creating mediated devices will include a nested
capability <code>mdev_types</code> which enumerates all supported mdev
</capability>
</device></pre>
- <h2><a name="MDEV">Mediated devices (MDEVs)</a></h2>
+ <h2><a id="MDEV">Mediated devices (MDEVs)</a></h2>
<p>
Mediated devices (<span class="since">Since 3.2.0</span>) are software
devices defining resource allocation on the backing physical device which
undue trouble.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
</li>
</ul>
- <h2><a name="connections">Connections to OpenVZ driver</a></h2>
+ <h2><a id="connections">Connections to OpenVZ driver</a></h2>
<p>
The libvirt OpenVZ driver is a single-instance privileged driver,
openvz+ssh://root@example.com/system (remote access, SSH tunnelled)
</pre>
- <h2><a name="notes">Notes on bridged networking</a></h2>
+ <h2><a id="notes">Notes on bridged networking</a></h2>
<p>
Bridged networking enables a guest domain (ie container) to have its
the host OS.
</p>
- <h3><a name="host">Host network devices</a></h3>
+ <h3><a id="host">Host network devices</a></h3>
<p>
One or more of the physical devices must be attached to a bridge. The
physical device "eth0", or a bonding device "bond0".
</p>
- <h3><a name="tools">OpenVZ tools configuration</a></h3>
+ <h3><a id="tools">OpenVZ tools configuration</a></h3>
<p>
OpenVZ releases later than 3.0.23 ship with a standard network device
</p>
- <h2><a name="example">Example guest domain XML configuration</a></h2>
+ <h2><a id="example">Example guest domain XML configuration</a></h2>
<p>
The current libvirt OpenVZ driver has a restriction that the
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
The <a href="http://www-03.ibm.com/systems/power/software/virtualization/index.html">IBM
</ul>
- <h2><a name="uri">Connections to the PowerVM driver</a></h2>
+ <h2><a id="uri">Connections to the PowerVM driver</a></h2>
<p>
Some example remote connection URIs for the driver are:
</p>
</p>
- <h3><a name="uriformat">URI Format</a></h3>
+ <h3><a id="uriformat">URI Format</a></h3>
<p>
URIs have this general form (<code>[...]</code> marks an
optional part, <code>{...|...}</code> marks a mandatory choice).
version 0.12.0 or later.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
</li>
</ul>
- <h2><a name="prereq">Deployment pre-requisites</a></h2>
+ <h2><a id="prereq">Deployment pre-requisites</a></h2>
<ul>
<li>
</li>
</ul>
- <h2><a name="uris">Connections to QEMU driver</a></h2>
+ <h2><a id="uris">Connections to QEMU driver</a></h2>
<p>
The libvirt QEMU driver is a multi-instance driver, providing a single
qemu+ssh://root@example.com/system (remote access, SSH tunnelled)
</pre>
- <h2><a name="security">Driver security architecture</a></h2>
+ <h2><a id="security">Driver security architecture</a></h2>
<p>
There are multiple layers to security in the QEMU driver, allowing for
flexibility in the use of QEMU based virtual machines.
</p>
- <h3><a name="securitydriver">Driver instances</a></h3>
+ <h3><a id="securitydriver">Driver instances</a></h3>
<p>
As explained above there are two ways to access the QEMU driver
elevated privileges.
</p>
- <h3><a name="securitydac">POSIX users/groups</a></h3>
+ <h3><a id="securitydac">POSIX users/groups</a></h3>
<p>
In the "session" instance, the POSIX users/groups model restricts QEMU
</li>
</ul>
- <h3><a name="securitycap">Linux process capabilities</a></h3>
+ <h3><a id="securitycap">Linux process capabilities</a></h3>
<p>
The libvirt QEMU driver has a build time option allowing it to use
to changing the <code>/etc/libvirt/qemu.conf</code> settings.
</p>
- <h3><a name="securityselinux">SELinux basic confinement</a></h3>
+ <h3><a id="securityselinux">SELinux basic confinement</a></h3>
<p>
The basic SELinux protection for QEMU virtual machines is intended to
SELinux boolean.
</p>
- <h3><a name="securitysvirt">SELinux sVirt confinement</a></h3>
+ <h3><a id="securitysvirt">SELinux sVirt confinement</a></h3>
<p>
The SELinux sVirt protection for QEMU virtual machines builds to the
file can be used to change the setting to <code>security_driver="none"</code>
</p>
- <h3><a name="securitysvirtaa">AppArmor sVirt confinement</a></h3>
+ <h3><a id="securitysvirtaa">AppArmor sVirt confinement</a></h3>
<p>
When using basic AppArmor protection for the libvirtd daemon and
</p>
- <h3><a name="securityacl">Cgroups device ACLs</a></h3>
+ <h3><a id="securityacl">Cgroups device ACLs</a></h3>
<p>
Recent Linux kernels have a capability known as "cgroups" which is used
<code>/dev/cgroup/libvirt/qemu/$VMNAME/</code>
</p>
- <h2><a name="imex">Import and export of libvirt domain XML configs</a></h2>
+ <h2><a id="imex">Import and export of libvirt domain XML configs</a></h2>
<p>The QEMU driver currently supports a single native
config format known as <code>qemu-argv</code>. The data for this format
then the QEMu binary name, finally followed by the QEMU command line
arguments</p>
- <h3><a name="xmlimport">Converting from QEMU args to domain XML</a></h3>
+ <h3><a id="xmlimport">Converting from QEMU args to domain XML</a></h3>
<p>
The <code>virsh domxml-from-native</code> provides a way to
<p>NB, don't include the literal \ in the args, put everything on one line</p>
- <h3><a name="xmlexport">Converting from domain XML to QEMU args</a></h3>
+ <h3><a id="xmlexport">Converting from domain XML to QEMU args</a></h3>
<p>
The <code>virsh domxml-to-native</code> provides a way to convert a
-serial none -parallel none -usb
</pre>
- <h2><a name="qemucommand">Pass-through of arbitrary qemu
+ <h2><a id="qemucommand">Pass-through of arbitrary qemu
commands</a></h2>
<p>Libvirt provides an XML namespace and an optional
</domain>
</pre>
- <h2><a name="xmlconfig">Example domain XML config</a></h2>
+ <h2><a id="xmlconfig">Example domain XML config</a></h2>
<h3>QEMU emulated guest on x86_64</h3>
has pre-created TAP devices.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
from version 2.2 onwards.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
work is completed to get the libvirtd daemon working there.</strong>
</p>
- <h2><a name="xmlconfig">Example domain XML config</a></h2>
+ <h2><a id="xmlconfig">Example domain XML config</a></h2>
<pre>
<domain type='vbox'>
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
The <a href="http://www.odin.com/products/virtuozzo/">Virtuozzo</a> Solution.
</ul>
- <h2><a name="uri">Connections to the Virtuozzo driver</a></h2>
+ <h2><a id="uri">Connections to the Virtuozzo driver</a></h2>
<p>
The libvirt Virtuozzo driver is a single-instance privileged driver, with a driver name of 'virtuozzo'. Some example connection URIs for the libvirt driver are:
</p>
vz+ssh://root@example.com/system (remote access, SSH tunnelled)
</pre>
- <h2><a name="example">Example guest domain XML configuration</a></h2>
+ <h2><a id="example">Example guest domain XML configuration</a></h2>
<p>
Virtuozzo driver require at least one hard disk for new domains
from <a href="http://www.vmware.com/support/developer/vix-api/">here</a>.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
vmwarews+ssh://user@example.com/session (remote access to VMware Workstation, SSH tunnelled)
</pre>
- <h2><a name="xmlconfig">Example domain XML config</a></h2>
+ <h2><a id="xmlconfig">Example domain XML config</a></h2>
<pre>
<domain type='vmware'>
on any Xen release from 3.0.1 onwards.
</p>
- <h2><a name="project">Project Links</a></h2>
+ <h2><a id="project">Project Links</a></h2>
<ul>
<li>
</li>
</ul>
- <h2><a name="prereq">Deployment pre-requisites</a></h2>
+ <h2><a id="prereq">Deployment pre-requisites</a></h2>
<p>
The libvirt Xen driver uses a combination of channels to manage Xen
</li>
</ul>
- <h2><a name="uri">Connections to Xen driver</a></h2>
+ <h2><a id="uri">Connections to Xen driver</a></h2>
<p>
The libvirt Xen driver is a single-instance privileged driver,
xen+ssh://root@example.com/ (remote access, SSH tunnelled)
</pre>
- <h2><a name="imex">Import and export of libvirt domain XML configs</a></h2>
+ <h2><a id="imex">Import and export of libvirt domain XML configs</a></h2>
<p>The Xen driver currently supports two native
config formats. The first known as <code>xen-xm</code> is the format
known as <code>xen-sxpr</code>, is the format used for interacting
with the XenD's legacy HTTP RPC service.</p>
- <h3><a name="xmlimport">Converting from XM config files to domain XML</a></h3>
+ <h3><a id="xmlimport">Converting from XM config files to domain XML</a></h3>
<p>
The <code>virsh domxml-from-native</code> provides a way to convert an
</devices>
</domain></pre>
- <h3><a name="xmlexport">Converting from domain XML to XM config files</a></h3>
+ <h3><a id="xmlexport">Converting from domain XML to XM config files</a></h3>
<p>
The <code>virsh domxml-to-native</code> provides a way to convert a
disk = [ "tap:aio:/var/lib/xen/images/rhel5pv.img,xvda,w", "tap:qcow:/root/qcow1-xen.img,xvdd,w" ]
vif = [ "mac=00:16:3e:60:36:ba,bridge=virbr0,script=vif-bridge,vifname=vif5.0" ]</pre>
- <h2><a name="xmlconfig">Example domain XML config</a></h2>
+ <h2><a id="xmlconfig">Example domain XML config</a></h2>
<p>
Below are some example XML configurations for Xen guest domains.
</li>
</ul>
- <h3><a name="name-fw-virtual-network-driver"
- id="id-fw-virtual-network-driver">The virtual network driver</a>
+ <h3><a id="fw-virtual-network-driver">The virtual network driver</a>
</h3>
<p>The typical configuration for guests is to use bridging of the
physical NIC on the host to connect the guest directly to the LAN.
</li>
</ul>
- <h3><a name="name-fw-network-filter-driver"
- id="id-fw-network-filter-driver">The network filter driver</a>
+ <h3><a id="fw-network-filter-driver">The network filter driver</a>
</h3>
<p>This driver provides a fully configurable network filtering capability
that leverages ebtables, iptables and ip6tables. This was written by
<ul id="toc"></ul>
- <h2><a name="elements">Element and attribute overview</a></h2>
+ <h2><a id="elements">Element and attribute overview</a></h2>
<p>As new virtualization engine support gets added to libvirt, and to
handle cases like QEMU supporting a variety of emulations, a query
the set of architectures the host can run at the moment.</p>
- <h3><a name="elementHost">Host capabilities</a></h3>
+ <h3><a id="elementHost">Host capabilities</a></h3>
<p>The <code><host/></code> element consists of the following child
elements:</p>
</dl>
- <h3><a name="elementGuest">Guest capabilities</a></h3>
+ <h3><a id="elementGuest">Guest capabilities</a></h3>
<p>While the <a href="#elementHost">previous section</a> aims at host
capabilities, this one focuses on capabilities available to a guest
</dd>
</dl>
- <h3><a name="elementExamples">Examples</a></h3>
+ <h3><a id="elementExamples">Examples</a></h3>
<p>For example, in the case of a 64-bit machine with hardware
virtualization capabilities enabled in the chip and
</p>
- <h2><a name="elements">Element and attribute overview</a></h2>
+ <h2><a id="elements">Element and attribute overview</a></h2>
<p>
The root element required for all virtual machines is
</p>
- <h3><a name="elementsMetadata">General metadata</a></h3>
+ <h3><a id="elementsMetadata">General metadata</a></h3>
<pre>
<domain type='xen' id='3'>
element). <span class="since">Since 0.9.10</span></dd>
</dl>
- <h3><a name="elementsOS">Operating system booting</a></h3>
+ <h3><a id="elementsOS">Operating system booting</a></h3>
<p>
There are a number of different ways to boot virtual machines
each with their own pros and cons.
</p>
- <h4><a name="elementsOSBIOS">BIOS bootloader</a></h4>
+ <h4><a id="elementsOSBIOS">BIOS bootloader</a></h4>
<p>
Booting via the BIOS is available for hypervisors supporting
</dd>
</dl>
- <h4><a name="elementsOSBootloader">Host bootloader</a></h4>
+ <h4><a id="elementsOSBootloader">Host bootloader</a></h4>
<p>
Hypervisors employing paravirtualization do not usually emulate
</dl>
- <h4><a name="elementsOSKernel">Direct kernel boot</a></h4>
+ <h4><a id="elementsOSKernel">Direct kernel boot</a></h4>
<p>
When installing a new guest OS it is often useful to boot directly
<span class="since">Since 1.3.5 (QEMU only)</span></dd>
</dl>
- <h4><a name="elementsOSContainer">Container boot</a></h4>
+ <h4><a id="elementsOSContainer">Container boot</a></h4>
<p>
When booting a domain using container based virtualization, instead
</pre>
- <h3><a name="elementsSysinfo">SMBIOS System Information</a></h3>
+ <h3><a id="elementsSysinfo">SMBIOS System Information</a></h3>
<p>
Some hypervisors allow control over what system information is
</dd>
</dl>
- <h3><a name="elementsCPUAllocation">CPU Allocation</a></h3>
+ <h3><a id="elementsCPUAllocation">CPU Allocation</a></h3>
<pre>
<domain>
</dd>
</dl>
- <h3><a name="elementsIOThreadsAllocation">IOThreads Allocation</a></h3>
+ <h3><a id="elementsIOThreadsAllocation">IOThreads Allocation</a></h3>
<p>
IOThreads are dedicated event loop threads for supported disk
devices to perform block I/O requests in order to improve
</dd>
</dl>
- <h3><a name="elementsCPUTuning">CPU Tuning</a></h3>
+ <h3><a id="elementsCPUTuning">CPU Tuning</a></h3>
<pre>
<domain>
</dl>
- <h3><a name="elementsMemoryAllocation">Memory Allocation</a></h3>
+ <h3><a id="elementsMemoryAllocation">Memory Allocation</a></h3>
<pre>
<domain>
</dl>
- <h3><a name="elementsMemoryBacking">Memory Backing</a></h3>
+ <h3><a id="elementsMemoryBacking">Memory Backing</a></h3>
<pre>
<domain>
</dl>
- <h3><a name="elementsMemoryTuning">Memory Tuning</a></h3>
+ <h3><a id="elementsMemoryTuning">Memory Tuning</a></h3>
<pre>
<domain>
</dl>
- <h3><a name="elementsNUMATuning">NUMA Node Tuning</a></h3>
+ <h3><a id="elementsNUMATuning">NUMA Node Tuning</a></h3>
<pre>
<domain>
</dl>
- <h3><a name="elementsBlockTuning">Block I/O Tuning</a></h3>
+ <h3><a id="elementsBlockTuning">Block I/O Tuning</a></h3>
<pre>
<domain>
...
</dl></dd></dl>
- <h3><a name="resPartition">Resource partitioning</a></h3>
+ <h3><a id="resPartition">Resource partitioning</a></h3>
<p>
Hypervisors may allow for virtual machines to be placed into
in all mounted controllers. <span class="since">Since 1.0.5</span>
</p>
- <h3><a name="elementsCPU">CPU model and topology</a></h3>
+ <h3><a id="elementsCPU">CPU model and topology</a></h3>
<p>
Requirements for CPU model, its features and topology can be specified
This guest NUMA specification is currently available only for QEMU/KVM.
</p>
- <h3><a name="elementsEvents">Events configuration</a></h3>
+ <h3><a id="elementsEvents">Events configuration</a></h3>
<p>
It is sometimes necessary to override the default actions taken
<dd>Keep the domain running as if nothing happened.</dd>
</dl>
- <h3><a name="elementsPowerManagement">Power Management</a></h3>
+ <h3><a id="elementsPowerManagement">Power Management</a></h3>
<p>
<span class="since">Since 0.10.2</span> it is possible to
left with its default value.</dd>
</dl>
- <h3><a name="elementsFeatures">Hypervisor features</a></h3>
+ <h3><a id="elementsFeatures">Hypervisor features</a></h3>
<p>
Hypervisors may allow certain CPU / machine features to be
</dd>
</dl>
- <h3><a name="elementsTime">Time keeping</a></h3>
+ <h3><a id="elementsTime">Time keeping</a></h3>
<p>
The guest clock is typically initialized from the host clock.
</dd>
</dl>
- <h3><a name="elementsPerf">Performance monitoring events</a></h3>
+ <h3><a id="elementsPerf">Performance monitoring events</a></h3>
<p>
Some platforms allow monitoring of performance of the virtual machine and
</tr>
</table>
- <h3><a name="elementsDevices">Devices</a></h3>
+ <h3><a id="elementsDevices">Devices</a></h3>
<p>
The final set of XML elements are all used to describe devices
</dd>
</dl>
- <h4><a name="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
+ <h4><a id="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
<p>
Any device that looks like a disk, be it a floppy, harddisk,
</dd>
</dl>
- <h4><a name="elementsFilesystems">Filesystems</a></h4>
+ <h4><a id="elementsFilesystems">Filesystems</a></h4>
<p>
A directory on the host that can be accessed directly from the guest.
</dd>
</dl>
- <h4><a name="elementsAddress">Device Addresses</a></h4>
+ <h4><a id="elementsAddress">Device Addresses</a></h4>
<p>
Many devices have an optional <code><address></code>
</dd>
</dl>
- <h4><a name="elementsVirtio">Virtio-related options</a></h4>
+ <h4><a id="elementsVirtio">Virtio-related options</a></h4>
<p>
QEMU's virtio devices have some attributes related to the virtio transport under
<span class="since">Since 3.5.0</span>
</p>
- <h4><a name="elementsControllers">Controllers</a></h4>
+ <h4><a id="elementsControllers">Controllers</a></h4>
<p>
Depending on the guest architecture, some device buses can
</devices>
...</pre>
- <h4><a name="elementsLease">Device leases</a></h4>
+ <h4><a id="elementsLease">Device leases</a></h4>
<p>
When using a lock manager, it may be desirable to record device leases
</dd>
</dl>
- <h4><a name="elementsHostDev">Host device assignment</a></h4>
+ <h4><a id="elementsHostDev">Host device assignment</a></h4>
- <h5><a name="elementsHostDevSubsys">USB / PCI / SCSI devices</a></h5>
+ <h5><a id="elementsHostDevSubsys">USB / PCI / SCSI devices</a></h5>
<p>
USB, PCI and SCSI devices attached to the host can be passed through
</dl>
- <h5><a name="elementsHostDevCaps">Block / character devices</a></h5>
+ <h5><a id="elementsHostDevCaps">Block / character devices</a></h5>
<p>
Block / character devices from the host can be passed through
</dd>
</dl>
- <h4><a name="elementsRedir">Redirected devices</a></h4>
+ <h4><a id="elementsRedir">Redirected devices</a></h4>
<p>
USB device redirection through a character device is
</dd>
</dl>
- <h4><a name="elementsSmartcard">Smartcard devices</a></h4>
+ <h4><a id="elementsSmartcard">Smartcard devices</a></h4>
<p>
A virtual smartcard device can be supplied to the guest via the
smartcard, with an address of bus=0 slot=0.
</p>
- <h4><a name="elementsNICS">Network interfaces</a></h4>
+ <h4><a id="elementsNICS">Network interfaces</a></h4>
<pre>
...
as <a href="#elementsAddress">documented above</a>.
</p>
- <h5><a name="elementsNICSVirtual">Virtual network</a></h5>
+ <h5><a id="elementsNICSVirtual">Virtual network</a></h5>
<p>
<strong><em>
</devices>
...</pre>
- <h5><a name="elementsNICSBridge">Bridge to LAN</a></h5>
+ <h5><a id="elementsNICSBridge">Bridge to LAN</a></h5>
<p>
<strong><em>
</devices>
...</pre>
- <h5><a name="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
+ <h5><a id="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
<p>
Provides a virtual LAN with NAT to the outside world. The virtual
...</pre>
- <h5><a name="elementsNICSEthernet">Generic ethernet connection</a></h5>
+ <h5><a id="elementsNICSEthernet">Generic ethernet connection</a></h5>
<p>
Provides a means for the administrator to execute an arbitrary script
</devices>
...</pre>
- <h5><a name="elementsNICSDirect">Direct attachment to physical interface</a></h5>
+ <h5><a id="elementsNICSDirect">Direct attachment to physical interface</a></h5>
<p>
Provides direct attachment of the virtual machine's NIC to the given
</pre>
- <h5><a name="elementsNICSHostdev">PCI Passthrough</a></h5>
+ <h5><a id="elementsNICSHostdev">PCI Passthrough</a></h5>
<p>
A PCI network device (specified by the <source> element)
...</pre>
- <h5><a name="elementsNICSMulticast">Multicast tunnel</a></h5>
+ <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
<p>
A multicast group is setup to represent a virtual network. Any VMs
</devices>
...</pre>
- <h5><a name="elementsNICSTCP">TCP tunnel</a></h5>
+ <h5><a id="elementsNICSTCP">TCP tunnel</a></h5>
<p>
A TCP client/server architecture provides a virtual network. One VM
</devices>
...</pre>
- <h5><a name="elementsNICSUDP">UDP unicast tunnel</a></h5>
+ <h5><a id="elementsNICSUDP">UDP unicast tunnel</a></h5>
<p>
A UDP unicast architecture provides a virtual network which enables
</devices>
...</pre>
- <h5><a name="elementsNICSModel">Setting the NIC model</a></h5>
+ <h5><a id="elementsNICSModel">Setting the NIC model</a></h5>
<pre>
...
ne2k_isa i82551 i82557b i82559er ne2k_pci pcnet rtl8139 e1000 virtio
</p>
- <h5><a name="elementsDriverBackendOptions">Setting NIC driver-specific options</a></h5>
+ <h5><a id="elementsDriverBackendOptions">Setting NIC driver-specific options</a></h5>
<pre>
...
</dd>
</dl>
- <h5><a name="elementsBackendOptions">Setting network backend-specific options</a></h5>
+ <h5><a id="elementsBackendOptions">Setting network backend-specific options</a></h5>
<pre>
...
adjust the size of send buffer in the host. <span class="since">Since
0.8.8</span>
</p>
- <h5><a name="elementsNICSTargetOverride">Overriding the target element</a></h5>
+ <h5><a id="elementsNICSTargetOverride">Overriding the target element</a></h5>
<pre>
...
</devices>
...</pre>
- <h5><a name="elementsNICSBoot">Specifying boot order</a></h5>
+ <h5><a id="elementsNICSBoot">Specifying boot order</a></h5>
<pre>
...
<span class="since">Since 0.8.8</span>
</p>
- <h5><a name="elementsNICSROM">Interface ROM BIOS configuration</a></h5>
+ <h5><a id="elementsNICSROM">Interface ROM BIOS configuration</a></h5>
<pre>
...
network device.
<span class="since">Since 0.9.10 (QEMU and KVM only)</span>.
</p>
- <h5><a name="elementDomain">Setting up a network backend in a driver domain</a></h5>
+ <h5><a id="elementDomain">Setting up a network backend in a driver domain</a></h5>
<pre>
...
<devices>
<span class="since">Since 1.2.13 (Xen only)</span>
</p>
- <h5><a name="elementQoS">Quality of service</a></h5>
+ <h5><a id="elementQoS">Quality of service</a></h5>
<pre>
...
the Network XML.
</p>
- <h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
+ <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
<pre>
...
traffic for that VLAN will be tagged.
</p>
- <h5><a name="elementLink">Modifying virtual link state</a></h5>
+ <h5><a id="elementLink">Modifying virtual link state</a></h5>
<pre>
...
<devices>
<span class="since">Since 0.9.5</span>
</p>
- <h5><a name="mtu">MTU configuration</a></h5>
+ <h5><a id="mtu">MTU configuration</a></h5>
<pre>
...
<devices>
<span class="since">Since 3.1.0</span>
</p>
- <h5><a name="coalesce">Coalesce settings</a></h5>
+ <h5><a id="coalesce">Coalesce settings</a></h5>
<pre>
...
<devices>
<span class="since">Since 3.3.0</span>
</p>
- <h5><a name="ipconfig">IP configuration</a></h5>
+ <h5><a id="ipconfig">IP configuration</a></h5>
<pre>
...
<devices>
configure the guest side of the interface (described above).
</p>
- <h5><a name="elementVhostuser">vhost-user interface</a></h5>
+ <h5><a id="elementVhostuser">vhost-user interface</a></h5>
<p>
<span class="since">Since 1.2.7</span> the vhost-user enables the
<code><model></code> element is mandatory.
</p>
- <h5><a name="elementNwfilter">Traffic filtering with NWFilter</a></h5>
+ <h5><a id="elementNwfilter">Traffic filtering with NWFilter</a></h5>
<p>
<span class="since">Since 0.8.0</span> an <code>nwfilter</code> profile
</p>
- <h4><a name="elementsInput">Input devices</a></h4>
+ <h4><a id="elementsInput">Input devices</a></h4>
<p>
Input devices allow interaction with the graphical framebuffer
set. (<span class="since">Since 3.5.0</span>)
</p>
- <h4><a name="elementsHub">Hub devices</a></h4>
+ <h4><a id="elementsHub">Hub devices</a></h4>
<p>
A hub is a device that expands a single port into several so
above</a>.
</p>
- <h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
+ <h4><a id="elementsGraphics">Graphical framebuffers</a></h4>
<p>
A graphics device allows for graphical interaction with the
</dd>
</dl>
- <h4><a name="elementsVideo">Video devices</a></h4>
+ <h4><a id="elementsVideo">Video devices</a></h4>
<p>
A video device.
</p>
</dd>
</dl>
- <h4><a name="elementsConsole">Consoles, serial, parallel & channel devices</a></h4>
+ <h4><a id="elementsConsole">Consoles, serial, parallel & channel devices</a></h4>
<p>
A character device provides a way to interact with the virtual machine.
slot.
</p>
- <h5><a name="elementsCharGuestInterface">Guest interface</a></h5>
+ <h5><a id="elementsCharGuestInterface">Guest interface</a></h5>
<p>
A character device presents itself to the guest as one of the following
types.
</p>
- <h6><a name="elementCharParallel">Parallel port</a></h6>
+ <h6><a id="elementCharParallel">Parallel port</a></h6>
<pre>
...
usually 0, 1 or 2 parallel ports.
</p>
- <h6><a name="elementCharSerial">Serial port</a></h6>
+ <h6><a id="elementCharSerial">Serial port</a></h6>
<pre>
...
<code>type='pci'</code> to select desired location on the PCI bus.
</p>
- <h6><a name="elementCharConsole">Console</a></h6>
+ <h6><a id="elementCharConsole">Console</a></h6>
<p>
The console element is used to represent interactive consoles. Depending
only 1 console.
</p>
- <h6><a name="elementCharChannel">Channel</a></h6>
+ <h6><a id="elementCharChannel">Channel</a></h6>
<p>
This represents a private communication channel between the host and the
<span class="since">Since 0.8.8</span></dd>
</dl>
- <h5><a name="elementsCharHostInterface">Host interface</a></h5>
+ <h5><a id="elementsCharHostInterface">Host interface</a></h5>
<p>
A character device presents itself to the host as one of the following
types.
</p>
- <h6><a name="elementsCharSTDIO">Domain logfile</a></h6>
+ <h6><a id="elementsCharSTDIO">Domain logfile</a></h6>
<p>
This disables all input on the character device, and sends output
...</pre>
- <h6><a name="elementsCharFle">Device logfile</a></h6>
+ <h6><a id="elementsCharFle">Device logfile</a></h6>
<p>
A file is opened and all data sent to the character
</devices>
...</pre>
- <h6><a name="elementsCharVC">Virtual console</a></h6>
+ <h6><a id="elementsCharVC">Virtual console</a></h6>
<p>
Connects the character device to the graphical framebuffer in
</devices>
...</pre>
- <h6><a name="elementsCharNull">Null device</a></h6>
+ <h6><a id="elementsCharNull">Null device</a></h6>
<p>
Connects the character device to the void. No data is ever
</devices>
...</pre>
- <h6><a name="elementsCharPTY">Pseudo TTY</a></h6>
+ <h6><a id="elementsCharPTY">Pseudo TTY</a></h6>
<p>
A Pseudo TTY is allocated using /dev/ptmx. A suitable client
with existing syntax for <console> tags.
</p>
- <h6><a name="elementsCharHost">Host device proxy</a></h6>
+ <h6><a id="elementsCharHost">Host device proxy</a></h6>
<p>
The character device is passed through to the underlying
</devices>
...</pre>
- <h6><a name="elementsCharPipe">Named pipe</a></h6>
+ <h6><a id="elementsCharPipe">Named pipe</a></h6>
<p>
The character device writes output to a named pipe. See pipe(7) for
</devices>
...</pre>
- <h6><a name="elementsCharTCP">TCP client/server</a></h6>
+ <h6><a id="elementsCharTCP">TCP client/server</a></h6>
<p>
The character device acts as a TCP client connecting to a
</devices>
...</pre>
- <h6><a name="elementsCharUDP">UDP network console</a></h6>
+ <h6><a id="elementsCharUDP">UDP network console</a></h6>
<p>
The character device acts as a UDP netconsole service,
</devices>
...</pre>
- <h6><a name="elementsCharUNIX">UNIX domain socket client/server</a></h6>
+ <h6><a id="elementsCharUNIX">UNIX domain socket client/server</a></h6>
<p>
The character device acts as a UNIX domain socket server,
</devices>
...</pre>
- <h6><a name="elementsCharSpiceport">Spice channel</a></h6>
+ <h6><a id="elementsCharSpiceport">Spice channel</a></h6>
<p>
The character device is accessible through spice connection
</devices>
...</pre>
- <h6><a name="elementsNmdm">Nmdm device</a></h6>
+ <h6><a id="elementsNmdm">Nmdm device</a></h6>
<p>
The nmdm device driver, available on FreeBSD, provides two
to the guest console. Device is specified by a fully qualified path.</dd>
</dl>
- <h4><a name="elementsSound">Sound devices</a></h4>
+ <h4><a id="elementsSound">Sound devices</a></h4>
<p>
A virtual sound card can be attached to the host via the
slot, <a href="#elementsAddress">documented above</a>.
</p>
- <h4><a name="elementsWatchdog">Watchdog device</a></h4>
+ <h4><a id="elementsWatchdog">Watchdog device</a></h4>
<p>
A virtual hardware watchdog device can be added to the guest via
</dd>
</dl>
- <h4><a name="elementsMemBalloon">Memory balloon device</a></h4>
+ <h4><a id="elementsMemBalloon">Memory balloon device</a></h4>
<p>
A virtual memory balloon device is added to all Xen and KVM/QEMU
set. (<span class="since">Since 3.5.0</span>)
</dd>
</dl>
- <h4><a name="elementsRng">Random number generator device</a></h4>
+ <h4><a id="elementsRng">Random number generator device</a></h4>
<p>
The virtual random number generator device allows the host to pass
</dl>
- <h4><a name="elementsTpm">TPM device</a></h4>
+ <h4><a id="elementsTpm">TPM device</a></h4>
<p>
The TPM device enables a QEMU guest to have access to TPM
</dd>
</dl>
- <h4><a name="elementsNVRAM">NVRAM device</a></h4>
+ <h4><a id="elementsNVRAM">NVRAM device</a></h4>
<p>
nvram device is always added to pSeries guest on PPC64, and its address
is allowed to be changed. Element <code>nvram</code> (only valid for
</dd>
</dl>
- <h4><a name="elementsPanic">panic device</a></h4>
+ <h4><a id="elementsPanic">panic device</a></h4>
<p>
panic device enables libvirt to receive panic notification from a QEMU
guest.
</dd>
</dl>
- <h4><a name="elementsShmem">Shared memory device</a></h4>
+ <h4><a id="elementsShmem">Shared memory device</a></h4>
<p>
A shared memory device allows to share a memory region between
</dd>
</dl>
- <h4><a name="elementsMemory">Memory devices</a></h4>
+ <h4><a id="elementsMemory">Memory devices</a></h4>
<p>
In addition to the initial memory assigned to the guest, memory devices
</dd>
</dl>
- <h4><a name="elementsIommu">IOMMU devices</a></h4>
+ <h4><a id="elementsIommu">IOMMU devices</a></h4>
<p>
The <code>iommu</code> element can be used to add an IOMMU device.
</dd>
</dl>
- <h3><a name="seclabel">Security label</a></h3>
+ <h3><a id="seclabel">Security label</a></h3>
<p>
The <code>seclabel</code> element allows control over the
being on a file system that lacks security labeling.
</p>
- <h3><a name="keywrap">Key Wrap</a></h3>
+ <h3><a id="keywrap">Key Wrap</a></h3>
<p>The content of the optional <code>keywrap</code> element specifies
whether the guest will be allowed to perform the S390 cryptographic key
<p>Note: DEA/TDEA is synonymous with DES/TDES.</p>
- <h2><a name="examples">Example configs</a></h2>
+ <h2><a id="examples">Example configs</a></h2>
<p>
Example configurations for each driver are provide on the
<ul id="toc"></ul>
- <h2><a name="Overview">Overview</a></h2>
+ <h2><a id="Overview">Overview</a></h2>
<p>Sometimes, when a new domain is to be created it may come handy to know
the capabilities of the hypervisor so the correct combination of devices and
management application to choose an appropriate mode for a pass-through
host device as well as which adapter to utilize.</p>
- <h2><a name="elements">Element and attribute overview</a></h2>
+ <h2><a id="elements">Element and attribute overview</a></h2>
<p> A new query interface was added to the virConnect API's to retrieve the
XML listing of the set of domain capabilities (<span class="since">Since
</dl>
- <h3><a name="elementsCPUAllocation">CPU Allocation</a></h3>
+ <h3><a id="elementsCPUAllocation">CPU Allocation</a></h3>
<p>Before any devices capability occurs, there might be a info on domain
wide capabilities, e.g. virtual CPUs:</p>
<dd>The maximum number of supported virtual CPUs</dd>
</dl>
- <h3><a name="elementsOSBIOS">BIOS bootloader</a></h3>
+ <h3><a id="elementsOSBIOS">BIOS bootloader</a></h3>
<p>Sometimes users might want to tweak some BIOS knobs or use
UEFI. For cases like that, <a
<loader/> element.</dd>
</dl>
- <h3><a name="elementsCPU">CPU configuration</a></h3>
+ <h3><a id="elementsCPU">CPU configuration</a></h3>
<p>
The <code>cpu</code> element exposes options usable for configuring
</dd>
</dl>
- <h3><a name="elementsDevices">Devices</a></h3>
+ <h3><a id="elementsDevices">Devices</a></h3>
<p>
Another set of XML elements describe the supported devices and their
support the values <code>disk</code>, <code>cdrom</code>,
<code>floppy</code>, or <code>lun</code>.</p>
- <h4><a name="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
+ <h4><a id="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
<p>Disk capabilities are exposed under the <code>disk</code> element. For
instance:</p>
</dl>
- <h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
+ <h4><a id="elementsGraphics">Graphical framebuffers</a></h4>
<p>Graphics device capabilities are exposed under the
<code>graphics</code> element. For instance:</p>
</dl>
- <h4><a name="elementsVideo">Video device</a></h4>
+ <h4><a id="elementsVideo">Video device</a></h4>
<p>Video device capabilities are exposed under the
<code>video</code> element. For instance:</p>
</dl>
- <h4><a name="elementsHostDev">Host device assignment</a></h4>
+ <h4><a id="elementsHostDev">Host device assignment</a></h4>
<p>Some host devices can be passed through to a guest (e.g. USB, PCI and
SCSI). Well, only if the following is enabled:</p>
element.</dd>
</dl>
- <h3><a name="elementsFeatures">Features</a></h3>
+ <h3><a id="elementsFeatures">Features</a></h3>
<p>One more set of XML elements describe the supported features and
their capabilities. All features occur as children of the main
the domain XML documentation.
</p>
- <h4><a name="elementsGIC">GIC capabilities</a></h4>
+ <h4><a id="elementsGIC">GIC capabilities</a></h4>
<p>GIC capabilities are exposed under the <code>gic</code> element.</p>
<a href="https://wiki.libvirt.org/page/Networking">relevant wiki page</a>.
</p>
- <h2><a name="elements">Element and attribute overview</a></h2>
+ <h2><a id="elements">Element and attribute overview</a></h2>
<p>
The root element required for all virtual networks is
available <span class="since">since 0.3.0</span>
</p>
- <h3><a name="elementsMetadata">General metadata</a></h3>
+ <h3><a id="elementsMetadata">General metadata</a></h3>
<p>
The first elements provide basic metadata about the virtual
override the setting in the network.</dd>
</dl>
- <h3><a name="elementsConnect">Connectivity</a></h3>
+ <h3><a id="elementsConnect">Connectivity</a></h3>
<p>
The next set of elements control how a virtual network is
</dd>
</dl>
- <h5><a name="elementQoS">Quality of service</a></h5>
+ <h5><a id="elementQoS">Quality of service</a></h5>
<pre>
...
<span class="since">since 1.0.1</span>.
</p>
- <h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
+ <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
<pre>
<network>
or <code><interface></code>.
</p>
- <h5><a name="elementsPortgroup">Portgroups</a></h5>
+ <h5><a id="elementsPortgroup">Portgroups</a></h5>
<pre>
...
setting in the portgroup.
</p>
- <h5><a name="elementsStaticroute">Static Routes</a></h5>
+ <h5><a id="elementsStaticroute">Static Routes</a></h5>
<p>
Static route definitions are used to provide routing information
to the virtualization host for networks which are not directly
...
</pre>
- <h3><a name="elementsAddress">Addressing</a></h3>
+ <h3><a id="elementsAddress">Addressing</a></h3>
<p>
The final set of elements define the addresses (IPv4 and/or
</dd>
</dl>
- <h2><a name="examples">Example configuration</a></h2>
+ <h2><a id="examples">Example configuration</a></h2>
- <h3><a name="examplesNAT">NAT based network</a></h3>
+ <h3><a id="examplesNAT">NAT based network</a></h3>
<p>
This example is the so called "default" virtual network. It is
</ip>
</network></pre>
- <h3><a name="examplesRoute">Routed network config</a></h3>
+ <h3><a id="examplesRoute">Routed network config</a></h3>
<p>
This is a variant on the default network which routes traffic
<route family="ipv6" address="2001:db8:ca2:8::" prefix="64" gateway="2001:db8:ca2:7::4"/>
</network></pre>
- <h3><a name="examplesPrivate">Isolated network config</a></h3>
+ <h3><a id="examplesPrivate">Isolated network config</a></h3>
<p>
This variant provides a completely isolated private network
<ip family="ipv6" address="2001:db8:ca2:3::1" prefix="64"/>
</network></pre>
- <h3><a name="examplesPrivate6">Isolated IPv6 network config</a></h3>
+ <h3><a id="examplesPrivate6">Isolated IPv6 network config</a></h3>
<p>
This variation of an isolated network defines only IPv6.
</ip>
</network></pre>
- <h3><a name="examplesBridge">Using an existing host bridge</a></h3>
+ <h3><a id="examplesBridge">Using an existing host bridge</a></h3>
<p>
<span class="since">Since 0.9.4</span>
<bridge name="br0"/>
</network></pre>
- <h3><a name="examplesDirect">Using a macvtap "direct" connection</a></h3>
+ <h3><a id="examplesDirect">Using a macvtap "direct" connection</a></h3>
<p>
<span class="since">Since 0.9.4, QEMU and KVM only, requires
</forward>
</network></pre>
- <h3><a name="examplesNoGateway">Network config with no gateway addresses</a></h3>
+ <h3><a id="examplesNoGateway">Network config with no gateway addresses</a></h3>
<p>
A valid network definition can contain no IPv4 or IPv6 addresses. Such a definition
<ul id="toc"></ul>
- <h2><a name="NodedevAttributes">Node Device XML</a></h2>
+ <h2><a id="NodedevAttributes">Node Device XML</a></h2>
<p>
There are several libvirt functions, all with the
</dd>
</dl>
- <h2><a name="nodeExample">Examples</a></h2>
+ <h2><a id="nodeExample">Examples</a></h2>
<p>The following are some example node device XML outputs:</p>
<pre>
their goals, concepts and XML format.
</p>
- <h2><a name="goals">Goals and background</a></h2>
+ <h2><a id="goals">Goals and background</a></h2>
<p>
The goal of the network filtering XML is to enable administrators
(QEMU, KVM)</span>
</p>
- <h2><a name="nwfconcepts">Concepts</a></h2>
+ <h2><a id="nwfconcepts">Concepts</a></h2>
<p>
The network traffic filtering subsystem enables configuration
of network traffic filtering rules on individual network
<br/><br/>
</p>
- <h3><a name="nwfconceptschains">Filtering chains</a></h3>
+ <h3><a id="nwfconceptschains">Filtering chains</a></h3>
<p>
Filtering rules are organized in filter chains. These chains can be
thought of as having a tree structure with packet
traverse the ARP chain.
<br/><br/>
</p>
- <h3><a name="nwfconceptschainpriorities">Filtering chain priorities</a></h3>
+ <h3><a id="nwfconceptschainpriorities">Filtering chain priorities</a></h3>
<p>
All chains are connected to the <code>root</code> chain. The order in
which those chains are accessed is influenced by the priority of the
node. The above example filter shows the default priority of -500
for <code>arp</code> chains.
</p>
- <h3><a name="nwfconceptsvars">Usage of variables in filters</a></h3>
+ <h3><a id="nwfconceptsvars">Usage of variables in filters</a></h3>
<p>
Two variables names have so far been reserved for usage by the
former notation always assumes the iterator with Id '0'.
</p>
- <h3><a name="nwfelemsRulesAdvIPAddrDetection">Automatic IP address detection</a></h3>
+ <h3><a id="nwfelemsRulesAdvIPAddrDetection">Automatic IP address detection</a></h3>
<p>
The detection of IP addresses used on a virtual machine's interface
is automatically activated if the variable <code>IP</code> is referenced
</interface>
</pre>
- <h3><a name="nwfelemsReservedVars">Reserved Variables</a></h3>
+ <h3><a id="nwfelemsReservedVars">Reserved Variables</a></h3>
<p>
The following table lists reserved variables in use by libvirt.
</p>
</tr>
</table>
- <h2><a name="nwfelems">Element and attribute overview</a></h2>
+ <h2><a id="nwfelems">Element and attribute overview</a></h2>
<p>
The root element required for all network filters is
ipv4, ipv6, arp and rarp</code>.
</p>
- <h3><a name="nwfelemsRefs">References to other filters</a></h3>
+ <h3><a id="nwfelemsRefs">References to other filters</a></h3>
<p>
Any filter may hold references to other filters. Individual
filters may be referenced multiple times in a filter tree but
attached.
</p>
- <h3><a name="nwfelemsRules">Filter rules</a></h3>
+ <h3><a id="nwfelemsRules">Filter rules</a></h3>
<p>
The following XML shows a simple example of a network
traffic filter implementing a rule to drop traffic if
filtered.
</p>
- <h4><a name="nwfelemsRulesProto">Supported protocols</a></h4>
+ <h4><a id="nwfelemsRulesProto">Supported protocols</a></h4>
<p>
The following sections enumerate the list of protocols that
are supported by the network filtering subsystem. The
</p>
- <h5><a name="nwfelemsRulesProtoMAC">MAC (Ethernet)</a></h5>
+ <h5><a id="nwfelemsRulesProtoMAC">MAC (Ethernet)</a></h5>
<p>
Protocol ID: <code>mac</code>
<br/>
[...]
</pre>
- <h5><a name="nwfelemsRulesProtoVLAN">VLAN (802.1Q)</a>
+ <h5><a id="nwfelemsRulesProtoVLAN">VLAN (802.1Q)</a>
<span class="since">(Since 0.9.8)</span>
</h5>
<p>
Valid Strings for <code>encap-protocol</code> are: arp, ipv4, ipv6
</p>
- <h5><a name="nwfelemsRulesProtoSTP">STP (Spanning Tree Protocol)</a>
+ <h5><a id="nwfelemsRulesProtoSTP">STP (Spanning Tree Protocol)</a>
<span class="since">(Since 0.9.8)</span>
</h5>
<p>
</tr>
</table>
- <h5><a name="nwfelemsRulesProtoARP">ARP/RARP</a></h5>
+ <h5><a id="nwfelemsRulesProtoARP">ARP/RARP</a></h5>
<p>
Protocol ID: <code>arp</code> or <code>rarp</code>
<br/>
<br/><br/>
</p>
- <h5><a name="nwfelemsRulesProtoIP">IPv4</a></h5>
+ <h5><a id="nwfelemsRulesProtoIP">IPv4</a></h5>
<p>
Protocol ID: <code>ip</code>
<br/>
</p>
- <h5><a name="nwfelemsRulesProtoIPv6">IPv6</a></h5>
+ <h5><a id="nwfelemsRulesProtoIPv6">IPv6</a></h5>
<p>
Protocol ID: <code>ipv6</code>
<br/>
<br/><br/>
</p>
- <h5><a name="nwfelemsRulesProtoTCP-ipv4">TCP/UDP/SCTP</a></h5>
+ <h5><a id="nwfelemsRulesProtoTCP-ipv4">TCP/UDP/SCTP</a></h5>
<p>
Protocol ID: <code>tcp</code>, <code>udp</code>, <code>sctp</code>
<br/>
</p>
- <h5><a name="nwfelemsRulesProtoICMP">ICMP</a></h5>
+ <h5><a id="nwfelemsRulesProtoICMP">ICMP</a></h5>
<p>
Protocol ID: <code>icmp</code>
<br/>
<br/><br/>
</p>
- <h5><a name="nwfelemsRulesProtoMisc">IGMP, ESP, AH, UDPLITE, 'ALL'</a></h5>
+ <h5><a id="nwfelemsRulesProtoMisc">IGMP, ESP, AH, UDPLITE, 'ALL'</a></h5>
<p>
Protocol ID: <code>igmp</code>, <code>esp</code>, <code>ah</code>, <code>udplite</code>, <code>all</code>
<br/>
</p>
- <h5><a name="nwfelemsRulesProtoTCP-ipv6">TCP/UDP/SCTP over IPV6</a></h5>
+ <h5><a id="nwfelemsRulesProtoTCP-ipv6">TCP/UDP/SCTP over IPV6</a></h5>
<p>
Protocol ID: <code>tcp-ipv6</code>, <code>udp-ipv6</code>, <code>sctp-ipv6</code>
<br/>
</p>
- <h5><a name="nwfelemsRulesProtoICMPv6">ICMPv6</a></h5>
+ <h5><a id="nwfelemsRulesProtoICMPv6">ICMPv6</a></h5>
<p>
Protocol ID: <code>icmpv6</code>
<br/>
<br/><br/>
</p>
- <h5><a name="nwfelemsRulesProtoMiscv6">ESP, AH, UDPLITE, 'ALL' over IPv6</a></h5>
+ <h5><a id="nwfelemsRulesProtoMiscv6">ESP, AH, UDPLITE, 'ALL' over IPv6</a></h5>
<p>
Protocol ID: <code>esp-ipv6</code>, <code>ah-ipv6</code>, <code>udplite-ipv6</code>, <code>all-ipv6</code>
<br/>
<br/><br/>
</p>
- <h3><a name="nwfelemsRulesAdv">Advanced Filter Configuration Topics</a></h3>
+ <h3><a id="nwfelemsRulesAdv">Advanced Filter Configuration Topics</a></h3>
<p>
The following sections discuss advanced filter configuration
topics.
</p>
- <h4><a name="nwfelemsRulesAdvTracking">Connection tracking</a></h4>
+ <h4><a id="nwfelemsRulesAdvTracking">Connection tracking</a></h4>
<p>
The network filtering subsystem (on Linux) makes use of the connection
tracking support of iptables. This helps in enforcing the
which may or may not be desirable.
</p>
- <h4><a name="nwfelemsRulesAdvLimiting">Limiting Number of Connections</a></h4>
+ <h4><a id="nwfelemsRulesAdvLimiting">Limiting Number of Connections</a></h4>
<p>
To limit the number of connections a VM may establish, a rule must
be provided that sets a limit of connections for a given
traffic behavior in relation to idle connections.
</p>
- <h2><a name="nwfcli">Command line tools</a></h2>
+ <h2><a id="nwfcli">Command line tools</a></h2>
<p>
The libvirt command line tool <code>virsh</code> has been extended
with life-cycle support for network filters. All commands related
<li>nwfilter-edit : edit a network filter given its name</li>
</ul>
- <h2><a name="nwfexamples">Pre-existing network filters</a></h2>
+ <h2><a id="nwfexamples">Pre-existing network filters</a></h2>
<p>
The following is a list of example network filters that are
automatically installed with libvirt.</p>
on top of the prevention of packet spoofing.
</p>
- <h2><a name="nwfwrite">Writing your own filters</a></h2>
+ <h2><a id="nwfwrite">Writing your own filters</a></h2>
<p>
Since libvirt only provides a couple of example networking filters, you
<code>udp-ipv6</code> traffic filtering node.
</p>
- <h3><a name="nwfwriteexample">Example custom filter</a></h3>
+ <h3><a id="nwfwriteexample">Example custom filter</a></h3>
<p>
As an example we want to now build a filter that fulfills the following
list of requirements:
</rule>
</pre>
- <h3><a name="nwfwriteexample2nd">Second example custom filter</a></h3>
+ <h3><a id="nwfwriteexample2nd">Second example custom filter</a></h3>
<p>
In this example we now want to build a similar filter as in the
example above, but extend the list of requirements with an
</pre>
- <h2><a name="nwflimits">Limitations</a></h2>
+ <h2><a id="nwflimits">Limitations</a></h2>
<p>
The following sections list (current) limitations of the network
filtering subsystem.
</p>
- <h3><a name="nwflimitsmigr">VM Migration</a></h3>
+ <h3><a id="nwflimitsmigr">VM Migration</a></h3>
<p>
VM migration is only supported if the whole filter tree
that is referenced by a virtual machine's top level filter
0.8.1 or later in order not to lose the network traffic filters
associated with an interface.
</p>
- <h3><a name="nwflimitsvlan">VLAN filtering on Linux</a></h3>
+ <h3><a id="nwflimitsvlan">VLAN filtering on Linux</a></h3>
<p>
VLAN (802.1Q) packets, if sent by a virtual machine, cannot be filtered
with rules for protocol IDs <code>arp</code>, <code>rarp</code>,
<ul id="toc"></ul>
- <h2><a name="SecretAttributes">Secret XML</a></h2>
+ <h2><a id="SecretAttributes">Secret XML</a></h2>
<p>
Secrets stored by libvirt may have attributes associated with them, using
</dd>
</dl>
- <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
+ <h3><a id="VolumeUsageType">Usage type "volume"</a></h3>
<p>
This secret is associated with a volume, whether the format is either
#
</pre>
- <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
+ <h3><a id="CephUsageType">Usage type "ceph"</a></h3>
<p>
This secret is associated with a Ceph RBD (rados block device).
The <code><usage type='ceph'></code> element must contain
</auth>
</pre>
- <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
+ <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
<p>
This secret is associated with an iSCSI target for CHAP authentication.
</auth>
</pre>
- <h3><a name="tlsUsageType">Usage type "tls"</a></h3>
+ <h3><a id="tlsUsageType">Usage type "tls"</a></h3>
<p>
This secret may be used in order to provide the passphrase for the
<ul id="toc"></ul>
- <h2><a name="SnapshotAttributes">Snapshot XML</a></h2>
+ <h2><a id="SnapshotAttributes">Snapshot XML</a></h2>
<p>
There are several types of snapshots:
</dd>
</dl>
- <h2><a name="example">Examples</a></h2>
+ <h2><a id="example">Examples</a></h2>
<p>Using this XML to create a disk snapshot of just vda on a qemu
domain with two disks:</p>
<ul id="toc"></ul>
- <h2><a name="StoragePool">Storage pool XML</a></h2>
+ <h2><a id="StoragePool">Storage pool XML</a></h2>
<p>
Although all storage pool backends share the same public APIs and
3.1.0</span>). This corresponds to the
storage backend drivers listed further along in this document.
</p>
- <h3><a name="StoragePoolFirst">General metadata</a></h3>
+ <h3><a id="StoragePoolFirst">General metadata</a></h3>
<pre>
<pool type="iscsi">
pool. <span class="since">Since 0.4.1</span></dd>
</dl>
- <h3><a name="StoragePoolSource">Source elements</a></h3>
+ <h3><a id="StoragePoolSource">Source elements</a></h3>
<p>
A single <code>source</code> element is contained within the top level
is backend specific. <span class="since">Since 0.8.4</span></dd>
</dl>
- <h3><a name="StoragePoolTarget">Target elements</a></h3>
+ <h3><a id="StoragePoolTarget">Target elements</a></h3>
<p>
A single <code>target</code> element is contained within the top level
</dd>
</dl>
- <h3><a name="StoragePoolExtents">Device extents</a></h3>
+ <h3><a id="StoragePoolExtents">Device extents</a></h3>
<p>
If a storage pool exposes information about its underlying
device, measured in bytes. <span class="since">Since 0.4.1</span>
</p>
- <h2><a name="StorageVol">Storage volume XML</a></h2>
+ <h2><a id="StorageVol">Storage volume XML</a></h2>
<p>
A storage volume will generally be either a file or a device
node; <span class="since">since 1.2.0</span>, an optional
XML format is available <span class="since">since 0.4.1</span>
</p>
- <h3><a name="StorageVolFirst">General metadata</a></h3>
+ <h3><a id="StorageVolFirst">General metadata</a></h3>
<pre>
<volume type='file'>
on the local host. <span class="since">Since 0.4.1</span></dd>
</dl>
- <h3><a name="StorageVolTarget">Target elements</a></h3>
+ <h3><a id="StorageVolTarget">Target elements</a></h3>
<p>
A single <code>target</code> element is contained within the top level
</dd>
</dl>
- <h3><a name="StorageVolBacking">Backing store elements</a></h3>
+ <h3><a id="StorageVolBacking">Backing store elements</a></h3>
<p>
A single <code>backingStore</code> element is contained within the top level
</dd>
</dl>
- <h2><a name="examples">Example configuration</a></h2>
+ <h2><a id="examples">Example configuration</a></h2>
<p>
Here are a couple of examples, for a more complete set demonstrating
every type of storage pool, consult the <a href="storage.html">storage driver page</a>
</p>
- <h3><a name="exampleFile">File based storage pool</a></h3>
+ <h3><a id="exampleFile">File based storage pool</a></h3>
<pre>
<pool type="dir">
</target>
</pool></pre>
- <h3><a name="exampleISCSI">iSCSI based storage pool</a></h3>
+ <h3><a id="exampleISCSI">iSCSI based storage pool</a></h3>
<pre>
<pool type="iscsi">
</target>
</pool></pre>
- <h3><a name="exampleVol">Storage volume</a></h3>
+ <h3><a id="exampleVol">Storage volume</a></h3>
<pre>
<volume>
</target>
</volume></pre>
- <h3><a name="exampleLuks">Storage volume using LUKS</a></h3>
+ <h3><a id="exampleLuks">Storage volume using LUKS</a></h3>
<pre>
<volume>
<ul id="toc"></ul>
- <h2><a name="StorageEncryption">Storage volume encryption XML</a></h2>
+ <h2><a id="StorageEncryption">Storage volume encryption XML</a></h2>
<p>
Storage volumes may be encrypted, the XML snippet described below is used
secret value at the time of volume creation, and store it using the
specified <code>uuid</code>.
</p>
- <h3><a name="StorageEncryptionDefault">"default" format</a></h3>
+ <h3><a id="StorageEncryptionDefault">"default" format</a></h3>
<p>
<code><encryption format="default"/></code> can be specified only
when creating a qcow volume. If the volume is successfully created, the
in later operations with the volume, or when setting up a domain that
uses the volume.
</p>
- <h3><a name="StorageEncryptionQcow">"qcow" format</a></h3>
+ <h3><a id="StorageEncryptionQcow">"qcow" format</a></h3>
<p>
The <code>qcow</code> format specifies that the built-in encryption
support in <code>qcow</code>- or <code>qcow2</code>-formatted volume
the <code>secret</code> element is not present during volume creation,
a secret is automatically generated and attached to the volume.
</p>
- <h3><a name="StorageEncryptionLuks">"luks" format</a></h3>
+ <h3><a id="StorageEncryptionLuks">"luks" format</a></h3>
<p>
The <code>luks</code> format is specific to a luks encrypted volume
and the secret is used in order to either encrypt during volume creation
</dl>
- <h2><a name="example">Examples</a></h2>
+ <h2><a id="example">Examples</a></h2>
<p>
Here is a simple example, specifying use of the <code>qcow</code> format:
influence, within the community.
</p>
- <h2><a name="codeofconduct">Code of conduct</a></h2>
+ <h2><a id="codeofconduct">Code of conduct</a></h2>
<p>
The libvirt project community covers people from a wide variety of
from them. Playing a blame game doesn't help anyone.</li>
</ul>
- <h2><a name="roles">Roles and responsibilities</a></h2>
+ <h2><a id="roles">Roles and responsibilities</a></h2>
<h3><a href="users">Users</a></h3>
ways listed in the next section.
</p>
- <h3><a name="contributors">Contributors</a></h3>
+ <h3><a id="contributors">Contributors</a></h3>
<p>
The contributors are community members who have some concrete impact
covered are found in the source repositories, or website in question.
</p>
- <h3><a name="committers">Committers</a></h3>
+ <h3><a id="committers">Committers</a></h3>
<p>
The committers are the subset of contributors who have direct access
to retain their role as a committer.
</p>
- <h3><a name="secteam">Security team</a></h3>
+ <h3><a id="secteam">Security team</a></h3>
<p>
The security team consists of a subset of the project committers
before disclosing a private issue.
</p>
- <h2><a name="roughconsensus">Rough consensus</a></h2>
+ <h2><a id="roughconsensus">Rough consensus</a></h2>
<p>
A core concept for governance of the project described above is
<ul id="toc"></ul>
- <h2><a name="patches">General tips for contributing patches</a></h2>
+ <h2><a id="patches">General tips for contributing patches</a></h2>
<ol>
<li>
<p>Discuss any large changes on the mailing list first. Post patches
Richard Jones' guide to working with open source projects</a>.
</p>
- <h2><a name="tooling">Tooling</a></h2>
+ <h2><a id="tooling">Tooling</a></h2>
<p>
libvirt includes support for some useful development tools right in its
</li>
</ul>
- <h2><a name="naming">Naming conventions</a></h2>
+ <h2><a id="naming">Naming conventions</a></h2>
<p>
When reading libvirt code, a number of different naming conventions will
</dd>
</dl>
- <h2><a name="indent">Code indentation</a></h2>
+ <h2><a id="indent">Code indentation</a></h2>
<p>
Libvirt's C source code generally adheres to some basic code-formatting
conventions. The existing code base is not totally consistent on this
which will load the .lvimrc only when you edit libvirt code.
</p>
- <h2><a name="formatting">Code formatting (especially for new code)</a></h2>
+ <h2><a id="formatting">Code formatting (especially for new code)</a></h2>
<p>
With new code, we can be even more strict.
</p>
- <h2><a name="bracket_spacing">Bracket spacing</a></h2>
+ <h2><a id="bracket_spacing">Bracket spacing</a></h2>
<p>
The keywords <code>if</code>, <code>for</code>, <code>while</code>,
int foo(int wizz); // Good
</pre>
- <h2><a name="comma">Commas</a></h2>
+ <h2><a id="comma">Commas</a></h2>
<p>
Commas should always be followed by a space or end of line, and
};
</pre>
- <h2><a name="semicolon">Semicolons</a></h2>
+ <h2><a id="semicolon">Semicolons</a></h2>
<p>
Semicolons should never have a space beforehand. Inside the
}
</pre>
- <h2><a name="curly_braces">Curly braces</a></h2>
+ <h2><a id="curly_braces">Curly braces</a></h2>
<p>
Omit the curly braces around an <code>if</code>, <code>while</code>,
}
</pre>
- <h2><a name="preprocessor">Preprocessor</a></h2>
+ <h2><a id="preprocessor">Preprocessor</a></h2>
<p>Macros defined with an ALL_CAPS name should generally be
assumed to be unsafe with regards to arguments with side-effects
#endif
</pre>
- <h2><a name="types">C types</a></h2>
+ <h2><a id="types">C types</a></h2>
<p>
Use the right type.
it points to, or it is aliased to another pointer that is.
</p>
- <h2><a name="memalloc">Low level memory management</a></h2>
+ <h2><a id="memalloc">Low level memory management</a></h2>
<p>
Use of the malloc/free/realloc/calloc APIs is deprecated in the libvirt
</li>
</ul>
- <h2><a name="file_handling">File handling</a></h2>
+ <h2><a id="file_handling">File handling</a></h2>
<p>
Usage of the <code>fdopen()</code>, <code>close()</code>, <code>fclose()</code>
</li>
</ul>
- <h2><a name="string_comparision">String comparisons</a></h2>
+ <h2><a id="string_comparision">String comparisons</a></h2>
<p>
Do not use the strcmp, strncmp, etc functions directly. Instead use
</ul>
- <h2><a name="string_copying">String copying</a></h2>
+ <h2><a id="string_copying">String copying</a></h2>
<p>
Do not use the strncpy function. According to the man page, it
and usually considered a flaw.
</p>
- <h2><a name="strbuf">Variable length string buffer</a></h2>
+ <h2><a id="strbuf">Variable length string buffer</a></h2>
<p>
If there is a need for complex string concatenations, avoid using
</pre>
- <h2><a name="includes">Include files</a></h2>
+ <h2><a id="includes">Include files</a></h2>
<p>
There are now quite a large number of include files, both libvirt
</p>
- <h2><a name="printf">Printf-style functions</a></h2>
+ <h2><a id="printf">Printf-style functions</a></h2>
<p>
Whenever you add a new printf-style function, i.e., one with a format
does for snprintf.
</p>
- <h2><a name="goto">Use of goto</a></h2>
+ <h2><a id="goto">Use of goto</a></h2>
<p>
The use of goto is not forbidden, and goto is widely used
- <h2><a name="committers">Libvirt committer guidelines</a></h2>
+ <h2><a id="committers">Libvirt committer guidelines</a></h2>
<p>
The AUTHORS files indicates the list of people with commit access right
<ul id="toc"></ul>
- <h2><a name="intro">Custom event scripts</a></h2>
+ <h2><a id="intro">Custom event scripts</a></h2>
<p>Beginning with libvirt 0.8.0, specific events on a host system will
trigger custom scripts.</p>
<p>These custom <b>hook</b> scripts are executed when any of the following
(<span class="since">since 1.2.2</span>)<br/><br/></li>
</ul>
- <h2><a name="location">Script location</a></h2>
+ <h2><a id="location">Script location</a></h2>
<p>The libvirt hook scripts are located in the directory
<code>$SYSCONFDIR/libvirt/hooks/</code>.</p>
<ul>
them executable.</p>
<br/>
- <h2><a name="names">Script names</a></h2>
+ <h2><a id="names">Script names</a></h2>
<p>At present, there are five hook scripts that can be called:</p>
<ul>
<li><code>/etc/libvirt/hooks/daemon</code><br/><br/>
</ul>
<br/>
- <h2><a name="structure">Script structure</a></h2>
+ <h2><a id="structure">Script structure</a></h2>
<p>The hook scripts are executed using standard Linux process creation
functions. Therefore, they must begin with the declaration of the
command interpreter to use.</p>
binary, so you are welcome to use your favourite languages.</p>
<br/>
- <h2><a name="arguments">Script arguments</a></h2>
+ <h2><a id="arguments">Script arguments</a></h2>
<p>The hook scripts are called with specific command line arguments,
depending upon the script, and the operation being performed.</p>
<p>The guest hook scripts, qemu and lxc, are also given the <b>full</b>
none.</li>
</ol>
- <h4><a name="arguments_specifics">Specifics</a></h4>
+ <h4><a id="arguments_specifics">Specifics</a></h4>
<p>This translates to the following specifics for each hook script:</p>
- <h5><a name="daemon">/etc/libvirt/hooks/daemon</a></h5>
+ <h5><a id="daemon">/etc/libvirt/hooks/daemon</a></h5>
<ul>
<li>When the libvirt daemon is started, this script is called as:<br/>
<pre>/etc/libvirt/hooks/daemon - start - start</pre></li>
with the "start" operation. There is no specific operation to indicate
a "restart" is occurring.</p>
- <h5><a name="qemu">/etc/libvirt/hooks/qemu</a></h5>
+ <h5><a id="qemu">/etc/libvirt/hooks/qemu</a></h5>
<ul>
<li>Before a QEMU guest is started, the qemu hook script is
called in three locations; if any location fails, the guest
</li>
</ul>
- <h5><a name="lxc">/etc/libvirt/hooks/lxc</a></h5>
+ <h5><a id="lxc">/etc/libvirt/hooks/lxc</a></h5>
<ul>
<li>Before a LXC guest is started, the lxc hook script is
called in three locations; if any location fails, the guest
</li>
</ul>
- <h5><a name="libxl">/etc/libvirt/hooks/libxl</a></h5>
+ <h5><a id="libxl">/etc/libvirt/hooks/libxl</a></h5>
<ul>
<li>Before a Xen guest is started using libxl driver, the libxl hook
script is called in three locations; if any location fails, the guest
</li>
</ul>
- <h5><a name="network">/etc/libvirt/hooks/network</a></h5>
+ <h5><a id="network">/etc/libvirt/hooks/network</a></h5>
<ul>
<li><span class="since">Since 1.2.2</span>, before a network is started,
this script is called as:<br/>
<br/>
- <h2><a name="execution">Script execution</a></h2>
+ <h2><a id="execution">Script execution</a></h2>
<ul>
<li>The "start" operation for the guest and network hook scripts,
executes <b>prior</b> to the object (guest or network) being created.
</ul>
<br/>
- <h2><a name="qemu_migration">QEMU guest migration</a></h2>
+ <h2><a id="qemu_migration">QEMU guest migration</a></h2>
<p>Migration of a QEMU guest involves running hook scripts on both the
source and destination hosts:</p>
<ol>
</ol>
<br/>
- <h2><a name="recursive">Calling libvirt functions from within a hook script</a></h2>
+ <h2><a id="recursive">Calling libvirt functions from within a hook script</a></h2>
<p><b>DO NOT DO THIS!</b></p>
<p>A hook script must not call back into libvirt, as the libvirt daemon
is already waiting for the script to exit.</p>
<p>A deadlock is likely to occur.</p>
<br/>
- <h2><a name="return_codes">Return codes and logging</a></h2>
+ <h2><a id="return_codes">Return codes and logging</a></h2>
<p>If a hook script returns with an exit code of 0, the libvirt daemon
regards this as successful and performs no logging of it.</p>
<p>However, if a hook script returns with a non zero exit code, the libvirt
All code is required to use these APIs
</p>
- <h2><a name="posix">Problems with standard POSIX APIs</a></h2>
+ <h2><a id="posix">Problems with standard POSIX APIs</a></h2>
<p>
The POSIX specification includes a number of APIs for
error prone, particularly wrt memory leak / OOM handling.
</p>
- <h2><a name="api">The libvirt command execution API</a></h2>
+ <h2><a id="api">The libvirt command execution API</a></h2>
<p>
There is now a high level API that provides a safe and
header which can be imported using <code>#include "vircommand.h"</code>
</p>
- <h3><a name="initial">Defining commands in libvirt</a></h3>
+ <h3><a id="initial">Defining commands in libvirt</a></h3>
<p>
The first step is to declare what command is to be
reported at a later time.
</p>
- <h3><a name="args">Adding arguments to the command</a></h3>
+ <h3><a id="args">Adding arguments to the command</a></h3>
<p>
There are a number of APIs for adding arguments to a
"--domain", "localdomain", NULL);
</pre>
- <h3><a name="env">Setting up the environment</a></h3>
+ <h3><a id="env">Setting up the environment</a></h3>
<p>
By default a command will inherit all environment variables
virCommandAddEnvString(cmd, "TERM=xterm");
</pre>
- <h3><a name="misc">Miscellaneous other options</a></h3>
+ <h3><a id="misc">Miscellaneous other options</a></h3>
<p>
Normally the spawned command will retain the current
the intermediate process exits.
</p>
- <h3><a name="privs">Reducing command privileges</a></h3>
+ <h3><a id="privs">Reducing command privileges</a></h3>
<p>
Normally a command will inherit all privileges of
virCommandClearCaps(cmd);
</pre>
- <h3><a name="fds">Managing file handles</a></h3>
+ <h3><a id="fds">Managing file handles</a></h3>
<p>
To prevent unintended resource leaks to child processes, the
virCommandNonblockingFDs(cmd);
</pre>
- <h3><a name="buffers">Feeding & capturing strings to/from the child</a></h3>
+ <h3><a id="buffers">Feeding & capturing strings to/from the child</a></h3>
<p>
Often dealing with file handles for stdin/out/err is
case the child process interleaves output into a single string.
</p>
- <h3><a name="directory">Setting working directory</a></h3>
+ <h3><a id="directory">Setting working directory</a></h3>
<p>
Daemonized commands are always run with "/" as the current
virCommandSetWorkingDirectory(cmd, LOCALSTATEDIR);
</pre>
- <h3><a name="hooks">Any additional hooks</a></h3>
+ <h3><a id="hooks">Any additional hooks</a></h3>
<p>
If anything else is needed, it is possible to request a hook
virCommandSetPreExecHook(cmd, hook, opaque);
</pre>
- <h3><a name="logging">Logging commands</a></h3>
+ <h3><a id="logging">Logging commands</a></h3>
<p>
Sometimes, it is desirable to log what command will be run, or
return -1;
</pre>
- <h3><a name="sync">Running commands synchronously</a></h3>
+ <h3><a id="sync">Running commands synchronously</a></h3>
<p>
For most commands, the desired behaviour is to spawn
}
</pre>
- <h3><a name="async">Running commands asynchronously</a></h3>
+ <h3><a id="async">Running commands asynchronously</a></h3>
<p>
In certain complex scenarios, particularly special
virCommandAbort to reap the process.
</p>
- <h3><a name="release">Releasing resources</a></h3>
+ <h3><a id="release">Releasing resources</a></h3>
<p>
Once the command has been executed, or if execution
it will be forcibly killed and cleaned up (via waitpid).
</p>
- <h2><a name="example">Complete examples</a></h2>
+ <h2><a id="example">Complete examples</a></h2>
<p>
This shows a complete example usage of the APIs roughly
libvirt. Both server and client.
</p>
- <h2><a name="event_loop">Event driven programming</a></h2>
+ <h2><a id="event_loop">Event driven programming</a></h2>
<p>Traditionally, a program simply ran once, then terminated.
This type of program was very common in the early days of
file descriptor which is then watched for incoming events,
e.g. messages. </p>
- <h2><a name="api">The event loop API</a></h2>
+ <h2><a id="api">The event loop API</a></h2>
<p>To work with event loop from our code we have plenty of
APIs.</p>
<p>For more information on these APIs continue reading <a
href="../html/libvirt-libvirt-event.html">here</a>.</p>
- <h2><a name="worker_pool">Worker pool</a></h2>
+ <h2><a id="worker_pool">Worker pool</a></h2>
<p>Looking back at the image above we can see one big
limitation. While processing a message event loop is blocked
access to content.
</p>
- <h2><a name="goals">Goals</a></h2>
+ <h2><a id="goals">Goals</a></h2>
<p>
The high level goal is to prevent the same disk image being
</li>
</ol>
- <h2><a name="requirement">Requirements</a></h2>
+ <h2><a id="requirement">Requirements</a></h2>
<p>
The high level goal leads to a set of requirements
</li>
</ol>
- <h2><a name="design">Design</a></h2>
+ <h2><a id="design">Design</a></h2>
<p>
Within a lock manager the following series of operations
</li>
</ul>
- <h2><a name="impl">Plugin Implementations</a></h2>
+ <h2><a id="impl">Plugin Implementations</a></h2>
<p>
Lock manager implementations are provided as LGPLv2+
in the previously mentioned header file
</p>
- <h2><a name="qemuIntegrate">QEMU Driver integration</a></h2>
+ <h2><a id="qemuIntegrate">QEMU Driver integration</a></h2>
<p>
With the QEMU driver, the lock plugin will be set
for backwards compatibility
</p>
- <h2><a name="usagePatterns">Lock usage patterns</a></h2>
+ <h2><a id="usagePatterns">Lock usage patterns</a></h2>
<p>
The following pseudo code illustrates the common
manager plugin callbacks.
</p>
- <h3><a name="usageLockAcquire">Lock acquisition</a></h3>
+ <h3><a id="usageLockAcquire">Lock acquisition</a></h3>
<p>
Initial lock acquisition will be performed from the
...abort...
</pre>
- <h3><a name="usageLockAttach">Lock release</a></h3>
+ <h3><a id="usageLockAttach">Lock release</a></h3>
<p>
The locks are all implicitly released when the process
</pre>
- <h2><a name="basicoom">Basic OOM testing support</a></h2>
+ <h2><a id="basicoom">Basic OOM testing support</a></h2>
<p>
The first step in validating OOM usage is to run a test suite
of memory allocations from that test case.
</p>
- <h3><a name="valgrind">Tracking failures with valgrind</a></h3>
+ <h3><a id="valgrind">Tracking failures with valgrind</a></h3>
<p>
The test suite should obviously *not* crash during OOM testing.
access.
</p>
- <h3><a name="stacktraces">Tracking failures with stack traces</a></h3>
+ <h3><a id="stacktraces">Tracking failures with stack traces</a></h3>
<p>
With some really difficult bugs valgrind is not sufficient to
??:?
</pre>
- <h3><a name="noncrash">Non-crash related problems</a></h3>
+ <h3><a id="noncrash">Non-crash related problems</a></h3>
<p>
Not all memory allocation bugs result in code crashing. Sometimes
</p>
- <h2><a name="protocol">RPC protocol</a></h2>
+ <h2><a id="protocol">RPC protocol</a></h2>
<p>
libvirt uses a simple, variable length, packet based RPC protocol.
definition for the program+version in question
</p>
- <h3><a name="wireexamples">Wire examples</a></h3>
+ <h3><a id="wireexamples">Wire examples</a></h3>
<p>
The following diagrams illustrate some example packet exchanges
between a client and server
</p>
- <h4><a name="wireexamplescall">Method call</a></h4>
+ <h4><a id="wireexamplescall">Method call</a></h4>
<p>
A single method call and successful
+--+-----------------------+--------+
</pre>
- <h4><a name="wireexamplescallerr">Method call with error</a></h4>
+ <h4><a id="wireexamplescallerr">Method call with error</a></h4>
<p>
An unsuccessful method call will instead return an error object
+--+-----------------------+--------------------------+
</pre>
- <h4><a name="wireexamplescallup">Method call with upload stream</a></h4>
+ <h4><a id="wireexamplescallup">Method call with upload stream</a></h4>
<p>
A method call which also involves uploading some data over
+--+-----------------------+
</pre>
- <h4><a name="wireexamplescallbi">Method call bidirectional stream</a></h4>
+ <h4><a id="wireexamplescallbi">Method call bidirectional stream</a></h4>
<p>
A method call which also involves a bi-directional stream will
</pre>
- <h4><a name="wireexamplescallmany">Method calls overlapping</a></h4>
+ <h4><a id="wireexamplescallmany">Method calls overlapping</a></h4>
<pre>
+--+-----------------------+-----------+
C --> |38| 8 | 1 | 3 | 0 | 1 | 0 | .o.oOo.o. | --> S (call 1)
+--+-----------------------+--------+
</pre>
- <h4><a name="wireexamplescallfd">Method call with passed FD</a></h4>
+ <h4><a id="wireexamplescallfd">Method call with passed FD</a></h4>
<p>
A single method call with 2 passed file descriptors and successful
</pre>
- <h2><a name="security">RPC security</a></h2>
+ <h2><a id="security">RPC security</a></h2>
<p>
There are various things to consider to ensure an implementation
of the RPC protocol can be satisfactorily secured
</p>
- <h3><a name="securitytls">Authentication/encryption</a></h3>
+ <h3><a id="securitytls">Authentication/encryption</a></h3>
<p>
The basic RPC protocol does not define or require any specific
stream can of course be tunnelled over transports such as SSH.
</p>
- <h3><a name="securitylimits">Data limits</a></h3>
+ <h3><a id="securitylimits">Data limits</a></h3>
<p>
Although the protocol itself defines many arbitrary sized data values in the
breaking compatibility of the RPC data on the wire.
</p>
- <h3><a name="securityvalidate">Data validation</a></h3>
+ <h3><a id="securityvalidate">Data validation</a></h3>
<p>
It is important that all data be fully validated before performing
execution API (e.g. corresponding libvirt public API).
</p>
- <h2><a name="internals">RPC internal APIs</a></h2>
+ <h2><a id="internals">RPC internal APIs</a></h2>
<p>
The generic internal RPC library code lives in the <code>src/rpc/</code>
purposes are:
</p>
- <h3><a name="apioverview">Overview of RPC objects</a></h3>
+ <h3><a id="apioverview">Overview of RPC objects</a></h3>
<p>
The following is a high level overview of the role of each
</dd>
</dl>
- <h3><a name="apiclientdispatch">Client RPC dispatch</a></h3>
+ <h3><a id="apiclientdispatch">Client RPC dispatch</a></h3>
<p>
The client RPC code must allow for multiple overlapping RPC method
grabs the buck, and re-enabled when the buck is released.
</p>
- <h4><a name="apiclientdispatchex1">Example with buck passing</a></h4>
+ <h4><a id="apiclientdispatchex1">Example with buck passing</a></h4>
<p>
In the first example, a second thread issues an API call
Return API2()
</pre>
- <h4><a name="apiclientdispatchex2">Example without buck passing</a></h4>
+ <h4><a id="apiclientdispatchex2">Example without buck passing</a></h4>
<p>
In this second example, a second thread issues an API call
Return API1()
</pre>
- <h4><a name="apiclientdispatchex3">Example with async events</a></h4>
+ <h4><a id="apiclientdispatchex3">Example with async events</a></h4>
<p>
In this example, only one thread is present and it has to
...
</pre>
- <h3><a name="apiserverdispatch">Server RPC dispatch</a></h3>
+ <h3><a id="apiserverdispatch">Server RPC dispatch</a></h3>
<p>
The RPC server code must support receipt of incoming RPC requests from
queue.
</p>
- <h4><a name="apiserverdispatchex1">Example with overlapping methods</a></h4>
+ <h4><a id="apiserverdispatchex1">Example with overlapping methods</a></h4>
<p>
This example illustrates processing of two incoming methods with
...
</pre>
- <h4><a name="apiserverdispatchex2">Example with stream data</a></h4>
+ <h4><a id="apiserverdispatchex2">Example with stream data</a></h4>
<p>
This example illustrates processing of stream data
plugin for virtual machine disk mutual exclusion.
</p>
- <h2><a name="background">virtlockd background</a></h2>
+ <h2><a id="background">virtlockd background</a></h2>
<p>
The virtlockd daemon is a single purpose binary which
commonly used filesystems.
</p>
- <h2><a name="sanlock">virtlockd daemon setup</a></h2>
+ <h2><a id="sanlock">virtlockd daemon setup</a></h2>
<p>
In most OS, the virtlockd daemon itself will not require
setup at all.
</p>
- <h2><a name="lockdplugin">libvirt lockd plugin configuration</a></h2>
+ <h2><a id="lockdplugin">libvirt lockd plugin configuration</a></h2>
<p>
Once the virtlockd daemon is running, or setup to autostart,
the same locking mechanism
</p>
- <h2><a name="qemuconfig">QEMU/KVM driver configuration</a></h2>
+ <h2><a id="qemuconfig">QEMU/KVM driver configuration</a></h2>
<p>
The QEMU driver is capable of using the virtlockd plugin
plugin for virtual machine disk mutual exclusion.
</p>
- <h2><a name="sanlock">Sanlock daemon setup</a></h2>
+ <h2><a id="sanlock">Sanlock daemon setup</a></h2>
<p>
On many operating systems, the <strong>sanlock</strong> plugin
steps as necessary.
</p>
- <h2><a name="sanlockplugin">libvirt sanlock plugin configuration</a></h2>
+ <h2><a id="sanlockplugin">libvirt sanlock plugin configuration</a></h2>
<p>
Once the sanlock daemon is running, the next step is to
unique value for the host.
</p>
- <h2><a name="sanlockstorage">libvirt sanlock storage configuration</a></h2>
+ <h2><a id="sanlockstorage">libvirt sanlock storage configuration</a></h2>
<p>
The sanlock plugin needs to create leases in a directory
it should be sufficient to run the cleanup once a week.
</p>
- <h2><a name="qemuconfig">QEMU/KVM driver configuration</a></h2>
+ <h2><a id="qemuconfig">QEMU/KVM driver configuration</a></h2>
<p>
The QEMU/KVM driver is fully integrated with the lock
</pool>
</pre>
- <h2><a name="domainconfig">Domain configuration</a></h2>
+ <h2><a id="domainconfig">Domain configuration</a></h2>
<p>
In case sanlock loses access to disk locks for some reason, it will
aware filesystem.
</p>
- <h2><a name="plugins">Lock manager plugins</a></h2>
+ <h2><a id="plugins">Lock manager plugins</a></h2>
<p>
The lock manager framework has a pluggable architecture,
<ul id="toc"/>
<h2>
- <a name="log_library">Logging in the library</a>
+ <a id="log_library">Logging in the library</a>
</h2>
<p>The logging functionalities in libvirt are based on 3 key concepts,
similar to the one present in other generic logging facilities like
</ul>
<h2>
- <a name="log_config">Configuring logging in the library</a>
+ <a id="log_config">Configuring logging in the library</a>
</h2>
<p>The library configuration of logging is through 3 environment variables
allowing to control the logging behaviour:</p>
have an error in a filter or output string, some of the settings may be
applied up to the point at which libvirt encountered the error.</p>
<h2>
- <a name="log_daemon">Logging in the daemon</a>
+ <a id="log_daemon">Logging in the daemon</a>
</h2>
<p>Similarly the daemon logging behaviour can be tuned using 3 config
variables, stored in the configuration file:</p>
for debugging purposes by sending the daemon a USR2 signal:</p>
<pre>killall -USR2 libvirtd</pre>
<h2>
- <a name="log_syntax">Syntax for filters and output values</a>
+ <a id="log_syntax">Syntax for filters and output values</a>
</h2>
<p>The syntax for filters and outputs is the same for both types of
variables.</p>
but also log all debug and information included in the
file <code>/tmp/libvirt.log</code></p>
- <h2><a name="journald">Systemd journal fields</a></h2>
+ <h2><a id="journald">Systemd journal fields</a></h2>
<p>
When logging to the systemd journal, the following fields
<dd>The libvirt error code (values from virErrorCode enum), if LIBVIRT_SOURCE="error"</dd>
</dl>
- <h3><a name="journaldids">Well known message ID values</a></h3>
+ <h3><a id="journaldids">Well known message ID values</a></h3>
<p>
Certain areas of the code will emit log records tagged with well known
</pre>
<h2>
- <a name="log_examples">Examples</a>
+ <a id="log_examples">Examples</a>
</h2>
<p>For example setting up the following:</p>
<pre>export LIBVIRT_DEBUG=1
libvirt implements several options for migration.
</p>
- <h2><a name="transport">Network data transports</a></h2>
+ <h2><a id="transport">Network data transports</a></h2>
<p>
There are two options for the data transport used during migration, either
over a libvirtd connection.
</p>
- <h3><a name="transportnative">Hypervisor native transport</a></h3>
+ <h3><a id="transportnative">Hypervisor native transport</a></h3>
<p>
<em>Native</em> data transports may or may not support encryption, depending
on the hypervisor in question, but will typically have the lowest computational costs
<img class="diagram" src="migration-native.png" alt="Migration native path"/>
</p>
- <h3><a name="transporttunnel">libvirt tunnelled transport</a></h3>
+ <h3><a id="transporttunnel">libvirt tunnelled transport</a></h3>
<p>
<em>Tunnelled</em> data transports will always be capable of strong encryption
since they are able to leverage the capabilities built in to the libvirt RPC protocol.
<img class="diagram" src="migration-tunnel.png" alt="Migration tunnel path"/>
</p>
- <h2><a name="flow">Communication control paths/flows</a></h2>
+ <h2><a id="flow">Communication control paths/flows</a></h2>
<p>
Migration of virtual machines requires close co-ordination of the two
which may be on the source, the destination, or a third host.
</p>
- <h3><a name="flowmanageddirect">Managed direct migration</a></h3>
+ <h3><a id="flowmanageddirect">Managed direct migration</a></h3>
<p>
With <em>managed direct</em> migration, the libvirt client process
</p>
- <h3><a name="flowpeer2peer">Managed peer to peer migration</a></h3>
+ <h3><a id="flowpeer2peer">Managed peer to peer migration</a></h3>
<p>
With <em>peer to peer</em> migration, the libvirt client process only
</p>
- <h3><a name="flowunmanageddirect">Unmanaged direct migration</a></h3>
+ <h3><a id="flowunmanageddirect">Unmanaged direct migration</a></h3>
<p>
With <em>unmanaged direct</em> migration, neither the libvirt client
</p>
- <h2><a name="security">Data security</a></h2>
+ <h2><a id="security">Data security</a></h2>
<p>
Since the migration data stream includes a complete copy of the guest
facility should be used.
</p>
- <h2><a name="offline">Offline migration</a></h2>
+ <h2><a id="offline">Offline migration</a></h2>
<p>
Offline migration transfers inactive the definition of a domain
offline migration.
</p>
- <h2><a name="uris">Migration URIs</a></h2>
+ <h2><a id="uris">Migration URIs</a></h2>
<p>
Initiating a guest migration requires the client application to
to comply with local firewall policies.</li>
</ol>
- <h2><a name="config">Configuration file handling</a></h2>
+ <h2><a id="config">Configuration file handling</a></h2>
<p>
There are two types of virtual machine known to libvirt. A <em>transient</em>
</tbody>
</table>
- <h2><a name="scenarios">Migration scenarios</a></h2>
+ <h2><a id="scenarios">Migration scenarios</a></h2>
- <h3><a name="scenarionativedirect">Native migration, client to two libvirtd servers</a></h3>
+ <h3><a id="scenarionativedirect">Native migration, client to two libvirtd servers</a></h3>
<p>
At an API level this requires use of virDomainMigrate, without the
Supported by Xen, QEMU, VMware and VirtualBox drivers
</p>
- <h3><a name="scenarionativepeer2peer">Native migration, client to and peer2peer between, two libvirtd servers</a></h3>
+ <h3><a id="scenarionativepeer2peer">Native migration, client to and peer2peer between, two libvirtd servers</a></h3>
<p>
virDomainMigrate, with the VIR_MIGRATE_PEER2PEER flag set,
Supported by QEMU driver
</p>
- <h3><a name="scenariotunnelpeer2peer1">Tunnelled migration, client and peer2peer between two libvirtd servers</a></h3>
+ <h3><a id="scenariotunnelpeer2peer1">Tunnelled migration, client and peer2peer between two libvirtd servers</a></h3>
<p>
virDomainMigrate, with the VIR_MIGRATE_PEER2PEER & VIR_MIGRATE_TUNNELLED
Supported by QEMU driver
</p>
- <h3><a name="nativedirectunmanaged">Native migration, client to one libvirtd server</a></h3>
+ <h3><a id="nativedirectunmanaged">Native migration, client to one libvirtd server</a></h3>
<p>
virDomainMigrateToURI, without the VIR_MIGRATE_PEER2PEER flag set,
Supported by Xen driver
</p>
- <h3><a name="nativepeer2peer">Native migration, peer2peer between two libvirtd servers</a></h3>
+ <h3><a id="nativepeer2peer">Native migration, peer2peer between two libvirtd servers</a></h3>
<p>
virDomainMigrateToURI, with the VIR_MIGRATE_PEER2PEER flag set,
Supported by the QEMU driver
</p>
- <h3><a name="scenariotunnelpeer2peer2">Tunnelled migration, peer2peer between two libvirtd servers</a></h3>
+ <h3><a id="scenariotunnelpeer2peer2">Tunnelled migration, peer2peer between two libvirtd servers</a></h3>
<p>
virDomainMigrateToURI, with the VIR_MIGRATE_PEER2PEER & VIR_MIGRATE_TUNNELLED
users. This is where NSS module comes handy.
</p>
- <h2><a name="Installation">Installation</a></h2>
+ <h2><a id="Installation">Installation</a></h2>
<p>
Installing the module is really easy:
# yum install libvirt-nss
</pre>
- <h2><a name="Configuration">Configuration</a></h2>
+ <h2><a id="Configuration">Configuration</a></h2>
<p>
Enabling the module is really easy. Just add <b>libvirt</b> into
lookup given host name.
</p>
- <h2><a name="Sources">Sources of information</a></h2>
+ <h2><a id="Sources">Sources of information</a></h2>
<p>
As of <code>v3.0.0</code> release, libvirt offers two NSS modules
resolved).
</p>
- <h2><a name="Internals">How does it work?</a></h2>
+ <h2><a id="Internals">How does it work?</a></h2>
<p>
Whenever an Unix process wants to do a host name translation
should carefully chose the lookup order.
</p>
- <h2><a name="Limitations">Limitations</a></h2>
+ <h2><a id="Limitations">Limitations</a></h2>
<ol>
<li>The <code>libvirt</code> NSS module matches only hostnames provided by guest.
<xsl:for-each select="/html:html/html:body/html:h2[count(html:a) = 1]">
<xsl:variable name="thish2" select="."/>
<li>
- <a href="#{html:a/@name}"><xsl:value-of select="html:a/text()"/></a>
+ <a href="#{html:a/@id}"><xsl:value-of select="html:a/text()"/></a>
<xsl:if test="count(./following-sibling::html:h3[preceding-sibling::html:h2[1] = $thish2 and count(html:a) = 1]) > 0">
<ul>
<xsl:for-each select="./following-sibling::html:h3[preceding-sibling::html:h2[1] = $thish2 and count(html:a) = 1]">
<xsl:variable name="thish3" select="."/>
<li>
- <a href="#{html:a/@name}"><xsl:value-of select="html:a/text()"/></a>
+ <a href="#{html:a/@id}"><xsl:value-of select="html:a/text()"/></a>
<xsl:if test="count(./following-sibling::html:h4[preceding-sibling::html:h3[1] = $thish3 and count(html:a) = 1]) > 0">
<ul>
<xsl:for-each select="./following-sibling::html:h4[preceding-sibling::html:h3[1] = $thish3 and count(html:a) = 1]">
<xsl:variable name="thish4" select="."/>
<li>
- <a href="#{html:a/@name}"><xsl:value-of select="html:a/text()"/></a>
+ <a href="#{html:a/@id}"><xsl:value-of select="html:a/text()"/></a>
<xsl:if test="count(./following-sibling::html:h5[preceding-sibling::html:h4[1] = $thish4 and count(html:a) = 1]) > 0">
<ul>
<xsl:for-each select="./following-sibling::html:h5[preceding-sibling::html:h4[1] = $thish4 and count(html:a) = 1]">
<xsl:variable name="thish5" select="."/>
<li>
- <a href="#{html:a/@name}"><xsl:value-of select="html:a/text()"/></a>
+ <a href="#{html:a/@id}"><xsl:value-of select="html:a/text()"/></a>
<xsl:if test="count(./following-sibling::html:h6[preceding-sibling::html:h5[1] = $thish5 and count(html:a) = 1]) > 0">
<ul>
<xsl:for-each select="./following-sibling::html:h6[preceding-sibling::html:h5[1] = $thish5 and count(html:a) = 1]">
<li>
- <a href="#{html:a/@name}"><xsl:value-of select="html:a/text()"/></a>
+ <a href="#{html:a/@id}"><xsl:value-of select="html:a/text()"/></a>
</li>
</xsl:for-each>
</ul>
<xsl:template match="html:h2 | html:h3 | html:h4 | html:h5 | html:h6" mode="content">
<xsl:element name="{name()}">
<xsl:apply-templates mode="copy" />
- <xsl:if test="./html:a/@name">
- <a class="headerlink" href="#{html:a/@name}" title="Permalink to this headline">¶</a>
+ <xsl:if test="./html:a/@id">
+ <a class="headerlink" href="#{html:a/@id}" title="Permalink to this headline">¶</a>
</xsl:if>
</xsl:element>
</xsl:template>
<ul id="toc"></ul>
<h2>
- <a name="Remote_basic_usage">Basic usage</a>
+ <a id="Remote_basic_usage">Basic usage</a>
</h2>
<p>
On the remote machine, <code>libvirtd</code> should be running in general.
much slower than, say, direct hypervisor calls. </li>
</ul>
<h2>
- <a name="Remote_transports">Transports</a>
+ <a id="Remote_transports">Transports</a>
</h2>
<p>
Remote libvirt supports a range of transports:
The default transport, if no other is specified, is <code>tls</code>.
</p>
<h2>
- <a name="Remote_URI_reference">Remote URIs</a>
+ <a id="Remote_URI_reference">Remote URIs</a>
</h2>
<p>
See also: <a href="uri.html">documentation on ordinary ("local") URIs</a>.
and use a different known_hosts file.</li>
</ul>
<h3>
- <a name="Remote_URI_parameters">Extra parameters</a>
+ <a id="Remote_URI_parameters">Extra parameters</a>
</h3>
<p>
Extra parameters can be added to remote URIs as part
</tr>
</table>
<h2>
- <a name="Remote_certificates">Generating TLS certificates</a>
+ <a id="Remote_certificates">Generating TLS certificates</a>
</h2>
<h3>
- <a name="Remote_PKI">Public Key Infrastructure set up</a>
+ <a id="Remote_PKI">Public Key Infrastructure set up</a>
</h3>
<p>
If you are unsure how to create TLS certificates, skip to the
<li> For the root user, the global default locations will always be used.</li>
</ul>
<h3>
- <a name="Remote_TLS_background">Background to TLS certificates</a>
+ <a id="Remote_TLS_background">Background to TLS certificates</a>
</h3>
<p>
Libvirt supports TLS certificates for verifying the identity
permissive, depending on your needs.
</p>
<h3>
- <a name="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a>
+ <a id="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a>
</h3>
<p>
You will need the <a href="http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html">GnuTLS
for your clients and servers.
</p>
<h3>
- <a name="Remote_TLS_server_certificates">Issuing server certificates</a>
+ <a id="Remote_TLS_server_certificates">Issuing server certificates</a>
</h3>
<p>
For each server (libvirtd) you need to issue a certificate
</li>
</ul>
<h3>
- <a name="Remote_TLS_client_certificates">Issuing client certificates</a>
+ <a id="Remote_TLS_client_certificates">Issuing client certificates</a>
</h3>
<p>
For each client (ie. any program linked with libvirt, such as
</li>
</ol>
<h3>
- <a name="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a>
+ <a id="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a>
</h3>
<dl>
<dt> failed to verify client's certificate </dt>
It will try to point out the possible problems and provide solutions to
fix the set up up to a point where you have secure remote access.</p>
<h2>
- <a name="Remote_libvirtd_configuration">libvirtd configuration file</a>
+ <a id="Remote_libvirtd_configuration">libvirtd configuration file</a>
</h2>
<p>
Libvirtd (the remote daemon) is configured from a file called
</tr>
</table>
<h2>
- <a name="Remote_IPv6">IPv6 support</a>
+ <a id="Remote_IPv6">IPv6 support</a>
</h2>
<p>
The libvirtd service and libvirt remote client driver both use the
should just 'do the right thing(tm)'.
</p>
<h2>
- <a name="Remote_limitations">Limitations</a>
+ <a id="Remote_limitations">Limitations</a>
</h2>
<ul>
<li> Fine-grained authentication: libvirt in general,
</p>
- <h2><a name="diskimage">Disk image handling</a></h2>
+ <h2><a id="diskimage">Disk image handling</a></h2>
- <h3><a name="diskimageformat">Disk image format probing</a></h3>
+ <h3><a id="diskimageformat">Disk image format probing</a></h3>
<p>
Historically there have been multiple flaws in QEMU and most
are accessible to / originate from an untrusted source.
</p>
- <h3><a name="diskimagebacking">Disk image backing files</a></h3>
+ <h3><a id="diskimagebacking">Disk image backing files</a></h3>
<p>
If a management application allows users to upload pre-created
file set. If a backing file is seen, reject the image.
</p>
- <h3><a name="diskimagesize">Disk image size validation</a></h3>
+ <h3><a id="diskimagesize">Disk image size validation</a></h3>
<p>
If an application allows users to upload pre-created disk
limit.
</p>
- <h3><a name="diskimageaccess">Disk image data access</a></h3>
+ <h3><a id="diskimageaccess">Disk image data access</a></h3>
<p>
If an untrusted disk image is ever mounted on the host OS by
tools and APIs for accessing disks
</p>
- <h2><a name="migration">Guest migration network</a></h2>
+ <h2><a id="migration">Guest migration network</a></h2>
<p>
Most hypervisors with support for guest migration between hosts
RPC protocol connections.</li>
</ul>
- <h2><a name="storage">Storage encryption</a></h2>
+ <h2><a id="storage">Storage encryption</a></h2>
<p>
Virtual disk images will typically contain confidential data
potential security issues.
</p>
- <h2><a name="reporting">Reporting security issues</a></h2>
+ <h2><a id="reporting">Reporting security issues</a></h2>
<p>
In the event that a bug in libvirt is found which is
moderator and the reporter copied on any replies.
</p>
- <h2><a name="seclist">Security team</a></h2>
+ <h2><a id="seclist">Security team</a></h2>
<p>
The libvirt security team is made up of a subset of the libvirt
described below.
</p>
- <h2><a name="embargo">Publication embargo policy</a></h2>
+ <h2><a id="embargo">Publication embargo policy</a></h2>
<p>
The libvirt security team operates a policy of
</p>
- <h2><a name="cve">CVE allocation</a></h2>
+ <h2><a id="cve">CVE allocation</a></h2>
<p>
The libvirt security team will associate each security issue with
the vendor security engineers on the security team.
</p>
- <h2><a name="branches">Branch fixing policy</a></h2>
+ <h2><a id="branches">Branch fixing policy</a></h2>
<p>
The libvirt community maintains one or more stable release branches
other release branches where applicable.
</p>
- <h2><a name="notification">Notification of issues</a></h2>
+ <h2><a id="notification">Notification of issues</a></h2>
<p>
When an embargo expires, security issues will be announced on both
</p>
<ul id="toc"></ul>
- <h2><a name="StorageBackendDir">Directory pool</a></h2>
+ <h2><a id="StorageBackendDir">Directory pool</a></h2>
<p>
A pool with a type of <code>dir</code> provides the means to manage
files within a directory. The files can be fully allocated raw files,
</p>
- <h2><a name="StorageBackendFS">Filesystem pool</a></h2>
+ <h2><a id="StorageBackendFS">Filesystem pool</a></h2>
<p>
This is a variant of the directory pool. Instead of creating a
directory on an existing mounted filesystem though, it expects
</p>
- <h2><a name="StorageBackendNetFS">Network filesystem pool</a></h2>
+ <h2><a id="StorageBackendNetFS">Network filesystem pool</a></h2>
<p>
This is a variant of the filesystem pool. Instead of requiring
a local block device as the source, it requires the name of a
</p>
- <h2><a name="StorageBackendLogical">Logical volume pool</a></h2>
+ <h2><a id="StorageBackendLogical">Logical volume pool</a></h2>
<p>
This provides a pool based on an LVM volume group. For a
pre-defined LVM volume group, simply providing the group
</p>
- <h2><a name="StorageBackendDisk">Disk pool</a></h2>
+ <h2><a id="StorageBackendDisk">Disk pool</a></h2>
<p>
This provides a pool based on a physical disk. Volumes are created
by adding partitions to the disk. Disk pools have constraints
</ul>
- <h2><a name="StorageBackendISCSI">iSCSI pool</a></h2>
+ <h2><a id="StorageBackendISCSI">iSCSI pool</a></h2>
<p>
This provides a pool based on an iSCSI target. Volumes must be
pre-allocated on the iSCSI server, and cannot be created via
The iSCSI volume pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendSCSI">SCSI pool</a></h2>
+ <h2><a id="StorageBackendSCSI">SCSI pool</a></h2>
<p>
This provides a pool based on a SCSI HBA. Volumes are preexisting SCSI
LUNs, and cannot be created via the libvirt APIs. Since /dev/XXX names
The SCSI volume pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendMultipath">Multipath pool</a></h2>
+ <h2><a id="StorageBackendMultipath">Multipath pool</a></h2>
<p>
This provides a pool that contains all the multipath devices on the
host. Therefore, only one Multipath pool may be configured per host.
The Multipath volume pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendRBD">RBD pool</a></h2>
+ <h2><a id="StorageBackendRBD">RBD pool</a></h2>
<p>
This storage driver provides a pool which contains all RBD
images in a RADOS pool. RBD (RADOS Block Device) is part
The RBD pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendSheepdog">Sheepdog pool</a></h2>
+ <h2><a id="StorageBackendSheepdog">Sheepdog pool</a></h2>
<p>
This provides a pool based on a Sheepdog Cluster.
Sheepdog is a distributed storage system for QEMU/KVM.
The Sheepdog pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendGluster">Gluster pool</a></h2>
+ <h2><a id="StorageBackendGluster">Gluster pool</a></h2>
<p>
This provides a pool based on native Gluster access. Gluster is
a distributed file system that can be exposed to the user via
pool type.
</p>
- <h2><a name="StorageBackendZFS">ZFS pool</a></h2>
+ <h2><a id="StorageBackendZFS">ZFS pool</a></h2>
<p>
This provides a pool based on the ZFS filesystem. Initially it was developed
for FreeBSD, and <span class="since">since 1.3.2</span> experimental support
<p>
The ZFS volume pool does not use the volume format type element.
</p>
- <h2><a name="StorageBackendVstorage">Vstorage pool</a></h2>
+ <h2><a id="StorageBackendVstorage">Vstorage pool</a></h2>
<p>
This provides a pool based on Virtuozzo storage. Virtuozzo Storage is
a highly available distributed software-defined storage with built-in
To this end, libvirt uses URIs as used on the Web and as defined in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. This page
documents libvirt URIs.
</p>
- <h2><a name="URI_libvirt">Specifying URIs to libvirt</a></h2>
+ <h2><a id="URI_libvirt">Specifying URIs to libvirt</a></h2>
<p>
The URI is passed as the <code>name</code> parameter to
virConnectPtr conn = virConnectOpenReadOnly (<b>"test:///default"</b>);
</pre>
<h2>
- <a name="URI_config">Configuring URI aliases</a>
+ <a id="URI_config">Configuring URI aliases</a>
</h2>
<p>
set, no alias lookup will be attempted.
</p>
- <h2><a name="URI_default">Default URI choice</a></h2>
+ <h2><a id="URI_default">Default URI choice</a></h2>
<p>
If the URI passed to <code>virConnectOpen*</code> is NULL, then libvirt will use the following
</ol>
<h2>
- <a name="URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a>
+ <a id="URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a>
</h2>
<p>
In virsh use the <code>-c</code> or <code>--connect</code> option:
virt-install <b>--connect=test:///default</b> <i>[other options]</i>
</pre>
<h2>
- <a name="URI_xen">xen:/// URI</a>
+ <a id="URI_xen">xen:/// URI</a>
</h2>
<p>
<i>This section describes a feature which is new in libvirt >
use the URI <code>xen:///</code>.
</p>
<h2>
- <a name="URI_qemu">qemu:///... QEMU and KVM URIs</a>
+ <a id="URI_qemu">qemu:///... QEMU and KVM URIs</a>
</h2>
<p>
To use QEMU support in libvirt you must be running the
here</a>.
</p>
<h2>
- <a name="URI_remote">Remote URIs</a>
+ <a id="URI_remote">Remote URIs</a>
</h2>
<p>
Remote URIs are formed by taking ordinary local URIs and adding a
for libvirt remote support</a>.
</p>
<h2>
- <a name="URI_test">test:///... Test URIs</a>
+ <a id="URI_test">test:///... Test URIs</a>
</h2>
<p>
The test driver is a dummy hypervisor for test purposes.
</li>
</ul>
<h2>
- <a name="URI_legacy">Other & legacy URI formats</a>
+ <a id="URI_legacy">Other & legacy URI formats</a>
</h2>
<h3>
- <a name="URI_NULL">NULL and empty string URIs</a>
+ <a id="URI_NULL">NULL and empty string URIs</a>
</h3>
<p>
Libvirt allows you to pass a <code>NULL</code> pointer to
for future proofing it should choose a full <a href="#URI_xen"><code>xen:///</code> URI</a>.
</p>
<h3>
- <a name="URI_file">File paths (xend-unix-server)</a>
+ <a id="URI_file">File paths (xend-unix-server)</a>
</h3>
<p>
If XenD is running and configured in <code>/etc/xen/xend-config.sxp</code>:
virsh -c ///var/run/xend/xend-socket
</pre>
<h3>
- <a name="URI_http">Legacy: <code>http://...</code> (xend-http-server)</a>
+ <a id="URI_http">Legacy: <code>http://...</code> (xend-http-server)</a>
</h3>
<p>
If XenD is running and configured in <code>/etc/xen/xend-config.sxp</code>:
documentation as "unix server" or "http server".</li>
</ol>
<h3>
- <a name="URI_legacy_xen">Legacy: <code>"xen"</code></a>
+ <a id="URI_legacy_xen">Legacy: <code>"xen"</code></a>
</h3>
<p>
Another legacy URI is to specify name as the string
hypervisor. However you should prefer a full <a href="#URI_xen"><code>xen:///</code> URI</a> in all future code.
</p>
<h3>
- <a name="URI_legacy_proxy">Legacy: Xen proxy</a>
+ <a id="URI_legacy_proxy">Legacy: Xen proxy</a>
</h3>
<p>
Libvirt continues to support connections to a separately running Xen
<ul id="toc"></ul>
- <h2><a name="description">Description</a></h2>
+ <h2><a id="description">Description</a></h2>
<p>
The new <b>Virsh Command Reference</b>, for documenting the commands
<p> </p>
- <h2><a name="viewing">Viewing Online</a></h2>
+ <h2><a id="viewing">Viewing Online</a></h2>
<p>
The latest version can be viewed directly online:
<p> </p>
- <h2><a name="downloading">Downloading</a></h2>
+ <h2><a id="downloading">Downloading</a></h2>
<p>
The latest version of the Virsh Command Reference can be downloaded:
</li>
</ul>
- <h2><a name="git">DocBook source GIT repository</a></h2>
+ <h2><a id="git">DocBook source GIT repository</a></h2>
<p>
The DocBook source is maintained in a <a
href="http://git-scm.com/">git</a> repository available on
as well but we either haven't tested or received reports for them.
</p>
- <h2><a name="installer">Installation packages</a></h2>
+ <h2><a id="installer">Installation packages</a></h2>
<p>
Users who need pre-built Windows DLLs of libvirt are advised
against libvirt.
</p>
- <h2><a name="conntypes">Connection types</a></h2>
+ <h2><a id="conntypes">Connection types</a></h2>
<p>
These connection types are known to work:
be used in security sensitive environments.</b>
</p>
- <h2><a name="esx">Connecting to VMware ESX/vSphere</a></h2>
+ <h2><a id="esx">Connecting to VMware ESX/vSphere</a></h2>
<p>
Details on the capabilities, certificates, and connection string
<a href="http://libvirt.org/drvesx.html">http://libvirt.org/drvesx.html</a>
- <h2><a name="tlscerts">TLS Certificates</a></h2>
+ <h2><a id="tlscerts">TLS Certificates</a></h2>
<p>
TLS certificates need to have been created and placed in the correct
<li>C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\private\clientkey.pem</li>
</ul>
- <h2><a name="feedback">Feedback</a></h2>
+ <h2><a id="feedback">Feedback</a></h2>
<p>
Feedback and suggestions on changes to make and what else to include
<a href="contact.html">are desired</a>.
</p>
- <h2><a name="compiling">Compiling yourself</a></h2>
+ <h2><a id="compiling">Compiling yourself</a></h2>
<p>
Libvirt can be compiled on Windows using the free
<a href="http://www.mingw.org/">MinGW compiler</a>.
</p>
- <h3><a name="msys_setup">MSYS Build script</a></h3>
+ <h3><a id="msys_setup">MSYS Build script</a></h3>
<p>
The easiest way is to use the <b>msys_setup</b> script, developed by
<a href="https://github.com/photron/msys_setup">https://github.com/photron/msys_setup</a>
- <h3><a name="cross-compile">Cross compiling</a></h3>
+ <h3><a id="cross-compile">Cross compiling</a></h3>
<p>
You can also cross-compile to a Windows target from a Fedora machine
(which includes a working libvirt specfile).
</p>
- <h3><a name="configure">By hand</a></h3>
+ <h3><a id="configure">By hand</a></h3>
<p>
Use these options when following the instructions on the
projects / libvirt.git / commitdiff