Skip to content

L
libvirt

openeuler / libvirt

通知 3
Star 0
Fork 0
L
libvirt

体验新版 GitCode，发现更多精彩内容 >>

切换分支/标签
查找文件 普通视图历史永久链接Permalink
api.html.in 9.9 KB
Newer Older
D
Api documentation  
Daniel Veillard 已提交
1 2 3 4 5 6 
<?xml version="1.0"?>
<html>
  <body>
    <h1>The libvirt API concepts</h1>

    <p> This page describes the main principles and architecture choices
E
docs: correct invalid xml  
Eric Blake 已提交
7 
    behind the definition of the libvirt API:</p>
J
docs: added a table of contents to the first 11 docs files  
Justin Clift 已提交
8 9 10 

    <ul id="toc"></ul>
J
api: Reword objects exposed section  
John Ferlan 已提交
11 12 13 14 15 16 17 
    <h2><a name="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
    manipulated through the API is the <code>virConnectPtr</code>, which
    represents the connection to a hypervisor. Any application using libvirt
    is likely to start using the
D
Api documentation  
Daniel Veillard 已提交
18 19 
    API by calling one of <a href="html/libvirt-libvirt.html#virConnectOpen"
    >the virConnectOpen functions</a>. You will note that those functions take
J
api: Reword objects exposed section  
John Ferlan 已提交
20 21 22 23 24 25 
    a name argument which is actually a <a href="uri.html">connection URI</a>
    to select the right hypervisor to open.
    A URI is needed to allow remote connections and also select between
    different possible hypervisors. For example, on a Linux system it may be
    possible to use both KVM and LinuxContainers on the same node. A NULL
    name will default to a preselected hypervisor, but it's probably not a
D
Api documentation  
Daniel Veillard 已提交
26 
    wise thing to do in most cases. See the <a href="uri.html">connection
E
docs: correct invalid xml  
Eric Blake 已提交
27 
    URI</a> page for a full descriptions of the values allowed.</p>
J
api: Reword objects exposed section  
John Ferlan 已提交
28 29 30 31 32 
    <p> Once the application obtains a <code class='docref'>virConnectPtr</code>
    connection to the hypervisor it can then use it to manage the hypervisor's
    available domains and related virtualization
    resources, such as storage and networking. All those are
    exposed as first class objects and connected to the hypervisor connection
D
Api documentation  
Daniel Veillard 已提交
33 34 35 36 37 38 39 
    (and the node or cluster where it is available).</p>
    <p class="image">
      <img alt="first class objects exposed by the API"
           src="libvirt-object-model.png"/>
    </p>
    <p> The figure above shows the five main objects exported by the API:</p>
    <ul>
J
api: Reword and clean lists for object description  
John Ferlan 已提交
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 
      <li><code class='docref'>virConnectPtr</code>
      <p>Represents the connection to a hypervisor. Use one of the
      <a href="html/libvirt-libvirt.html#virConnectOpen">virConnectOpen</a>
      functions to obtain connection to the hypervisor which is then used
      as a parameter to other connection API's.</p></li>
      <li><code class='docref'>virDomainPtr</code>
      <p>Represents one domain either active or defined (i.e. existing as
      permanent config file and storage but not currently running on that
      node). The function <code class='docref'>virConnectListAllDomains</code>
      lists all the domains for the hypervisor.</p></li>
      <li><code class='docref'>virNetworkPtr</code>
      <p>Represents one network either active or defined (i.e. existing
      as permanent config file and storage but not currently activated).
      The function <code class='docref'>virConnectListAllNetworks</code>
      lists all the virtualization networks for the hypervisor.</p></li>
      <li><code class='docref'>virStorageVolPtr</code>
      <p>Represents one storage volume generally used
D
Api documentation  
Daniel Veillard 已提交
57 
      as a block device available to one of the domains. The function
J
api: Reword and clean lists for object description  
John Ferlan 已提交
58 59 60 61 62 63 64 65 66 
      <code class="docref">virStorageVolLookupByPath</code> finds
      the storage volume object based on its path on the node.</p></li>
      <li><code class='docref'>virStoragePoolPtr</code>
      <p>Represents a storage pool, which is a logical area
      used to allocate and store storage volumes. The function
      <code class='docref'>virConnectListAllStoragePools</code> lists
      all of the virtualization storage pools on the hypervisor. The function
      <code class="docref">virStoragePoolLookupByVolume</code> finds
      the storage pool containing a given storage volume.</p></li>
D
Api documentation  
Daniel Veillard 已提交
67 
    </ul>
J
api: Reword and clean lists for object description  
John Ferlan 已提交
68 
    <p> Most objects manipulated by the library can also be represented using
D
Api documentation  
Daniel Veillard 已提交
69 70 
      XML descriptions. This is used primarily to create those object, but is
      also helpful to modify or save their description back.</p>
J
api: Reword and clean lists for object description  
John Ferlan 已提交
71 
    <p> Domains, networks, and storage pools can be either <code>active</code>
D
Api documentation  
Daniel Veillard 已提交
72 73 74 
      i.e. either running or available for immediate use, or
      <code>defined</code> in which case they are inactive but there is
      a permanent definition available in the system for them. Based on this
J
api: Reword and clean lists for object description  
John Ferlan 已提交
75 76 
      they can be activated dynamically in order to be used.</p>
    <p> Most objects can also be named in various ways:</p>
D
Api documentation  
Daniel Veillard 已提交
77 
    <ul>
J
api: Reword and clean lists for object description  
John Ferlan 已提交
78 79 80 81 82 83 84 85 86 
      <li><code>name</code>
      <p>A user friendly identifier but whose uniqueness
      cannot be guaranteed between two nodes.</p></li>
      <li><code>ID</code>
      <p>A runtime unique identifier
      provided by the hypervisor for one given activation of the object;
      however, it becomes invalid once the resource is deactivated.</p></li >
      <li><code>UUID</code>
      <p> A 16 byte unique identifier
D
Api documentation  
Daniel Veillard 已提交
87 
      as defined in <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
J
Various typos and misspellings  
Ján Tomko 已提交
88 
      which is guaranteed to be unique for long term usage and across a
J
api: Reword and clean lists for object description  
John Ferlan 已提交
89 
      set of nodes.</p></li>
D
Api documentation  
Daniel Veillard 已提交
90 
    </ul>
M
Cleanup whitespace in docs  
Matthew Booth 已提交
91
J
api: Complete list of function and naming conventions  
John Ferlan 已提交
92 
    <h2><a name="Functions">Functions and Naming Conventions</a></h2>
D
Api documentation  
Daniel Veillard 已提交
93 
    <p> The naming of the functions present in the library is usually
J
api: Complete list of function and naming conventions  
John Ferlan 已提交
94 
      composed by a prefix describing the object associated to the function
D
Api documentation  
Daniel Veillard 已提交
95 
      and a verb describing the action on that object.</p>
J
api: Complete list of function and naming conventions  
John Ferlan 已提交
96 
    <p> For each first class object you will find APIs
D
Api documentation  
Daniel Veillard 已提交
97 98 
      for the following actions:</p>
    <ul>
J
api: Complete list of function and naming conventions  
John Ferlan 已提交
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 
      <li><b>Lookup</b> [...LookupBy...]
      <p>Used to perform lookups on objects by some type of identifier,
      such as:</p>
          <ul>
            <li><code class='docref'>virDomainLookupByID</code></li>
            <li><code class='docref'>virDomainLookupByName</code></li>
            <li><code class='docref'>virDomainLookupByUUID</code></li>
            <li><code class='docref'>virDomainLookupByUUIDString</code></li>
          </ul>
      </li>
      <li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
      <p>Used to enumerate a set of object available to an given
      hypervisor connection such as:</p>
          <ul>
            <li><code class='docref'>virConnectListDomains</code></li>
            <li><code class='docref'>virConnectNumOfDomains</code></li>
            <li><code class='docref'>virConnectListNetworks</code></li>
            <li><code class='docref'>virConnectListStoragePools</code></li>
          </ul>
      </li>
      <li><b>Description</b> [...GetInfo]
      <p>Generic accessor providing a set of generic information about an
      object, such as: </p>
        <ul>
          <li><code class='docref'>virNodeGetInfo</code></li>
          <li><code class='docref'>virDomainGetInfo</code></li>
          <li><code class='docref'>virStoragePoolGetInfo</code></li>
          <li><code class='docref'>virStorageVolGetInfo</code></li>
        </ul>
      </li>
      <li><b>Accessors</b> [...Get..., ...Set...]
      <p>Specific accessors used to query or modify data for the given object,
      such as: </p>
        <ul>
          <li><code class='docref'>virConnectGetType</code></li>
          <li><code class='docref'>virDomainGetMaxMemory</code></li>
          <li><code class='docref'>virDomainSetMemory</code></li>
          <li><code class='docref'>virDomainGetVcpus</code></li>
          <li><code class='docref'>virStoragePoolSetAutostart</code></li>
          <li><code class='docref'>virNetworkGetBridgeName</code></li>
        </ul>
      </li>
      <li><b>Creation</b> [...Create, ...CreateXML]
      <p>Used to create and start objects.  The ...CreateXML APIs will create
      the object based on an XML description, while the ...Create APIs will
      create the object based on existing object pointer, such as: </p>
        <ul>
          <li><code class='docref'>virDomainCreate</code></li>
          <li><code class='docref'>virDomainCreateXML</code></li>
          <li><code class='docref'>virNetworkCreate</code></li>
          <li><code class='docref'>virNetworkCreateXML</code></li>
        </ul>
      </li>
      <li><b>Destruction</b> [...Destroy]
      <p>Used to shutdown or deactivate and destroy objects, such as: </p>
        <ul>
          <li><code class='docref'>virDomainDestroy</code></li>
          <li><code class='docref'>virNetworkDestroy</code></li>
          <li><code class='docref'>virStoragePoolDestroy</code></li>
        </ul>
      </li>
D
Api documentation  
Daniel Veillard 已提交
160 161 
    </ul>
    <p> For more in-depth details of the storage related APIs see
E
docs: correct invalid xml  
Eric Blake 已提交
162 163 
      <a href="storage.html">the storage management page</a>.
    </p>
J
api: Add text and references for drivers section  
John Ferlan 已提交
164 165 166 167 168 169 170 171 172 173 
    <h2><a name="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
    part of the <code class='docref'>virInitialize</code> API. Each driver
    has a registration API which loads up the driver specific function
    references for the libvirt APIs to call. The following is a simplistic
    view of the hypervisor driver mechanism. Consider the stacked list of
    drivers as a series of modules that can be plugged into the architecture
    depending on how libvirt is configured to be built.</p>
D
Api documentation  
Daniel Veillard 已提交
174 175 176 177 
    <p class="image">
      <img alt="The libvirt driver architecture"
           src="libvirt-driver-arch.png"/>
    </p>
J
api: Add text and references for drivers section  
John Ferlan 已提交
178 179 180 181 182 183 184 185 186 187 188 
    <p>The driver architecture is also used to support other virtualization
    components such as storage, storage pools, host device, networking,
    network interfaces, and network filters.</p>
    <p>See the <a href="drivers.html">libvirt drivers</a> page for more
    information on hypervisor and storage specific drivers.</p>
    <p>Not all drivers support every virtualization function possible.
    The <a href="hvsupport.html">libvirt API support matrix</a> lists
    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>
D
Api documentation  
Daniel Veillard 已提交
189 190 191 192 193 194 
    <p class="image">
      <img alt="The libvirt daemon and remote architecture"
           src="libvirt-daemon-arch.png"/>
    </p>
  </body>
</html>