虚拟化最佳实践 #

虚拟化能为您的环境提供许多功能。该技术可以用于多种场景。如需更多相关细节，请参见虚拟化指南，尤其是以下章节：

本最佳实践指南提供有助于在您的环境中做出正确选择的建议。指南将根据您的工作负载建议或不建议使用某些选项。修复配置问题和执行微调任务会将 VM Guest 的性能提高到近乎裸机的水平。

为 VM Guest 分配资源是管理虚拟机时至关重要的一点。在向 VM Guest 分配资源时，需注意过量使用资源可能会影响 VM 主机服务器和 VM Guest 的性能。如果所有 VM Guest 同时请求它们的所有资源，主机需要提供所有这些资源。如果无法提供，主机的性能将受到负面影响，进而也会对 VM Guest 的性能产生负面影响。

4.1 内存 #

 

Linux 以称为页的单元来管理内存。在大多数系统上，默认页大小为 4 KB。Linux 和 CPU 需要知道哪些页属于哪些进程。该信息存储在页表中。如果有大量进程在运行，则需要花更多时间来查找内存映射的位置，因为搜索页表需要时间。为加快搜索速度，发明了 TLB（转换后援缓冲区）技术。但在具有大量内存的系统上，TLB 也无法完全满足需求。为避免回退到普通页表（会导致发生缓存不命中情况，这将耗费大量时间），可以使用大页。使用大页将减少 TLB 开销和找不到 TLB 的情况 (pagewalk)。对于内存为 32 GB (32*1014*1024 = 33,554,432 KB)、页大小为 4 KB 的主机，TLB 具有 33,554,432/4 = 8,388,608 个项。使用 2 MB (2048 KB) 的页大小时，TLB 只有 33554432/2048 = 16384 个项，可大大减少找不到 TLB 的情况。

4.1.1 将 VM 主机服务器和 VM Guest 配置为使用大页 #

 

AMD64/Intel 64 CPU 体系结构支持大于 4 KB 的页，即大页。要确定系统上可用大页的大小（可以是 2 MB 或 1 GB），请查看 /proc/cpuinfo 输出中的 flags 行中是否包含 pse 和/或 pdpe1gb。

表 1︰ 确定可用的大页大小 #

 

CPU 标志	可用的大页大小
空字符串	没有可用的大页
pse	2 MB
pdpe1gb	1 GB

使用大页可以提升 VM Guest 的性能并减少主机内存的消耗。

默认情况下，系统使用 THP。要使系统上可以使用大页，请在引导时使用 hugepages=1 来激活大页，您也可以选择使用诸如 hugepagesz=2MB 的设置来添加大页大小。

注意：1 GB 大页

1 GB 的页只能在引导时分配，之后将无法释放。

要分配和使用大页表 (HugeTlbPage)，您需要使用正确的权限挂载 hugetlbfs。

注意：大页的相关限制

大页虽然能够提供最佳性能，但也存在一些缺点。使用大页时，内存气球（请参见第 6.1.3 节 “virtio balloon”）、KSM（请参见第 4.1.4 节 “KSM 和页共享”）等功能将不可用，并且大页无法交换。

过程 2︰ 配置大页的使用 #

 

1. 将 hugetlbfs 挂载到 /dev/hugepages：

   > sudo  mount -t hugetlbfs hugetlbfs /dev/hugepages

2. 要为大页预留内存，请使用 sysctl 命令。如果系统的大页大小为 2 MB (2048 KB)，而您想要为 VM Guest 预留 1 GB (1,048,576 KB)，那么池中需要有 1,048,576/2048=512 个页：

   > sudo  sysctl vm.nr_hugepages=512

   该值将写入 /proc/sys/vm/nr_hugepages，表示内核的大页池中当前的持久性大页数量。被任务释放后，持久性大页会回到大页池。

3. 在 VM Guest 配置文件中添加 memoryBacking 元素（通过运行 virsh edit CONFIGURATION）。

   <memoryBacking>
     <hugepages/>
   </memoryBacking>

4. 启动 VM Guest，检查主机是否使用了大页：

   > cat /proc/meminfo | grep HugePages_
   HugePages_Total:1     512
   HugePages_Free:2       92
   HugePages_Rsvd:3        0
   HugePages_Surp:4        0

   1	大页池的大小
   2	池中尚未分配的大页数量
   3	已承诺从池中分配但尚未进行分配的大页数量
   4	池中大于 /proc/sys/vm/nr_hugepages 中的值的大页数量。最大超量大页数由 /proc/sys/vm/nr_overcommit_hugepages 控制

4.1.2 透明大页 #

 

利用透明大页 (THP)，您可以使用 khugepaged 内核线程动态分配大页，无需再手动管理大页的分配和使用。THP 对于采用连续内存访问模式的工作负载很有用。在运行采用连续内存访问模式的合成工作负载时，页错误可减少 1000 倍。反之，对于采用稀疏内存访问模式的工作负载（例如数据库），THP 可能表现较差。在这类情况下，比较好的做法可能是通过添加内核参数 transparent_hugepage=never 来禁用 THP，然后重构建 grub2 配置并重引导。使用以下命令校验是否已禁用 THP：

> cat /sys/kernel/mm/transparent_hugepage/enabled
always madvise [never]

如已禁用，方括号中会显示值 never，如以上示例中所示。

注意：Xen

THP 在 Xen 下不可用。

4.1.3 特定于 Xen 的内存说明 #

 

4.1.3.1 管理 Domain-0 内存 #

 

在以前的 SUSE Linux Enterprise Server 版本中，Xen 主机的默认内存分配模式是将所有主机物理内存都分配给 Dom0，并启用自动气球式调节功能。当有其他域启动后，内存会自动从 Dom0 进行气球式调节。此行为总是容易出错，因此强烈建议将其禁用。从 SUSE Linux Enterprise Server15 SP1 开始，默认已禁用自动气球式调节，并会为 Dom0 分配 10% 的主机物理内存外加 1 GB。例如，在物理内存大小为 32 GB 的主机上，将为 Dom0 分配 4.2 GB 内存。

我们仍支持并建议在 /etc/default/grub 中使用 dom0_mem 命令行选项（有关详细信息，请参见第 7.5 节 “在引导时更改内核参数”）。可以通过将 dom0_mem 设置为主机物理内存大小，并在 /etc/xen/xl.conf 中启用 autoballoon 设置，来恢复旧行为。

4.1.4 KSM 和页共享 #

 

内核同页合并 (Kernel Samepage Merging) 是一项内核功能，可以通过共享 VM Guest 共有的内存块来减少 VM 主机服务器上消耗的内存。KSM 守护程序 ksmd 会定期扫描用户内存，查找包含相同内容、可由单个写保护页替换的页。要启用 KSM 服务，首先需确保已安装 qemu-ksm 软件包，然后运行以下命令：

> sudo  systemctl enable --now ksm.service

或者，也可以运行以下命令来启动该服务：

#  echo 1 > /sys/kernel/mm/ksm/run

从 VM Guest 的角度而言，使用 KSM 的优点之一是所有 Guest 内存都受主机匿名内存支持。您可以共享 pagecache、tmpfs 或 Guest 中分配的任何类型的内存。

KSM 由 sysfs 控制。您可以在 /sys/kernel/mm/ksm/ 中检查 KSM 的值：

• pages_shared：正在使用的共享页数量（只读）。

• pages_sharing：正在共享页的站点数量（只读）。

• pages_unshared：为进行合并而反复检查的唯一页数量（只读）。

• pages_volatile：更改太快而认为无法合并的页数量（只读）。

• full_scans：已扫描所有可合并区域的次数（只读）。

• sleep_millisecs：ksmd 在下次扫描前应休眠的毫秒数。值过低会过度使用 CPU，导致消耗可以用于其他任务的 CPU 时间。我们建议将该值设为 1000 以上。

• pages_to_scan：在 ksmd 进入睡眠状态之前要扫描的当前页数。值过高会过度使用 CPU。我们建议先将该值设为 1000，然后根据在测试部署时观察到的 KSM 结果进行调整。

• merge_across_nodes：默认情况下，系统会跨 NUMA 节点合并页。将此选项设为 0 会禁用此行为。

注意：使用案例

KSM 技术非常适合在运行同一个应用程序或 VM Guest 的多个实例时过量使用主机内存。当应用程序和 VM Guest 类型不一并且不共享任何共用数据时，最好禁用 KSM。为此，请运行以下命令：

> sudo  systemctl disable --now ksm.service

或者，也可以运行以下命令来禁用该服务：

#  echo 0 > /sys/kernel/mm/ksm/run

在异类和同类混杂的环境中，可以在主机上启用 KSM，但要对每个 VM Guest 禁用 KSM。可以使用 virsh edit 在 VM Guest 的 XML 配置中添加以下内容来禁用 Guest 页共享：

<memoryBacking>
   <nosharepages/>
</memoryBacking>

警告：避免出现内存不足的情况

尽管 KSM 可以释放主机系统上的一些内存，但是管理员应当预留足够的交换来避免可共享内存减少时内存不足的情况。如果可共享内存的量减少，就会增加物理内存的使用量。

警告：内存访问延迟

默认情况下，KSM 会跨 NUMA 节点合并共用页。如果合并后的共用页现在位于较远的 NUMA 节点上（相对于运行 VM Guest vCPU 的节点），这样可能会降低 VM Guest 的性能。如果在 VM Guest 中发现内存访问延迟增加，请使用 merge_across_nodes sysfs 控制禁用跨节点合并：

#  echo 0 > /sys/kernel/mm/ksm/merge_across_nodes

4.1.5 VM Guest：内存热插拔 #

 

为了优化主机内存的使用，在需要时为运行中 VM Guest 热插入更多内存可能会很有用。要支持内存热插拔，必须先在 VM Guest 的配置文件中配置 <maxMemory> 标记：

<maxMemory1 slots='16'2 unit='KiB'>209715203</maxMemory>
  <memory4 unit='KiB'>1048576</memory>
<currentMemory5 unit='KiB'>1048576</currentMemory>

1	为 Guest 分配的运行时最大内存
2	可用于向 Guest 添加内存的槽数
3	有效单位包括： “KB”，表示千字节（1,000 个字节） “k”或“KiB”，表示千位二进制字节（1,024 个字节） “MB”，表示兆字节（1,000,000 个字节） “M”或“MiB”，表示兆位二进制字节（1,048,576 个字节） “GB”，表示千兆字节（1,000,000,000 个字节） “G”或“GiB”，表示千兆位二进制字节（1,073,741,824 个字节） “TB”，表示万亿字节（1,000,000,000,000 个字节） “T”或“TiB”，表示万亿位二进制字节（1,099,511,627,776 个字节）
4	在引导时为 Guest 分配的最大内存
5	实际为 Guest 分配的内存

要将内存设备热插入到槽中，请创建如下所示的 mem-dev.xml 文件：

<memory model='dimm'>
  <target>
  <size unit='KiB'>524287</size>
  <node>0</node>
  </target>
</memory>

然后使用以下命令附加该文件：

> virsh attach-device vm-name mem-dev.xml

要使用内存设备热插拔，必须至少为 Guest 定义 1 个 NUMA 单元（请参见第 4.6.3.1 节 “VM Guest 虚拟 NUMA 拓扑”）。

#  echo 35 > /proc/sys/vm/swappiness

> free -h
total       used       free     shared    buffers     cached
Mem:      24616680    4991492   19625188     167056     144340    2152408
-/+ buffers/cache:    2694744   21921936
Swap:      6171644          0    6171644

vm.swappiness = 35

<memtune>1
  <hard_limit unit='G'>1</hard_limit>2
  <soft_limit unit='M'>128</soft_limit>3
  <swap_hard_limit unit='G'>2</swap_hard_limit>4
</memtune>

w /sys/block/sda/queue/scheduler - - - - mq-deadline
w /sys/block/sdb/queue/scheduler - - - - none

fs.aio-max-nr = 1048576

nfs_server:/exported/vm_images1 /mnt/images2 nfs3 rw4,hard5,sync6, rsize=81927,wsize=81928 0 0

> sudo  nfsstat -rc
Client rpc stats:
calls      retrans    authrefrsh
6401066    198          0          0

4.5 CPU #

 

主机 CPU“组件”在分配时将被“转换”为 VM Guest 中的虚拟 CPU。这些组件可能是：

• CPU 处理器：它描述主 CPU 单元，通常有多个核心并且可能支持超线程。

• CPU 核心：一个主 CPU 单元可以提供多个核心，多个邻近的核心能够使计算过程加速并降低能源成本。

• CPU 超线程：此实现用于改进计算的并行化，但其效率不如专用核心。

4.5.1 分配 CPU #

 

所有 VM Guest 的虚拟 CPU 的累积数量超过主机 CPU 的数量时，会发生 CPU 过量使用。当没有过量使用并且每个虚拟 CPU 均匹配 VM 主机服务器上的一个硬件处理器或核心时，将会达到最佳性能。VM Guest 在一台过量使用的主机上运行会发生延迟时间增加，并且每个 VM Guest 的吞吐量往往会受到负面影响。因此，请尽量避免过量使用 CPU。

要决定是否允许过量使用 CPU，需要对整体工作负载有较好的先验了解。例如，如果您知道所有 VM Guest 虚拟 CPU 的负载都不会超过 50%，那么您就可以假设将主机过量使用 2 倍时（这意味着在一台具有 64 个 CPU 的主机上，总共有 128 个虚拟 CPU）可以正常工作。但是，如果您知道 VM Guest 的所有虚拟 CPU 在大多数情况下都会尝试以 100% 的负载运行，那么即使虚拟 CPU 比主机的 CPU 多一个也属于不适当的配置。

过量使用达到一定的程度时，即虚拟 CPU 的累积数量超过 VM 主机服务器物理核心数量的 8 倍时，可能会导致系统出现故障和不稳定，因此应当避免出现这一情况。

除非您确切知道一个 VM Guest 需要多少个虚拟 CPU，否则请从一个 CPU 开始。将 VM 中的 CPU 工作负载目标控制在大约 70%（有关监控工具的信息，请参见第 2.3 节 “流程”）。如果您在 VM Guest 中分配的处理器超过所需，这将会对主机和 Guest 的性能产生负面影响。循环效率将会降低，因为未使用的 vCPU 仍然会导致计时器中断。如果您主要在 VM Guest 上运行单线程应用程序，那么单个虚拟 CPU 是最好的选择。

要是一个 VM Guest 具有的虚拟 CPU 比 VM 主机服务器具有的 CPU 还多，则一律属于不适当的配置。

4.5.2 VM Guest CPU 配置 #

 

本节介绍如何为 VM Guest 选择和配置 CPU 类型。您还将了解如何将虚拟 CPU 固定到主机系统上的物理 CPU。有关虚拟 CPU 配置和微调参数的详细信息，请参见 https://libvirt.org/formatdomain.html#elementsCPU 上的 libvirt 文档。

4.5.2.1 虚拟 CPU 型号和功能 #

 

可以为每个 VM Guest 单独指定 CPU 型号和拓扑。配置选项包括选择特定的 CPU 模型和排除某些 CPU 功能等。/usr/share/libvirt/cpu_map/ 目录中的文件列出了预定义的 CPU 型号。采用与主机类似的 CPU 型号和拓扑通常能提供最佳性能。可以通过运行 virsh capabilities 来显示主机系统 CPU 型号和拓扑。

如果更改了默认虚拟 CPU 配置，在将 VM Guest 迁移到硬件不同的主机时，需要关闭 VM Guest。有关 VM Guest 迁移的详细信息，请参见第 11.7 节 “迁移 VM Guest”。

要为 VM Guest 指定某个特定的 CPU 型号，请向 VM Guest 配置文件添加相应的项。下面的示例配置了具有固定 TSC 功能的 Broadwell CPU：

<cpu mode='custom' match='exact'>
  <model>Broadwell</model>
  <feature name='invtsc'/>
  </cpu>

对于与主机物理 CPU 最类似的虚拟 CPU，可以使用 <cpu mode='host-passthrough'>。host-passthrough CPU 型号可能与主机物理 CPU 并不完全相似，因为 KVM 默认会屏蔽任何不可迁移的功能。例如，invtsc 就不包含在虚拟 CPU 功能集中。虽然 libvirt 允许任意直通 KVM 命令行参数，但它并不直接支持更改默认 KVM 行为。仍以 invtsc 为例，您可以在 VM Guest 配置文件中使用以下命令行直通来实现主机 CPU（包括 invtsc） 的直通：

<domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
     <qemu:commandline>
     <qemu:arg value='-cpu'/>
     <qemu:arg value='host,migratable=off,+invtsc'/>
     </qemu:commandline>
     ...
     </domain>

注意：host-passthrough 模式

由于 host-passthrough 会向虚拟 CPU 公开物理 CPU 细节，因此无法迁移到不同的硬件。有关更多信息，请参见第 4.5.2.3 节 “虚拟 CPU 迁移注意事项”。

4.5.2.2 虚拟 CPU 固定 #

 

虚拟 CPU 固定用于将虚拟 CPU 线程限制到一组物理 CPU 。vcpupin 元素指定虚拟 CPU 可以使用的物理主机 CPU。如果未设置此元素且未指定 vcpu 元素的 cpuset 属性，则虚拟 CPU 可以自由使用任何物理 CPU。

虚拟 CPU 固定可提高物理 CPU 缓存命中率，对 CPU 密集型工作负载用处很大。要将虚拟 CPU 固定到特定的物理 CPU，请运行以下命令：

> virsh vcpupin DOMAIN_ID --vcpu vCPU_NUMBER
VCPU: CPU Affinity
----------------------------------
0: 0-7
# virsh vcpupin SLE15 --vcpu 0 0 --config

最后一个命令会在 XML 配置中生成下面一项：

<cputune>
   <vcpupin vcpu='0' cpuset='0'/>
</cputune>

注意：NUMA 节点上的虚拟 CPU 固定

要将 VM Guest 的 CPU 和内存限制为一个 NUMA 节点，可以在 NUMA 系统上使用虚拟 CPU 固定和内存分配策略。有关 NUMA 微调的详细信息，请参见第 4.6 节 “NUMA 微调”。

警告：虚拟 CPU 固定和实时迁移

虽然 vcpupin 可以提高性能，但它可能会使实时迁移复杂化。有关虚拟 CPU 迁移注意事项的详细信息，请参见第 4.5.2.3 节 “虚拟 CPU 迁移注意事项”。

4.5.2.3 虚拟 CPU 迁移注意事项 #

 

选择包含所有最新功能的虚拟 CPU 型号可以提高 VM Guest 工作负载的性能，但通常会牺牲可迁移性。除非群集中的所有主机都包含最新的 CPU 功能，否则如果目标主机缺少新功能，迁移便可能会失败。如果比起最新的 CPU 功能，更为重要的是虚拟 CPU的可迁移性，那么应当使用标准化的 CPU 型号和功能集。virsh cpu-baseline 命令可帮助定义可以跨所有主机迁移的标准化虚拟 CPU。以下命令（在迁移群集中的每台主机上运行时）会在 all-hosts-caps.xml 中说明所有主机功能的集合。

> sudo  virsh capabilities >> all-hosts-cpu-caps.xml

您可以使用 virsh cpu-baseline 根据 all-hosts-caps.xml 中收集的每个主机的功能创建跨所有主机兼容的虚拟 CPU 定义。

> sudo  virsh cpu-baseline all-hosts-caps.xml

生成的 CPU 定义可用作 VM Guest 配置文件中的 cpu 元素。

在逻辑层面上而言，虚拟 CPU 固定是一种硬件直通形式。CPU 固定会将物理资源与虚拟资源进行配对，这也可能会给迁移带来问题。例如，如果请求的物理资源在目标主机上不可用，或者源主机与目标主机的 NUMA 拓扑不同，迁移将会失败。有关实时迁移的更多建议，请参见第 11.7.1 节 “迁移要求”。

4.6 NUMA 微调 #

 

NUMA 是 Non Uniform Memory Access（非一致性内存访问）的首字母缩写。NUMA 系统具有多个物理 CPU，每个 CPU 都附有本地内存。每个 CPU 还可以访问其他 CPU 的内存（称为“远程内存访问”），但速度比访问本地内存要慢得多。如果调节不当，NUMA 系统会对 VM Guest 性能造成负面影响。本节介绍了在 NUMA 主机上部署 VM Guest 时应当考虑的控制，不过最终微调取决于工作负载。在配置和部署 VM 时，始终要考虑主机拓扑。

SUSE Linux Enterprise Server 包含一个 NUMA 自动平衡器，该平衡器通过将内存放置在与处理它的 CPU 相同的 NUMA 节点上来尽力减少远程内存访问。标准工具（例如 cgset）和虚拟化工具（例如 libvirt）提供了将 VM Guest 资源限制为物理资源的机制。

numactl 用于检查主机 NUMA 功能：

> sudo  numactl --hardware
available: 4 nodes (0-3)
node 0 cpus: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 72 73 74 75 76 77 78
79 80 81 82 83 84 85 86 87 88 89
node 0 size: 31975 MB
node 0 free: 31120 MB
node 1 cpus: 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 90 91 92 93
94 95 96 97 98 99 100 101 102 103 104 105 106 107
node 1 size: 32316 MB
node 1 free: 31673 MB
node 2 cpus: 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 108 109 110
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
node 2 size: 32316 MB
node 2 free: 31726 MB
node 3 cpus: 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 126 127 128
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
node 3 size: 32314 MB
node 3 free: 31387 MB
node distances:
node   0   1   2   3
0:  10  21  21  21
1:  21  10  21  21
2:  21  21  10  21
3:  21  21  21  10

numactl 输出显示这是一个具有 4 个节点或单元的 NUMA 系统，每个节点或单元包含 36 个 CPU 和大约 32G 内存。virsh capabilities 还可用于检查系统 NUMA 功能和 CPU 拓扑。

4.6.1 NUMA 平衡 #

 

在 NUMA 计算机上，如果 CPU 访问远程内存，将会造成性能损失。NUMA 自动平衡功能会扫描任务的地址空间并取消页映射。这样做可以检测页是否正确放置，或者是否要将数据迁移到运行任务的本地内存节点。在定义的间隔（使用 numa_balancing_scan_delay_ms 配置）内，该任务会扫描其地址空间中的下次扫描大小，即页数（使用 numa_balancing_scan_size_mb 配置）。在到达地址空间的末尾时，扫描器会从头重新开始。

较高的扫描率会导致较高的系统开销，因为必须捕获页错误，并需要迁移数据。但扫描率越高，当工作负载模式更改时，任务的内存迁移到本地节点的速度就越快。这样可最大限度减少远程内存访问对性能造成的影响。以下 sysctl 指令用于控制扫描延迟的阈值和扫描的页数：

> sudo  sysctl -a | grep numa_balancing
kernel.numa_balancing = 11
kernel.numa_balancing_scan_delay_ms = 10002
kernel.numa_balancing_scan_period_max_ms = 600003
kernel.numa_balancing_scan_period_min_ms = 10004
kernel.numa_balancing_scan_size_mb = 2565

1	启用/禁用基于页错误的 NUMA 自动平衡
2	任务初始派生时用于任务的起始扫描延迟
3	扫描任务的虚拟内存的最大时间（以毫秒为单位）
4	扫描任务的虚拟内存的最小时间（以毫秒为单位）
5	某次给定的扫描需要扫描的页大小（以兆字节为单位）

有关详细信息，请参见第 11 章 “自动平衡非一致性内存访问 (NUMA)”。

NUMA 自动平衡的主要目标是在相同节点的内存上重新安排任务（以便 CPU 跟随内存），或者将内存的页复制到相同的节点上（以便内存跟随 CPU）。

警告：任务布局

由于不同的任务之间可能会共享内存，因此并没有可定义运行任务的最佳位置的通用规则。为了获得最佳性能，我们建议将共享同一节点上的内存的任务分成一组。使用 # cat /proc/vmstat | grep numa_ 检查 NUMA 统计。

4.6.2 使用 CPUset 控制器控制内存分配 #

 

cgroup cpuset 控制器可用于将进程使用的内存限制在一个 NUMA 节点。可用的 cpuset 内存策略模式有以下三种：

• interleave：内存放置策略，也称为轮替。对于需要将线程本地数据放到相应节点上的作业，此策略可提供显著的改进。当交错目标不可用时，它将被转移到另一个节点。

• bind：此策略仅将内存放到一个节点上，这意味着如果内存不足，分配将会失败。

• preferred：此策略应用首选项来向节点分配内存。如果此节点上没有足够的内存空间，则会回退到另一个节点。

您可以使用 libcgroup-tools 软件包中的 cgset 工具更改内存策略模式：

> sudo  cgset -r cpuset.mems=NODE sysdefault/libvirt/qemu/KVM_NAME/emulator

要将页迁移到某个节点，请使用 migratepages 工具：

> migratepages PID FROM-NODE TO-NODE

要检查是否一切正常，请使用：cat /proc/PID/status | grep Cpus。

注意：内核 NUMA/cpuset 内存策略

有关详细信息，请参见Kernel NUMA memory policy和cpusets memory policy。另请查看 Libvirt NUMA Tuning documentation。

4.6.3 VM Guest：NUMA 相关配置 #

 

libvirt 允许设置虚拟 NUMA 和内存访问策略。virt-install 或 virt-manager 不支持配置这些设置，需要使用 virsh edit 手动编辑 VM Guest 配置文件来完成该操作。

4.6.3.1 VM Guest 虚拟 NUMA 拓扑 #

 

创建类似于主机 NUMA 拓扑的 VM Guest 虚拟 NUMA (vNUMA) 通常可以提高传统的大型可扩展工作负载的性能。可以在 XML 配置中使用 numa 元素指定 VM Guest vNUMA 拓扑：

<cpu>
...
  <numa>
    <cell1 id="0"2 cpus='0-1'3 memory='512000' unit='KiB'/>
    <cell id="1" cpus='2-3' memory='256000'4
    unit='KiB'5 memAccess='shared'6/>
  </numa>
  ...
</cpu>

1	每个 cell 元素指定一个 vNUMA 单元或节点
2	所有单元都应具有 id 属性，用于在其他配置块中引用所需单元。如果没有，将按从 0 开始的升序为单元分配 ID。
3	属于节点一部分的 CPU 或 CPU 范围
4	节点内存
5	指定节点内存时所用的单位
6	可选属性，可控制将内存映射为 shared 还是 private。仅对支持大页的内存有效。

要查找 VM Guest 将其页分配到的位置，请使用：cat /proc/PID/numa_maps 和 cat /sys/fs/cgroup/memory/sysdefault/libvirt/qemu/KVM_NAME/memory.numa_stat。

警告：NUMA 规范

libvirt VM Guest NUMA 规范目前仅适用于 QEMU/KVM。

4.6.3.2 使用 libvirt 控制内存分配 #

 

如果 VM Guest 具有 vNUMA 拓扑（请参见第 4.6.3.1 节 “VM Guest 虚拟 NUMA 拓扑”），便可使用 numatune 元素将内存固定到主机 NUMA 节点。此方法目前仅适用于 QEMU/KVM Guest。请参见重要：非 vNUMA VM Guest了解如何配置非 vNUMA VM Guest。

<numatune>
    <memory mode="strict"1 nodeset="1-4,^3"2/>
    <memnode3 cellid="0"4 mode="strict" nodeset="1"/>
    <memnode cellid="2" placement="strict"5 mode="preferred" nodeset="2"/>
</numatune>

1	可用的策略包括：interleave（类似于轮替）、strict（默认）或 preferred。
2	指定 NUMA 节点。
3	指定每个 Guest NUMA 节点的内存分配策略（如果未定义此元素，则会回退并使用 memory 元素）。
4	对要应用设置的 Guest NUMA 节点寻址。
5	可以使用 placement 属性来指示域进程的内存放置模式，值可以是 auto 或 strict。

重要：非 vNUMA VM Guest

在非 vNUMA VM Guest 上，将内存固定到主机 NUMA 节点的命令如以下示例所示：

<numatune>
   <memory mode="strict" nodeset="0-1"/>
</numatune>

此示例从主机节点 0 和 1 分配内存。如果无法满足这些内存要求，启动 VM Guest 的操作将会失败。virt-install 还支持通过 --numatune 选项提供此配置。

警告：跨 NUMA 节点的内存和 CPU

您应当避免跨 NUMA 节点分配 VM Guest 内存，并防止虚拟 CPU 跨 NUMA 节点浮动。

映像是用于存储 VM Guest 的操作系统和数据的虚拟磁盘。可以使用 qemu-img 命令来创建、维护和查询映像。有关 qemu-img 工具和示例的详细信息，请参见第 34.2.2 节 “创建、转换和检查磁盘映像”。

5.1 VM Guest 映像格式 #

 

QEMU 可识别源自其他虚拟化技术的某些存储格式。通过识别这些格式，QEMU 可以利用最初用于在这些其他虚拟化技术下运行的数据存储或整个 Guest。有些格式只支持只读模式。要以读取/写入模式使用它们，请使用 qemu-img 将它们转换为完全受支持的 QEMU 存储格式。否则，它们在 QEMU Guest 中将只能用作只读数据存储区。

使用 qemu-img info VMGUEST.IMG 可获取有关现有映像的信息，例如格式、虚拟大小、物理大小和快照（如果有）。

注意：性能

建议将磁盘映像转换为 raw 或 qcow2 格式以获得较好的性能。

警告：无法压缩加密映像

创建映像时，无法在输出文件中使用压缩 (-c) 的同时指定加密选项 (-e)。

5.1.1 Raw 格式 #

 

• 此格式十分简单，并且容易导出到所有其他模拟器/超级管理程序。

• 它提供的性能最佳（I/O 开销最少）。

• 它会占用文件系统上的所有已分配空间。

• Raw 格式允许将 VM Guest 映像复制到物理设备 (dd if=VMGUEST.RAW of=/dev/sda)。

• 这与 VM Guest 看到的字节对字节相同，因此会浪费大量空间。

5.1.2 qcow2 格式 #

 

• 使用此格式可缩小映像大小（这在文件系统不支持空洞时很有用）。

• 它具有可选的 AES 加密（现已弃用）。

• 基于 Zlib 的压缩选项。

• 支持多个 VM 快照（内部、外部）。

• 可提升性能和稳定性。

• 支持更改后备文件。

• 支持一致性检查。

• 性能低于 raw 格式。

l2-cache-size

qcow2 可以为随机读取/写入访问提供与 raw 格式相同的性能，但需要合适的缓存大小。默认情况下，缓存大小设置为 1 MB。这将提供最大 8 GB 磁盘大小的良好性能。如果您需要更大的磁盘大小，则需要调整缓存大小。如果磁盘大小为 64 GB (64*1024 = 65536)，则需要 65536 / 8192B = 8 MB 缓存 (-drive format=qcow2,l2-cache-size=8M)。

群集大小

qcow2 格式提供更改群集大小的功能。值必须介于 512 KB 到 2 MB 之间。较小的群集大小可以改善映像文件的大小，而较大的群集大小可提供更好的性能。

预分配

具有预分配元数据的映像最初便比较大，但在其需要增长时可以提升性能。

迟缓的引用计数

为了避免元数据 I/O 并提高性能，系统会延迟更新引用计数。这对于 cache=writethrough 的设置尤为有用。此选项不会批量进行元数据更新，但如果由于主机崩溃而必须重构建引用计数表，则在下次使用 qemu-img check -r all 打开时会自动完成重构建，此过程需要花费一定的时间。

5.1.3 qed 格式 #

 

qed 是一种改进型 qcow（QEMU 写入时复制）格式。由于 qcow2 可提供 qed 的所有优点以及其他功能，因此 qed 现已弃用。

5.1.4 VMDK 格式 #

 

VMware 3、4 或 6 映像格式，用于与该产品交换映像。

5.2 覆盖磁盘映像 #

 

qcow2 和 qed 格式提供了一种创建基本映像（也称为后备文件）和在基本映像的基础上覆盖映像的方法。后备文件对于还原到已知状态并丢弃覆盖映像非常有用。如果向映像写入数据，后备映像将保持不变，所有更改都将记录在覆盖映像文件中。除非使用 commit 监控命令（或 qemu-img commit），否则后备文件永远都不会修改。

要创建覆盖映像，请运行以下命令：

# qemu-img create -o1backing_file=vmguest.raw2,backing_fmt=raw3\
     -f4 qcow2 vmguest.cow5

1	使用 -o ? 可获取可用选项的概览。
2	后备文件名。
3	指定后备文件的文件格式。
4	指定 VM Guest 的映像格式。
5	VM Guest 的映像名称，它只会记录与后备文件的差异。

警告：后备映像路径

您不应更改后备映像的路径，否则将需要对其进行调整。路径存储在覆盖映像文件中。要更新路径，请创建一个从原始路径指向新路径的符号链接，然后使用 qemu-img rebase 选项。

# ln -sf /var/lib/images/OLD_PATH/vmguest.raw  \
 /var/lib/images/NEW_PATH/vmguest.raw
# qemu-img rebase1 -u2 -b3 \
 /var/lib/images/OLD_PATH/vmguest.raw /var/lib/images/NEW_PATH/vmguest.cow

1	rebase 子命令告知 qemu-img 更改后备文件映像。
2	-u 选项会激活不安全模式（请参见下面的注释）。rebase 有两种不同的运行模式： 安全：这是默认模式，执行真正的变基操作。安全模式是一种较为耗时的操作。 不安全：不安全模式 (-u) 只更改后备文件名和文件名的格式，而不检查文件的内容。要重命名或移动后备文件，请使用此模式。
3	使用 -b 来指定要使用的后备映像，映像路径是命令的最后一个参数。

常见的用法是使用后备文件来启动新的 Guest。假设我们有一个可以使用的 sle15_base.img VM Guest（未经任何修改的新安装）。这将是我们的后备文件。现在需要在更新后的系统和具有不同内核的系统上测试一个新软件包。我们可以使用 sle15_base.img，通过创建指向此后备文件 (sle15_base.img) 的 qcow2 覆盖文件来实例化新的 SUSE Linux Enterprise VM Guest。

在本示例中，我们将为更新后的系统使用 sle15_updated.qcow2，为具有不同内核的系统使用 sle15_kernel.qcow2。

要创建这两个精简预配的系统，请使用带 -b 选项的 qemu-img 命令行：

# qemu-img create -b /var/lib/libvirt/sle15_base.img -f qcow2 \
/var/lib/libvirt/sle15_updated.qcow2
Formatting 'sle15_updated.qcow2', fmt=qcow2 size=17179869184
backing_file='sle15_base.img' encryption=off cluster_size=65536
lazy_refcounts=off nocow=off
# qemu-img create -b /var/lib/libvirt/sle15_base.img -f qcow2 \
/var/lib/libvirt/sle15_kernel.qcow2
Formatting 'sle15_kernel.qcow2', fmt=qcow2 size=17179869184
backing_file='vmguest-sle15_base.img' encryption=off cluster_size=65536
lazy_refcounts=off nocow=off

映像现在便可供使用，您可以在不改动初始 sle15_base.img 后备文件的情况下执行测试。所有更改都将存储在新的覆盖映像中。您还可以使用这些新映像作为后备文件来创建新的覆盖映像。

# qemu-img create -b sle15_kernel.qcow2 -f qcow2 sle15_kernel_TEST.qcow2

结合 --backing-chain 选项使用 qemu-img info 时，该命令将递归返回有关整个后备链的所有信息：

# qemu-img info --backing-chain
/var/lib/libvirt/images/sle15_kernel_TEST.qcow2
image: sle15_kernel_TEST.qcow2
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 196K
cluster_size: 65536
backing file: sle15_kernel.qcow2
Format specific information:
compat: 1.1
lazy refcounts: false

image: sle15_kernel.qcow2
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 196K
cluster_size: 65536
backing file: SLE15.qcow2
Format specific information:
compat: 1.1
lazy refcounts: false

image: sle15_base.img
file format: qcow2
virtual size: 16G (17179869184 bytes)
disk size: 16G
cluster_size: 65536
Format specific information:
compat: 1.1
lazy refcounts: true

图 1︰ 理解映像覆盖 #

 

5.3 打开 VM Guest 映像 #

 

要访问映像的文件系统，请使用 guestfs-tools。如果系统上没有安装此工具，您可以使用其他 Linux 工具挂载映像。应避免访问不可信或未知的 VM Guest 的映像系统，因为这可能会导致安全问题（有关详细信息，请阅读 D. Berrangé's post）。

5.3.1 打开 Raw 映像 #

 

过程 5︰ 挂载 Raw 映像 #

 

1. 要挂载映像，请找到一台空闲的循环设备。以下命令显示第一台未使用的循环设备（在本示例中为 /dev/loop1）。

   # losetup -f
   /dev/loop1

2. 将映像（在本示例中为 SLE15.raw）与循环设备相关联：

   # losetup /dev/loop1 SLE15.raw

3. 通过获取有关循环设备的详细信息来检查映像是否已成功与循环设备关联：

   # losetup -l
   NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
   /dev/loop1         0      0         0  0    /var/lib/libvirt/images/SLE15.raw

4. 使用 kpartx 查看映像的分区：

   # kpartx -a1 -v2 /dev/loop1
   add map loop1p1 (254:1): 0 29358080 linear /dev/loop1 2048

   1	添加分区设备映射。
   2	详细模式。

5. 现在挂载映像分区（以下示例将其挂载到 /mnt/sle15mount）：

   # mkdir /mnt/sle15mount
   # mount /dev/mapper/loop1p1 /mnt/sle15mount

注意：包含 LVM 的 Raw 映像

如果 raw 映像包含 LVM 卷组，您应当使用 LVM 工具挂载分区。有关详细信息，请参见 第 5.3.3 节 “打开包含 LVM 的映像”。

过程 6︰ 卸载 Raw 映像 #

 

1. 卸载映像的所有已挂载分区，例如：

   # umount /mnt/sle15mount

2. 使用 kpartx 删除分区设备映射：

   # kpartx -d /dev/loop1

3. 使用 losetup 解除设备关联：

   # losetup -d /dev/loop1

5.3.2 打开 qcow2 映像 #

 

过程 7︰ 挂载 qcow2 映像 #

 

1. 首先，您需要加载 nbd（网络块设备）模块。以下示例加载该模块并支持 16 个块设备 (max_part=16)。使用 dmesg 检查操作是否成功：

   # modprobe nbd max_part=16
   # dmesg | grep nbd
   [89155.142425] nbd: registered device at major 43

2. 使用 qemu-nbd 命令将 VM Guest 映像（例如 SLE15.qcow2）连接到 NBD 设备（在下例中为 /debv/nbd0）。使用空闲的 NBD 设备：

   # qemu-nbd -c1 /dev/nbd02 SLE15.qcow23

   1	将 SLE15.qcow2 连接到本地 NBD 设备 /dev/nbd0
   2	要使用的 NBD 设备
   3	要使用的 VM Guest 映像

   

   提示：检查是否有空闲的 NBD 设备

   要检查 NBD 设备是否空闲，请运行以下命令：

   # lsof /dev/nbd0
   COMMAND    PID USER   FD   TYPE DEVICE SIZE/OFF  NODE NAME
   qemu-nbd 15149 root   10u   BLK   43,0      0t0 47347 /dev/nbd0

   如果命令生成如上所示的输出，则表示设备处于忙碌状态（非空闲）。还可以通过查看是否存在 /sys/devices/virtual/block/nbd0/pid 文件来确认设备是否空闲。

3. 使用 partprobe 通知操作系统有关分区表的更改：

   # partprobe /dev/nbd0 -s
   /dev/nbd0: msdos partitions 1 2
   # dmesg | grep nbd0 | tail -1
   [89699.082206]  nbd0: p1 p2

4. 在上例中，SLE15.qcow2 包含两个分区：/dev/nbd0p1 和 /dev/nbd0p2。在挂载这些分区之前，使用 vgscan 检查它们是否属于 LVM 卷：

   # vgscan -v
       Wiping cache of LVM-capable devices
       Wiping internal VG cache
       Reading all physical volumes. This may take a while...
       Using volume group(s) on command line.
       No volume groups found.

5. 如果没有找到 LVM 卷，可以使用 mount 挂载分区：

   # mkdir /mnt/nbd0p2
   # mount /dev/nbd0p1 /mnt/nbd0p2

   有关如何处理 LVM 卷的信息，请参见第 5.3.3 节 “打开包含 LVM 的映像”。

过程 8︰ 卸载 qcow2 映像 #

 

1. 卸载映像的所有已挂载分区，例如：

   # umount /mnt/nbd0p2

2. 断开映像与 /dev/nbd0 设备的连接。

   # qemu-nbd -d /dev/nbd0

5.3.3 打开包含 LVM 的映像 #

 

警告

如果 VM 主机服务器使用的 VG 名为 system，而 Guest 映像使用的 VG 也名为 system，LVM 将在其激活过程中报错。一种变通方法是暂时重命名 Guest VG，而正确的做法是为 Guest 使用与 VM 主机服务器不同的 VG 名称。

过程 9︰ 挂载包含 LVM 的映像 #

 

1. 要检查映像是否包含 LVM 组，请使用 vgscan -v。如果映像包含 LVM 组，命令的输出将如下所示：

   # vgscan -v
   Wiping cache of LVM-capable devices
   Wiping internal VG cache
   Reading all physical volumes.  This may take a while...
   Finding all volume groups
   Finding volume group "system"
   Found volume group "system" using metadata type lvm2

2. 在系统上找到了 system LVM 卷组。可以使用 vgdisplay VOLUMEGROUPNAME（在本例中 VOLUMEGROUPNAME 为 system）获取有关此卷的详细信息。应当激活这个卷组以将 LVM 分区作为设备公开，这样系统便能挂载它们。使用 vgchange：

   # vgchange -ay -v
   Finding all volume groups
   Finding volume group "system"
   Found volume group "system"
   activation/volume_list configuration setting not defined: Checking only
   host tags for system/home
   Creating system-home
   Loading system-home table (254:0)
   Resuming system-home (254:0)
   Found volume group "system"
   activation/volume_list configuration setting not defined: Checking only
   host tags for system/root
   Creating system-root
   Loading system-root table (254:1)
   Resuming system-root (254:1)
   Found volume group "system"
   activation/volume_list configuration setting not defined: Checking only
   host tags for system/swap
   Creating system-swap
   Loading system-swap table (254:2)
   Resuming system-swap (254:2)
   Activated 3 logical volumes in volume group system
       3 logical volume(s) in volume group "system" now active

3. 卷组中的所有分区都列于 /dev/mapper 目录中。现在即可挂载它们。

   # ls /dev/mapper/system-*
   /dev/mapper/system-home  /dev/mapper/system-root /dev/mapper/system-swap
   
   # mkdir /mnt/system-root
   # mount  /dev/mapper/system-root /mnt/system-root
   
   # ls /mnt/system-root/
   bin   dev  home  lib64       mnt  proc        root  sbin     srv  tmp  var
   boot  etc  lib   lost+found  opt  read-write  run   selinux  sys  usr

过程 10︰ 卸载包含 LVM 的映像 #

 

1. 使用 umount 卸载所有分区

   # umount /mnt/system-root

2. 使用 vgchange -an VOLUMEGROUPNAME 停用 LVM 卷组

   # vgchange -an -v system
   Using volume group(s) on command line
   Finding volume group "system"
   Found volume group "system"
   Removing system-home (254:0)
   Found volume group "system"
   Removing system-root (254:1)
   Found volume group "system"
   Removing system-swap (254:2)
   Deactivated 3 logical volumes in volume group system
   0 logical volume(s) in volume group "system" now active

3. 现在有以下两种选择：

   • 对于 qcow2 映像，请按步骤 2 中所述继续 (qemu-nbd -d /dev/nbd0)。

   • 对于 raw 映像，请按步骤 2 中所述继续（kpartx -d /dev/loop1；losetup -d /dev/loop1）。

   

   重要：检查卸载是否成功

   应使用 losetup、qemu-nbd、mount 或 vgscan 等系统命令确认卸载是否成功。如果没有成功卸载，您在使用 VM Guest 时可能会遇到问题，因为它的系统映像会在不同的地方使用。

<filesystem type='mount'1 accessmode='mapped'2>
   <source dir='/data/shared'3>
   <target dir='shared'4/>
</filesystem>

# mkdir /opt/mnt_shared
# mount shared -t 9p /opt/mnt_shared -o trans=virtio

版权所有 © 2006– 2024 SUSE LLC 和贡献者。保留所有权利。

根据 GNU 自由文档许可证 (GNU Free Documentation License) 版本 1.2 或（根据您的选择）版本 1.3 中的条款，在此授予您复制、分发和/或修改本文档的权限；本版权声明和许可证附带不可变部分。许可版本 1.2 的副本包含在题为“GNU Free Documentation License”的部分。

有关 SUSE 商标，请参见 https://www.suse.com/company/legal/。所有其他第三方商标分别为相应所有者的财产。商标符号（®、™ 等）代表 SUSE 及其关联公司的商标。星号 (*) 代表第三方商标。

本指南力求涵盖所有细节，但这不能确保本指南准确无误。SUSE LLC 及其关联公司、作者和译者对于可能出现的错误或由此造成的后果皆不承担责任。

Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

You may copy and distribute the Document in any medium, either commercially or non-commercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled “GNU
Free Documentation License”.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:

with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.