This chapter describes the main principles and architecture choices behind the definition of the libvirt API and the Python libvirt module.
2.1. Object model 2.1. 对象模型
The scope of the libvirt API and the Python libvirt module is intended to extend to all functions necessary for deployment and management of virtual machines. This entails management of both the core hypervisor functions and host resources that are required by virtual machines, such as networking, storage and PCI/USB devices. Most of the classes and methods exposed by libvirt have a pluggable internal backend, allowing support for different underlying virtualization technologies and operating systems. Thus, the extent of the functionality available from a particular API or method is determined by the specific hypervisor driver in use and the capabilities of the underlying virtualization technology.
libvirt API 和 Python libvirt 模块的范围旨在扩展到部署和管理虚拟机所需的所有功能。这包括管理核心虚拟化程序功能和虚拟机所需的主机资源，如网络、存储和 PCI/USB 设备。libvirt 公开的大多数类和方法都具有可插拔的内部后端，允许支持不同的底层虚拟化技术和操作系统。因此，特定 API 或方法提供的功能范围取决于所使用的特定虚拟化程序驱动程序以及底层虚拟化技术的功能。
2.1.1. Hypervisor connections
2.1.1. 虚拟化程序连接
A connection is the primary or top level object in the libvirt API and Python libvirt module. An instance of this object is required before attempting to use almost any of the classes or methods. A connection is associated with a particular hypervisor, which may be running locally on the same machine as the libvirt client application, or on a remote machine over the network. In all cases, the connection is represented by an instance of the
virConnect class and identified by a URI. The URI scheme and path defines the hypervisor to connect to, while the host part of the URI determines where it is located. Refer to
Section 3.2, “URI formats” for a full description of valid URIs.
连接是 libvirt API 和 Python libvirt 模块中的主要或顶级对象。在尝试使用几乎所有类或方法之前，需要此对象的一个实例。连接与特定的 hypervisor 相关联，该 hypervisor 可能在与 libvirt 客户端应用程序相同的机器上本地运行，也可能在网络上的远程机器上运行。在所有情况下，连接由 virConnect 类的实例表示，并由 URI 标识。URI 方案和路径定义要连接的 hypervisor，而 URI 的主机部分确定其位置。有关有效 URI 的完整描述，请参阅第 3.2 节“URI 格式”。
An application is permitted to open multiple connections at the same time, even when using more than one type of hypervisor on a single machine. For example, a host may provide both KVM full machine virtualization and LXC container virtualization. A connection object may be used concurrently across multiple threads. Once a connection has been established, it is possible to obtain handles to other managed objects or create new managed objects, as discussed in
Section 2.1.2, “Guest domains”.
应用程序允许同时打开多个连接，即使在单台机器上使用多种类型的 hypervisor。例如，主机可以同时提供 KVM 完整机器虚拟化和 LXC 容器虚拟化。连接对象可以跨多个线程同时使用。建立连接后，可以获取其他受管理对象的句柄或创建新的受管理对象，如第 2.1.2 节“客户域”中所讨论的。
2.1.2. Guest domains 2.1.2. 客户域
A guest domain can refer to either a running virtual machine or a configuration that can be used to launch a virtual machine. The connection object provides methods to enumerate the guest domains, create new guest domains and manage existing domains. A guest domain is represented with an instance of the virDomain class and has a number of unique identifiers.
客户域可以指正在运行的虚拟机，也可以指可用于启动虚拟机的配置。连接对象提供了枚举客户域、创建新客户域和管理现有域的方法。客户域用 virDomain 类的实例表示，并具有许多唯一标识符。
Unique identifiers 唯一标识符
ID: positive integer, unique amongst running guest domains on a single host. An inactive domain does not have an ID.
ID: 正整数，在单个主机上运行的客户域中唯一。非活动域没有 ID。
name: short string, unique amongst all guest domains on a single host, both running and inactive. To ensure maximum portability between hypervisors, it is recommended that names only include alphanumeric (a - Z, 0 - 9), hyphen ( - ) and underscore ( _ ) characters.
名称: 短字符串，在单个主机上所有客户域中唯一，无论是运行还是非活动的。为了确保在不同虚拟化程序之间最大的可移植性，建议名称只包括字母数字（ a - Z ， 0 - 9 ），连字符（ - ）和下划线（ _ ）字符。
UUID: 16 unsigned bytes, guaranteed to be unique amongst all guest domains on any host. RFC 4122 defines the format for UUIDs and provides a recommended algorithm for generating UUIDs with guaranteed uniqueness.
UUID: 16 个无符号字节，保证在任何主机上所有客户域中唯一。RFC 4122 定义了 UUID 的格式，并提供了一个推荐的算法来生成具有保证唯一性的 UUID。
A guest domain may be transient or persistent. A transient guest domain can only be managed while it is running on the host. Once it is powered off, all trace of it will disappear. A persistent guest domain has its configuration maintained in a data store on the host by the hypervisor, in an implementation defined format. Thus when a persistent guest is powered off, it is still possible to manage its inactive configuration. A transient guest can be turned into a persistent guest while it is running by defining a configuration for it.
客体域可以是瞬态的或持久的。瞬态客体域只能在主机上运行时进行管理。一旦关闭电源，所有与其相关的痕迹都将消失。持久客体域的配置由虚拟机监视器在主机上的数据存储中维护，以一种实现定义的格式。因此，当持久客体域关闭电源时，仍然可以管理其非活动配置。可以通过为其定义配置将瞬态客体域转换为持久客体域，而其仍在运行。
A virtual network provides a method for connecting the network devices of one or more guest domains within a single host. The virtual network can either:
A virtual network is represented by an instance of the virNetwork class and has two unique identifiers:
Unique identifiers
name: short string, unique amongst all virtual network on a single host, both running and inactive. For maximum portability between hypervisors, applications should only use the characters a-Z,0-9,-,_ in names.
UUID: 16 unsigned bytes, guaranteed to be unique amongst all virtual networks on any host. RFC 4122 defines the format for UUIDs and provides a recommended algorithm for generating UUIDs with guaranteed uniqueness.
A virtual network may be transient or persistent. A transient virtual network can only be managed while it is running on the host. When taken offline, all traces of it will disappear. A persistent virtual network has its configuration maintained in a data store on the host, in an implementation defined format. Thus when a persistent network is brought offline, it is still possible to manage its inactive config. A transient network can be turned into a persistent network on the fly by defining a configuration for it.
After installation of libvirt, every host will get a single virtual network instance called 'default', which provides DHCP services to guests and allows NAT'd IP connectivity to the host's interfaces. This service is of most use to hosts with intermittent network connectivity. For example, laptops using wireless networking.
安装 libvirt 后，每个主机将获得一个名为“default”的单个虚拟网络实例，该实例为客户提供 DHCP 服务，并允许 NAT'd IP 连接到主机的接口。此服务对于具有间歇性网络连接的主机最有用。例如，使用无线网络的笔记本电脑。
2.1.4. Storage pools 2.1.4. 存储池
The storage pool object provides a mechanism for managing all types of storage on a host, such as local disk, logical volume group, iSCSI target, FibreChannel HBA and local/network file system. A pool refers to a quantity storage that is able to be allocated to form individual volumes. A storage pool is represented by an instance of the virStoragePool class and has a pair of unique identifiers.
存储池对象提供了一种管理主机上所有类型存储的机制，例如本地磁盘、逻辑卷组、iSCSI 目标、FibreChannel HBA 和本地/网络文件系统。存储池指的是可以分配给形成单独卷的存储量。存储池由 virStoragePool 类的一个实例表示，并具有一对唯一标识符。
Unique identifiers 唯一标识符
name: short string, unique amongst all storage pools on a single host, both running and inactive. For maximum portability between hypervisors applications should only rely on being able to use the characters a-Z,0-9,-,_ in names.
名称: 短字符串，在单个主机上的所有存储池中是唯一的，无论是运行还是非活动状态。为了在不同的虚拟化平台之间实现最大的可移植性，应用程序应该只依赖能够在名称中使用字符 a-Z,0-9,-,_ 。
UUID: 16 unsigned bytes, guaranteed to be unique amongst all storage pools on any host. RFC 4122 defines the format for UUIDs and provides a recommended algorithm for generating UUIDs with guaranteed uniqueness.
UUID: 16 个无符号字节，保证在任何主机上的所有存储池中是唯一的。RFC 4122 定义了 UUID 的格式，并提供了一个推荐的算法来生成具有保证唯一性的 UUID。
A storage pool may be transient, or persistent. A transient storage pool can only be managed while it is running on the host and, when powered off, all trace of it will disappear (the underlying physical storage still exists of course !). A persistent storage pool has its configuration maintained in a data store on the host by the hypervisor, in an implementation defined format. Thus when a persistent storage pool is deactivated, it is still possible to manage its inactive config. A transient pool can be turned into a persistent pool on the fly by defining a configuration for it.
存储池可以是瞬态的或持久的。瞬态存储池只能在主机上运行时进行管理，当其关闭电源时，所有与其相关的痕迹都将消失（当然底层物理存储仍然存在！）。持久存储池的配置由虚拟化平台在主机上的数据存储中维护，以一种实现定义的格式。因此，当持久存储池被停用时，仍然可以管理其非活动配置。可以通过为其定义配置将瞬态存储池即时转换为持久存储池。
Refer to
Chapter 5, Storage Pools for further information about using storage pool objects.
请参考第 5 章《存储池》以获取有关使用存储池对象的更多信息。
2.1.5. Storage volumes 2.1.5. 存储卷
The storage volume object provides management of an allocated block of storage within a pool, be it a disk partition, logical volume, SCSI/iSCSI LUN, or a file within a local/network file system. Once allocated, a volume can be used to provide disks to one (or more) virtual domains. A volume is represented by an instance of the virStorageVol class, and has three identifiers
存储卷对象提供对池内已分配存储块的管理，无论是磁盘分区、逻辑卷、SCSI/iSCSI LUN，还是本地/网络文件系统中的文件。一旦分配，卷可以用于为一个（或多个）虚拟域提供磁盘。卷由 virStorageVol 类的实例表示，并具有三个标识符。
Unique identifiers 唯一标识符
name: short string, unique amongst all storage volumes within a storage pool. For maximum portability between implementations applications should only rely on being able to use the characters a-Z,0-9,-,_ in names. The name is not guaranteed to be stable across reboots, or between hosts, even if the storage pool is shared between hosts.
名称: 短字符串，存储池中所有存储卷中唯一。为了在不同实现之间实现最大可移植性，应用程序应仅依赖能够在名称中使用字符 a-Z,0-9,-,_ 。名称不能保证在重新启动或主机之间稳定，即使存储池在主机之间共享。
Key: a opaque string, of arbitrary printable characters, intended to uniquely identify the volume within the pool. The key is intended to be stable across reboots, and between hosts.
键: 不透明字符串，由任意可打印字符组成，旨在唯一标识池中的卷。键旨在在重新启动和主机之间保持稳定。
Path: a file system path referring to the volume. The path is unique amongst all storage volumes on a single host. If the storage pool is configured with a suitable target path, the volume path may be stable across reboots, and between hosts.
路径: 指向卷的文件系统路径。该路径在单个主机上的所有存储卷中是唯一的。如果存储池配置了适当的目标路径，卷路径可能在重新启动和主机之间保持稳定。
2.1.6. Host devices 2.1.6. 主机设备
Host devices provide a view to the hardware devices available on the host machine. This covers both the physical USB or PCI devices and logical devices these provide, such as a NIC, disk, disk controller, sound card, etc. Devices can be arranged to form a tree structure allowing relationships to be identified. A host device is represented by an instance of the virNodeDev class, and has one general identifier, though specific device types may have their own unique identifiers.
主机设备提供了主机机器上可用的硬件设备的视图。这包括物理 USB 或 PCI 设备以及这些设备提供的逻辑设备，如 NIC、磁盘、磁盘控制器、声卡等。设备可以排列成树形结构，以便识别关系。主机设备由 virNodeDev 类的一个实例表示，并具有一个通用标识符，尽管特定设备类型可能有其自己的唯一标识符。
Physical devices can be detached from the host OS drivers, which implicitly removes all associated logical devices, and then assigned to a guest domain. Physical device information is also useful when working with the storage and networking APIs to determine what resources are available to configure.
物理设备可以从主机操作系统驱动程序中分离，这会隐式移除所有关联的逻辑设备，然后分配给一个客户域。物理设备信息在使用存储和网络 API 时也很有用，以确定可用于配置的资源。
