libvirt学习笔记（二）

http://blog.csdn.net/gaoxingnengjisuan?viewmode=contents

8.Libvirt API介绍

    高级libvirt API可划分为5个API部分：虚拟机监控程序连接API、域API、网络API、存储卷API、存储池API。

1）.连接API

    在libvirt中，连接是系统中的每一个动作和对象的基础。每一个实体，要与libvirt互相作用，应用virsh, virt-manager或者使用libvirt库，都需要首先获得一个到主机上libvirt守护进程的连接。

    链接是与特定的hypervisor相关联的，它可能与libvirt客户端程序同时运行在本地的一个节点上，也可能通过网络连接到远程的机器上。通常情况下，链接由virConnectPtr对象代表，并且由一个URI来定义。

一个libvirt代理程序要做的第一件事就是调用libvirt连接函数获得virConnectPtr句柄。在后续的操作中，该句柄作为所有其他管理功能的基础。

（1）.连接函数

    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, intflags)

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

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

（2）.关闭连接

   virConnectClose

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

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

    virConnectClose(conn);

（3）.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://root@node.example.com/

（4）.获取虚拟机功能信息的API

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

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

    具体例子不再描述。

（5）.获取主机信息的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的调用能够查询一个给定的连接是否安全。

（6）.错误处理API

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

 

2）.域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）.域表单的获取

    Libvirt API公开了两个域的列表，第一个包含运行域，第二个包含无效的持久的域。

    活跃的域列表的API--virConnectListDomains，返回域ID的列表。为了确定ID数组的大小，应用程序可以调用virConnectNumOfDomainsAPI来解决。把这两个API调用放在一起，打印运行域ID列表的代码将会是如下所示：

[cpp] view plaincopyprint?

1.  int i;  

2.  int numDomains;  

3.  int *activeDomains;  

4.  numDomains = virConnectNumOfDomains(conn);  

5.  activeDomains = malloc(sizeof(int) * numDomains);  

6.  numDomains = virConnectListDomains(conn, activeDomains, numDomains);  

7.  printf("Active domain IDs:\n");  

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

9.      printf(" %d\n", activeDomains[i]);  

10. }  

11. free(activeDomains);  

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

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

[cpp] view plaincopyprint?

1.  int i;  

2.  int numDomains;  

3.  char **inactiveDomains;  

4.  numDomains = virConnectNumOfDefinedDomains(conn);  

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

6.  numDomains = virConnectListDomains(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将会建立并立即引导启动一个新的临时性的域。当这个域系统关闭的时候，所有的运行痕迹将会消失。

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

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

    引导一个临时的域

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

[cpp] view plaincopyprint?

1.  virDomainPtr dom;  

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

3.  dom = virConnectCreateXML(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 = virConnectDefineXML(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);  

    至于网络 API（监控虚拟网络）、存储卷 API（管理存储设备）和存储池 API（管理存储文件系统）这里先不做介绍了，如果有需要的话，可以直接看官方文档，介绍的很详细，还有很多简单明了的示例。

 

8.Libvirt API介绍

    高级libvirt API可划分为5个API部分：虚拟机监控程序连接API、域API、网络API、存储卷API、存储池API。

1）.连接API

    在libvirt中，连接是系统中的每一个动作和对象的基础。每一个实体，要与libvirt互相作用，应用virsh, virt-manager或者使用libvirt库，都需要首先获得一个到主机上libvirt守护进程的连接。

    链接是与特定的hypervisor相关联的，它可能与libvirt客户端程序同时运行在本地的一个节点上，也可能通过网络连接到远程的机器上。通常情况下，链接由virConnectPtr对象代表，并且由一个URI来定义。

一个libvirt代理程序要做的第一件事就是调用libvirt连接函数获得virConnectPtr句柄。在后续的操作中，该句柄作为所有其他管理功能的基础。

（1）.连接函数

    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, intflags)

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

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

（2）.关闭连接

   virConnectClose

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

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

    virConnectClose(conn);

（3）.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://root@node.example.com/

（4）.获取虚拟机功能信息的API

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

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

    具体例子不再描述。

（5）.获取主机信息的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的调用能够查询一个给定的连接是否安全。

（6）.错误处理API

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

 

2）.域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）.域表单的获取

    Libvirt API公开了两个域的列表，第一个包含运行域，第二个包含无效的持久的域。

    活跃的域列表的API--virConnectListDomains，返回域ID的列表。为了确定ID数组的大小，应用程序可以调用virConnectNumOfDomainsAPI来解决。把这两个API调用放在一起，打印运行域ID列表的代码将会是如下所示：

[cpp] view plaincopyprint?

1.  int i;  

2.  int numDomains;  

3.  int *activeDomains;  

4.  numDomains = virConnectNumOfDomains(conn);  

5.  activeDomains = malloc(sizeof(int) * numDomains);  

6.  numDomains = virConnectListDomains(conn, activeDomains, numDomains);  

7.  printf("Active domain IDs:\n");  

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

9.      printf(" %d\n", activeDomains[i]);  

10. }  

11. free(activeDomains);  

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

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

[cpp] view plaincopyprint?

1.  int i;  

2.  int numDomains;  

3.  char **inactiveDomains;  

4.  numDomains = virConnectNumOfDefinedDomains(conn);  

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

6.  numDomains = virConnectListDomains(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将会建立并立即引导启动一个新的临时性的域。当这个域系统关闭的时候，所有的运行痕迹将会消失。

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

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

    引导一个临时的域

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

[cpp] view plaincopyprint?

1.  virDomainPtr dom;  

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

3.  dom = virConnectCreateXML(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 = virConnectDefineXML(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);  

    至于网络 API（监控虚拟网络）、存储卷 API（管理存储设备）和存储池 API（管理存储文件系统）这里先不做介绍了，如果有需要的话，可以直接看官方文档，介绍的很详细，还有很多简单明了的示例。