<?xml version="1.0" encoding="UTF-8"?>
<!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">
<!--
This file is autogenerated from formatnode.html.in
Do not edit this file. Changes will be lost.
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="SHORTCUT ICON" href="32favicon.png" />
<title>libvirt: Node devices XML format</title>
<meta name="description" content="libvirt, virtualization, virtualization API" />
</head>
<body>
<div id="header">
<div id="headerLogo"></div>
<div id="headerSearch">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
<input id="query" name="query" type="text" size="12" value="" />
<input id="submit" name="submit" type="submit" value="Search" />
</div></form>
</div>
</div>
<div id="body">
<div id="menu">
<ul class="l0"><li>
<div>
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
</div>
</li><li>
<div>
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
</div>
</li><li>
<div>
<a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
</div>
</li><li>
<div>
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
</div>
</li><li>
<div>
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
<ul class="l1"><li>
<div>
<a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
</div>
</li><li>
<div>
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
</div>
</li><li>
<div>
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
</div>
</li><li>
<div>
<a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
<ul class="l2"><li>
<div>
<a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
</div>
</li><li>
<div>
<a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
</div>
</li><li>
<div>
<a title="Network filter XML format" class="inactive" href="formatnwfilter.html">Network Filtering</a>
</div>
</li><li>
<div>
<a title="The storage pool and volume XML format" class="inactive" href="formatstorage.html">Storage</a>
</div>
</li><li>
<div>
<a title="Storage volume encryption XML format" class="inactive" href="formatstorageencryption.html">Storage Encryption</a>
</div>
</li><li>
<div>
<a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
</div>
</li><li>
<div>
<span class="active">Node Devices</span>
</div>
</li><li>
<div>
<a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
</div>
</li><li>
<div>
<a title="The snapshot XML format" class="inactive" href="formatsnapshot.html">Snapshots</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
</div>
</li><li>
<div>
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
</div>
</li><li>
<div>
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
</div>
</li><li>
<div>
<a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
</div>
</li><li>
<div>
<a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
</div>
</li><li>
<div>
<a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
</div>
</li><li>
<div>
<a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
</div>
</li><li>
<div>
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
</div>
</li><li>
<div>
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
</div>
</li><li>
<div>
<a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
</div>
</li><li>
<div>
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
</div>
</li><li>
<div>
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
</div>
</li></ul>
</div>
<div id="content">
<h1>Node devices XML format</h1>
<ul><li>
<a href="#NodedevAttributes">Node Device XML</a>
</li><li>
<a href="#nodeExample">Examples</a>
</li></ul>
<h2>
<a name="NodedevAttributes" id="NodedevAttributes">Node Device XML</a>
</h2>
<p>
There are several libvirt functions, all with the
prefix <code>virNodeDevice</code>, which deal with management of
host devices that can be handed to guests via passthrough as
<hostdev> elements
in <a href="formatdomain.html#elementsUSB">the domain XML</a>.
These devices are represented as a hierarchy, where a device on
a bus has a parent of the bus controller device; the root of the
hierarchy is the node named "computer".
</p>
<p>
When represented in XML, a node device uses the
top-level <code>device</code> element, with the following
elements present according to the type of device:
</p>
<dl><dt><code>name</code></dt><dd>The name for this device. The name will be alphanumeric,
with words separated by underscore. For many devices, the
name is just the bus type and address, as in
"pci_0000_00_02_1" or "usb_1_5_3", but some devices are able
to provide more specific names, such as
"net_eth1_00_27_13_6a_fe_00".
</dd><dt><code>parent</code></dt><dd>If this element is present, it names the parent device (that
is, a controller to which this node belongs).
</dd><dt><code>capability</code></dt><dd>This node appears for each capability that libvirt
associates with a node. A mandatory
attribute <code>type</code> lists which category the device
belongs to, and controls which further subelements will be
present to describe the node:
<dl><dt><code>system</code></dt><dd>Describes the overall host. Sub-elements include:
<dl><dt><code>product</code></dt><dd>If present, a simple text string giving the product
name of the system.</dd><dt><code>hardware</code></dt><dd>Describes the hardware of the system, including
sub-elements for <code>vendor</code>, <code>version</code>,
<code>serial</code>, and <code>uuid</code>.</dd><dt><code>firmware</code></dt><dd>Describes the firmware of the system, including
sub-elements for <code>vendor</code>, <code>version</code>,
and <code>release_date</code>.</dd></dl>
</dd><dt><code>pci</code></dt><dd>Describes a device on the host's PCI bus. Sub-elements
include:
<dl><dt><code>domain</code></dt><dd>Which domain the device belongs to.</dd><dt><code>bus</code></dt><dd>Which bus within the domain.</dd><dt><code>slot</code></dt><dd>Which slot within the bus.</dd><dt><code>function</code></dt><dd>Which function within the slot.</dd><dt><code>product</code></dt><dd>Product details from the device ROM, including an
attribute <code>id</code> with the hexadecimal product
id, and an optional text description of that id.</dd><dt><code>vendor</code></dt><dd>Vendor details from the device ROM, including an
attribute <code>id</code> with the hexadecimal vendor
id, and an optional text name of that vendor.</dd></dl>
</dd><dt><code>usb_device</code></dt><dd>Describes a device on the host's USB bus, based on its
location within the bus. Sub-elements include:
<dl><dt><code>bus</code></dt><dd>Which bus the device belongs to.</dd><dt><code>device</code></dt><dd>Which device within the bus.</dd><dt><code>product</code></dt><dd>Product details from the device ROM, including an
attribute <code>id</code> with the hexadecimal product
id, and an optional text description of that id.</dd><dt><code>vendor</code></dt><dd>Vendor details from the device ROM, including an
attribute <code>id</code> with the hexadecimal vendor
id, and an optional text name of that vendor.</dd></dl>
</dd><dt><code>usb</code></dt><dd>Describes a USB device, based on its advertised driver
interface. Sub-elements include:
<dl><dt><code>number</code></dt><dd>The device number.</dd><dt><code>number</code></dt><dd>The device class.</dd><dt><code>number</code></dt><dd>The device subclass.</dd><dt><code>number</code></dt><dd>The device protocol.</dd><dt><code>description</code></dt><dd>If present, a description of the device.</dd></dl>
</dd><dt><code>net</code></dt><dd>Describes a device capable for use as a network
interface. Sub-elements include:
<dl><dt><code>interface</code></dt><dd>The interface name tied to this device.</dd><dt><code>address</code></dt><dd>If present, the MAC address of the device.</dd><dt><code>capability</code></dt><dd>A network protocol exposed by the device, where the
attribute <code>type</code> can be "80203" for IEEE
802.3, or "80211" for various flavors of IEEE 802.11.
</dd></dl>
</dd><dt><code>scsi_host</code></dt><dd>Describes a SCSI host device. Sub-elements include:
<dl><dt><code>host</code></dt><dd>The SCSI host number.</dd><dt><code>capability</code></dt><dd>Current capabilities include "vports_ops" (indicates
vport operations are supported) and "fc_host", the later
implies following sub-elements: <code>wwnn</code>,
<code>wwpn</code>, <code>fabric_wwn</code>.
</dd></dl>
</dd><dt><code>scsi</code></dt><dd>Describes a SCSI device. Sub-elements include:
<dl><dt><code>host</code></dt><dd>The SCSI host containing the device.</dd><dt><code>bus</code></dt><dd>The bus within the host.</dd><dt><code>target</code></dt><dd>The target within the bus.</dd><dt><code>lun</code></dt><dd>The lun within the target.</dd><dt><code>type</code></dt><dd>The type of SCSI device.</dd></dl>
</dd><dt><code>storage</code></dt><dd>Describes a device usable for storage. Sub-elements
include:
<dl><dt><code>block</code></dt><dd>A block device file name that accesses the storage
present on the device.</dd><dt><code>bus</code></dt><dd>If present, the name of the bus the device is found
on.</dd><dt><code>drive_type</code></dt><dd>The type of the drive, such as "disk" or
"cdrom".</dd><dt><code>model</code></dt><dd>Any model information available from the
device.</dd><dt><code>vendor</code></dt><dd>Any vendor information available from the
device.</dd><dt><code>serial</code></dt><dd>Any serial number information available from the
device.</dd><dt><code>size</code></dt><dd>For fixed-size storage, the amount of storage
available.</dd><dt><code>capability</code></dt><dd>If present, an additional capability is listed via
the attribute <code>type</code>. Current capabilities
include "hotpluggable" and "removable", with the
latter implying the following
sub-elements: <code>media_available</code> (0 or
1), <code>media_size</code>,
and <code>media_label</code>.</dd></dl>
</dd></dl>
</dd></dl>
<h2>
<a name="nodeExample" id="nodeExample">Examples</a>
</h2>
<p>The following are some example node device XML outputs:</p>
<pre>
<device>
<name>computer</name>
<capability type='system'>
<product>2241B36</product>
<hardware>
<vendor>LENOVO</vendor>
<version>ThinkPad T500</version>
<serial>R89055N</serial>
<uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid>
</hardware>
<firmware>
<vendor>LENOVO</vendor>
<version>6FET82WW (3.12 )</version>
<release_date>11/26/2009</release_date>
</firmware>
</capability>
</device>
<device>
<name>net_eth1_00_27_13_6a_fe_00</name>
<parent>pci_0000_00_19_0</parent>
<capability type='net'>
<interface>eth1</interface>
<address>00:27:13:6a:fe:00</address>
<capability type='80203'/>
</capability>
</device></pre>
</div>
</div>
<div id="footer">
<p id="sponsor">
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
</div>
</body>
</html>
