libvirt库的API参考文档总结

Libvirt 主要API说明

 

说明：以下为libvirt库的重要API接口说明，重要接口附有demo示例，针对某一个功能的具体细化（如网络接口流量信息获取，主机内存资源状态获取等）详见附件。

 

一、连接函数

    libvirt库为连接到一个资源提供了三种不同的函数,三个函数之间的区别在于它们提供的验证方式以及由此产生的授权的方法。

    virConnectPtr virConnectOpen(const char *name)

    以实现完全的读写访问，不包含任何认证机制，仅仅提供一种连接。

示例：conn = virConnectOpen("qemu:///system");

 

    virConnectPtr virConnectOpenReadOnly(const char *name)

    virConnectOpenReadOnly API会打开一个只读访问的连接。

示例：conn = virConnectOpenReadOnly("qemu:///system");

 

    virConnectPtr virConnectOpenAuth(const char *name, virConnectAuthPtr auth, int flags)

    提供了一种基于认证机制的连接；

示例：conn = virConnectOpenAuth("qemu+tcp://localhost/system", virConnectAuthPtrDefault, 0);

 

二.关闭连接

    virConnectClose

    当不再需要连接的时候，必须调用virConnectClose来断开连接。
    示例：
    virConnectPtr conn;

    conn = virConnectOpen("qemu:///system");

virConnectClose(conn);

 

三、获取虚拟机功能信息的API

    virConnectGetCapabilities的调用能够用于获取虚拟主机的功能信息。返回虚拟机监控程序和驱动程序的功能描述。它包含一个指针，如果调用成功，将返回一个字符串，其中包括了描述功能信息的XML文件。

    capabilities XML格式提供了有关主机虚拟化技术的信息。特别的，他描述了虚拟主机的功能、虚拟化驱动程序以及所采用的虚拟技术所能够启动的客户端的类型等等。

    

四．获取主机信息的API（重点）

    各种不同的API可以用来获得虚拟主机的信息，包括主机名、最大支持的CPU个数等。

    virConnectGetHostname的调用可以获得虚拟主机的主机名。

    virConnectGetMaxVcpus的调用可以获得每个域的虚拟CPU最大个数。

    virNodeGetFreeMemory调用能够获得虚拟主机中空闲内存的总量。

    virNodeGetInfo的调用可以用来获得虚拟主机的各种信息。它采用了一个连接指针和一个virNodeInfo指针（由调用者分配）作为输入，如果成功，则会返回0，并且将获取信息填写在virNodeInfo结构体中。

    virNodeInfo结构体包括以下成员：

    char model[32]                表示CPU型号的字符串

    unsigned long memory          以kb为单位的内存大小

    unsigned int cpus              活跃的CPU数目

    unsigned int mhz               期望的CPU频率

    unsigned int nodes             NUMA节点数目，1表示一致性内存访问

    unsigned int sockets           每一个节点的CPU socket的数目

    unsigned int cores             每一个socket的核数

    unsigned int threads           每一个核的线程数

 

    virConnectGetType的调用能够获得处于连接使用中的虚拟机的类型。

    virConnectGetVersion可以获取使用中的主机上虚拟机软件的版本。

    virConnectGetLibVersion可以获得正在使用中的主机上的libvirt软件的版本。

    virConnectGetURI能够用来获取当前连接中的URI。

    virConnectIsEncrypted的调用能够查询一个给定的连接是否加密。

virConnectIsSecure的调用能够查询一个给定的连接是否安全。

 

五．域API（重点）

    域API用于虚拟机管理，包括创建，启动，停用，迁移，动态修改配置等。

    进入虚拟机监控程序后，便可以使用一组 API 调用函数重复使用该虚拟机监控程序上的各种资源。API实现大量针对域的函数。要探究或管理域，首先需要一个virDomainPtr对象。您可通过多种方式获得该句柄（使用ID、UUID或域名）。有了该域句柄，就可以执行很多操作，从探究域（virDomainGetUUID、virDomainGetInfo、virDomainGetXMLDesc）到控制域（virDomainCreate 、virDomainSuspend 、virDomainResume 、virDomainDestroy）。

    域可以指任何正在运行的虚拟机或者是可以用来启动虚拟机的配置。链接对象提供了API用来枚举域、创建新域和管理现有域。域用virDomainPtr对象来表示，并有自己唯一的标示符。

域可以是临时的也可以是持久的。一个临时的域只由当它在主机上运行的时候才能够被管理，一旦关闭，所有运行的迹象都会消失。当一个持续的域被关闭时，仍然可能会管理这个域的无效的配置。当运行定义好的配置文件时，一个临时的域可以转变成一个持续的域。

（1）.域的标识符

    唯一标识符：

    ID：正整数类型，一个单节点上的若干域中，每个域都有唯一的ID。无效的域没有ID号。

    name:字符串类型，在一个主机上的所有域中是唯一的，包括运行的域和无效的域。

    UUID:16比特无符号类型，保证在任何主机上的所有域之间是唯一的。

（2）.域的获取

    有三个获取现有的域的API，即virDomainLookupByID, virDomainLookupByName 和virDomainLookupByUUID.这些对象中都用一个连接对象作为第一个输入参数，以及域标示符作为其它的输入参数。
示例：

    从ID获取一个域对象

    int domainID = 6;

    virDomainPtr dom;

    dom = virDomainLookupByID(conn, domainID);

    从name获取一个域对象

    int domainName = "someguest";

    virDomainPtr dom;

    dom = virDomainLookupByName(conn, domainName);

    从UUID获取一个域对象

    char *domainUUID = "00311636-7767-71d2-e94a-26e7b8bad250";

    virDomainPtr dom;

    dom = virDomainLookupByUUIDString(conn, domainUUID);

（3）.域表单的获取---虚拟机数量 、活动/非活动状态

     在服务器内部，虚拟机分为正在运行的和没有运行的两类，分别叫ActiveDom和InactiveDom;一个虚拟机正常创建之后，就处在active状态，当对他执行shut down之后，虚拟机就处在Inactive状态；对处于Inactive状态的虚拟机执行Run之后，他就处于active状态了，需要注意的是：对activeDom执行pause之后，这个虚拟机仍然处于active状态。

       1.查看activeDom的数量使用如下方法：      

1. numOfActiveDom = virConnectNumOfDomains(conn);    //numOfActiveDom就是活动虚拟机的数量  

      2.获得active虚拟机的编号：

1. int activeDom[numOfActiveDom];  

2.          numOfActiveDom = virConnectListDomains(conn , activeDom , numOfActiveDom);  

3.                                                  //数组activeDom里存放的就是所有活动虚拟机的id。  

      3.通过这些id就可以拿到相关虚拟机的实体

1. virDomainPtr *allDomains;             //allDomain是用来装所有活动虚拟机实体的数组  

2.   

3.        allDomains = malloc(sizeof(virDomainPtr)* numOfactiveDom）;     

4.   

5.                                            //困惑1：由于virDomain是未公开的结构体，所以 sizeof(virDomain) 不 可使用，因此试了sizeof(virDomainPtr)，尽然也可以。  

6.        printf("活动的Dom：\n");   

7.        for(i=0 ; i<numOfActiveDom ; i++){  

8.            printf("id:%d\n",activeDom[i]);  

9.            allDomains[numOfDom] = virDomainLookupByID(conn ,activeDom[i]);  //通过id取Domain  

10.            ｝                                  //至此，所有的活动虚拟机实力已经得到。  

  

       4.获得inactiveDom实体的方法类似。只不过由于inactiveDom没有id，所以需要通过名字得到实体。

1. char **inactiveDom;  

2.   

3.         virDomainPtr *allDomains;  

4.   

5.         numOfInactiveDom = virConnectNumOfDefinedDomains(conn);  

6.   

7.         allDomains = malloc(sizeof(virDomainPtr)* numOfactiveDom）;     

8.         if (numOfInactiveDom != 0){  

9.             printf("Inactive的数量是:%d\n",numOfInactiveDom);  

10.             inactiveDom = malloc(sizeof(char*) * (numOfInactiveDom));  

11.             numOfInactiveDom = virConnectListDefinedDomains(conn , inactiveDom , numOfInactiveDom);  

12.             printf("vir之后的numOfInactiveDom*************:%d\n", numOfInactiveDom);  

13.             printf("\n不活动的Dom：\n");  

14.             for(i=0 ; i<numOfInactiveDom ; i++){  

15.                printf("name:%s\n",inactiveDom[i]);  

16.                allDomains[numOfDom] = virDomainLookupByName(conn , inactiveDom[i]);//通过name取domain  

17.                numOfDom++;  

18.            }  

 

    除了正在运行的域，可能还会有一些持久的无效域配置存储在主机上。如果一个无效的域不具备任何的ID标志，这个不活跃域的列表将会以name字符串列表的形式输出。

    virConnectListDefinedDomains将会返回所填充的name字符串到数组元素的总数量。也有一个virConnectNumOfDefinedDomains来确定name的数量。打印无效的持久域的name列表的代码将会是如下所示：

1. int i;  

2. int numDomains;  

3. char **inactiveDomains;  

4. numDomains = virConnectNumOfDefinedDomains(conn);  

5. inactiveDomains = malloc(sizeof(char *) * numDomains);  

6. numDomains = virConnectListDefinedDomains(conn, inactiveDomains, numDomains);  

7. printf("Inactive domain names:\n");  

8. for (i = 0 ; i < numDomains ; i++) {  

9.     printf(" %s\n", inactiveDomains[i]);  

10.     free(inactiveDomains[i]);  

11. }  

12. free(inactiveDomains);  

（4）.域生命周期的控制

    Libvirt能够控制域的整个生命周期。域可以在它的整个生命周期的几个状态之间进行转换：

    Undefined这是一个基本的状态。任何没有定义或者没有建立的域的状态。

    Defined这是一个域已定义但是没有运行的状态。这种状态也可以被描述为停止。

    Running这是一个已经定义并运行在一个hypervisor上面的域的状态。

    Paused这个状态是形容一个域系统从运行状态转换为暂停状态。它的内存镜像已经被暂时地存储，它可以恢复到运行状态。

三个重要的API：

第一种为临时性的立即启动方式：

virDomainCreateXML将会建立并立即引导启动一个新的临时性的域。当这个域系统关闭的时候，所有的运行痕迹将会消失。

第二种为持久性的创建，需要两个API才可以完成创建和启动：

    virDomainDefineXML将会为一个持久性的域建立并存储配置文件。

    virDomainCreate将会从持久性配置中引导启动一个预先定义的域。

    引导一个临时的域

    如果想引导一个临时的域，只需要建立一个对libvirt的连接以及一个包含了描述了所需求的域的配置的XML文档的字符串。

[cpp] view plaincopyprint?

1. virDomainPtr dom;  

2. const char *xmlconfig = "<domain>........</domain>";  

3. dom = virDomianCreateXML(conn, xmlconfig, 0);  

4. if (!dom)   

5. {      

6.     fprintf(stderr, "Domain creation failed");      

7.     return;  

8. }  

9. fprintf(stderr, "Guest %s has booted",virDomainName(dom));  

10. virDomainFree(dom);   

    如果创建域的尝试成功，那么将会返回virDomainPtr作为这个域的句柄。尽管域引导启动成功，但是这不能保证这个域的持续运行。

    定义并引导一个持久的域

    在一个持久域能够被引导之前，必须使它的配置文件已经定义完成。这也要求建立一个对libvirt的连接以及一个包含了描述了所需求的来宾域的配置文件的XML文档的字符串。下面的示例假定了conn是virConnectPtr对象的实例。

[cpp] view plaincopyprint?

1. virDomainPtr dom;  

2. const char *xmlconfig = "<domain>........</domain>";  

3. dom = virDomainDefineXML(conn, xmlconfig, 0);  

4. if(virDomainCreate(dom) < 0){      

5.     virDomainFree(dom);      

6.     fprintf(stderr, "Cannot boot guest");      

7.     return;  

8. }  

9. fprintf(stderr,"Guest %s has booted",virDomainName(dom));  

10. virDomainFree(dom);  

 

（5）主机内存资源状态探测

计算资源与内存资源的监控

libvirt中提供virDomainGetInfo方法可以将一个domain的计算资源和内存资源的使用情况封装在一个结构体中，如下：

1. struct virDomainInfo{  

2. unsigned char state : //the running state, one of virDomainState    

3. unsigned long maxMem :// the maximum memory in KBytes allowed   

4. unsigned long memory :// the memory in KBytes used by the domain   

5. unsigned short nrVirtCpu :// the number of virtual CPUs for the domain   

6. unsigned long long cpuTime : //the CPU time used in nanoseconds   

7. }  

  

获取内存资源和计算资源监控信息并打印的方法如下：

1. virDomainInfoPtr domaininfo;     

2. domaininfo = malloc(sizeof(virDomainInfo)* 1);  

3. m = virDomainGetInfo(allDomains[numOfDom] , domaininfo);  

4. printf("状态:%d    ",(*domaininfo).state);  

5. printf("最大内存:%ld    ",((*domaininfo).maxMem)/1024);  

6. printf("内存:%ld   ",((*domaininfo).memory)/1024);  

7. printf("虚拟cpu个数:%d   ",(*domaininfo).nrVirtCpu);  

8. printf("cpu时间:%lld   ",(*domaininfo).cpuTime);  

 

（六）、网络接口状态探测

获得网络流量信息

    可以使用 virDomainInterfaceStats方法，将一个domain的网络流量信息封装在一个virDomainInterfaceStatsStruct结构体中，该方法需要传递一个虚拟网卡接口的参数，这个参数可以通过XML文件取得：

<interface type='bridge'>
      <mac address='00:16:3e:74:03:53'/>
      <source bridge='xenbr0'/>
      <script path='vif-bridge'/>
      <target dev='vif1.0 '/>          /*这个就是需要的参数*/
    </interface>

 

具体代码如下：

 

1. virDomainInterfaceStatsPtr interfacestats;  

2.   

3. interfacestats = malloc(sizeof(virDomainInterfaceStatsStruct)* 10);  

4. m = virDomainInterfaceStats(allDomains[numOfDom], i_path, interfacestats, 10);  

5.  printf("rx字节数:%ld    ",(*interfacestats).rx_bytes);  

6.  printf("tx字节数:%ld    ",(*interfacestats).tx_bytes);  

7.  printf("rx丢包:%ld    ",(*interfacestats).rx_drop);  

8.  printf("tx丢包:%ld\n",(*interfacestats).tx_drop);  

 

 

 

六．错误处理API

    libvirt error API将会在一个正常的libvirt API调用返回错误标志的时候。提供关于引发错误的非常详细的信息。如果多个错误发生在没有错误监测机制的连接上的时候，错误信息有可能会丢失。因为这个原因，强烈建议经常对错误进行监测，并在libvirt API调用失败以后，立即进行错误收集。

 

 

七.URI格式

    Libvirt使用统一的资源标识符（URI）来识别管理连接。连接本地和远程的hypervisor都是libvirt使用URI来进行处理。

    本地URI：

    Libvirt的本地URI具备下述格式之一：

    driver:///system

    driver:///session

    driver+unix:///system

    driver+unix:///session

    远程URI：

    远程URI具有通用的格式（"[...]"表示可选部分）：

    driver[+transport]://[username@][hostname][:port]/[path][?extraparameters]

    参数解释：

    driver：libvirt 所连接的driver的名字。如xen, qemu，lxc, openvz和test。

    transport：数据传输方式，可用的方式包括tls, tcp, unix, ssh和ext。

    hostname：远程机器的主机名。

    port：很少使用。

    远程访问URI的例子：

    应用SSH数据传输通道连接一个主机名为node.example.com上的远程Xen hypervisor，SSH的用户名根目录为：xen+ssh://[email protected]/