Geo 群集指南
SUSE Linux Enterprise High Availability Extension 15 SP4

# Geo 群集指南 #

本文档介绍 Geo 群集及其组件的设置选项和参数，例如投票间票据管理器、特定 Csync2 设置和所需群集资源的配置（以及如何在发生更改时将其传输到其他站点）。了解如何从命令行或使用 Hawk2 Web 界面监视和管理 Geo 群集。

修订历史: Geo 群集指南
作者: Tanja Roth、Thomas Schraitle
出版日期：2025 年 12 月 11 日

- 2.1 双站点群集 - 2x2 个节点 + 仲裁方（可选）
- 4.1 示例票据依赖项
- 5.1 Geo 群集的示例 Csync2 设置
- 8.1 Hawk2 - 票据细节
- 8.2 Hawk2 模拟器 - 票据

- 4.1 投票间配置文件
- 4.2 `/etc/booth/apac.conf`
- 4.3 `/etc/booth/emea.conf`
- 7.1 动态 DNS 更新的资源配置

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

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

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

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

# 前言 #

## 1 可用文档 #

联机文档

  https://documentation.suse.com/#sle-ha 上提供了此产品的相关联机文档。您可浏览或下载各种格式的文档。

  https://documentation.suse.com/ 上提供了其他产品的相关联机文档。

  注意：最新更新

  最新的文档更新通常会在文档的英文版中提供。

发行说明

  有关发行说明，请参见 https://www.suse.com/releasenotes/。

在您的系统中

  要以脱机方式使用，请参见安装的系统中 `/usr/share/doc` 下的文档。许多命令的手册页中也对相应命令进行了详细说明。要查看手册页，请运行 `man` 后跟特定的命令名。如果系统上未安装 `man` 命令，请使用 `sudo zypper install man` 加以安装。

## 2 改进文档 #

欢迎您提供针对本文档的反馈及改进建议。您可以通过以下渠道提供反馈：

服务请求和支持

  有关产品可用的服务和支持选项，请参见 https://www.suse.com/support/。

  要创建服务请求，需在 SUSE Customer Center 中注册订阅的 SUSE 产品。请转到 https://scc.suse.com/support/requests 并登录，然后点击新建。

Bug 报告

  在 https://bugzilla.suse.com/ 中报告文档问题。要简化此过程，可以使用本文档 HTML 版本中的报告问题链接。将光标置于受影响的句子中，然后在右侧导航面板的提供反馈部分单击报告问题。这样会在 Bugzilla 中预先选择正确的产品和类别，并添加当前章节的链接。然后，您便可以立即开始键入 Bug 报告。需要一个 Bugzilla 帐户。

贡献

  要帮助改进本文档，请使用本文档 HTML 版本中的 Edit source document（编辑源文档）链接。将光标置于受影响的句子中，然后在右侧导航面板的提供反馈部分单击 Edit source document（编辑源文档）。这样您将会转到 GitHub 上的源代码，可以在其中提出拉取请求。需要一个 GitHub 帐户。

  注意：Edit source document（编辑源文档）仅适用于英语版本

  Edit source document（编辑源文档）链接仅适用于每个文档的英语版本。对于其他所有语言，请按上文所述使用报告问题链接。

  有关本文档使用的文档环境的详细信息，请参见软件源的自述文件 https://github.com/SUSE/doc-sleha/blob/main/README.adoc.

邮件

  您也可以将有关本文档中的错误以及相关反馈发送至：<doc-team@suse.com>。请在其中包含文档标题、产品版本和文档发布日期。此外，请包含相关的章节号和标题（或者提供 URL），并提供问题的简要说明。

## 3 文档约定 #

本文档中使用了以下通知和排版约定：

-     tux > command

  可由任何用户（包括 `root` 用户）运行的命令。

-     root # command

  必须使用 `root` 特权运行的命令。您往往还可以在这些命令前加上 `sudo` 命令来运行它们。

-     crm(live)#

  在交互式 crm 外壳中执行的命令。有关细节，请参见Book “管理指南”, Chapter 8 “配置和管理群集资源（命令行）”。

- `/etc/passwd`：目录名称和文件名

- PLACEHOLDER：PLACEHOLDER 将会替换为实际的值

- `PATH`：环境变量 PATH

- `ls`、`--help`：命令、选项和参数

- `user`：用户或组

- packagename：软件包的名称

- Alt、Alt–F1：按键或组合键；这些键以大写形式显示，如在键盘上一样

- 文件、文件 › 另存为：菜单项，按钮

- amd64, em64t, ipf 本段仅与体系结构 `amd64`、`em64t` 和 `ipf` 相关。箭头标记文本块的开始位置和结束位置。

- 跳舞的企鹅（企鹅一章，↑其他手册）：此内容参见自其他手册中的一章。

- 注意

  警告

  在继续操作之前，您必须了解的不可或缺的信息。向您指出有关安全问题、潜在数据丢失、硬件损害或物理危害的警告。

  重要

  在继续操作之前，您必须了解的重要信息。

  注意

  额外信息，例如有关软件版本差异的信息。

  提示

  有用信息，例如指导方针或实用性建议。

有关群集节点和名称、资源与约束的命名约定概述，请参见Book “管理指南”, Appendix “命名约定”。

## 4 支持 #

下面提供了 SUSE Linux Enterprise High Availability Extension 的支持声明和有关技术预览的一般信息。有关产品生命周期的细节，请参见 SUSE Linux Enterprise Server 15 SP4 的《升级指南》。

如果您有权获享支持，可在 SUSE Linux Enterprise Server 15 SP4 的《管理指南》中查找有关如何收集支持票据所需信息的细节。

### 4.1 SUSE Linux Enterprise High Availability Extension 的支持声明 #

要获得支持，您需要一个适当的 SUSE 订阅。要查看为您提供的具体支持服务，请转到 https://www.suse.com/support/ 并选择您的产品。

支持级别的定义如下：

L1

  问题判定，该技术支持级别旨在提供兼容性信息、使用支持、持续维护、信息收集，以及使用可用文档进行基本查错。

L2

  问题隔离，该技术支持级别旨在分析数据、重现客户问题、隔离问题领域，并针对级别 1 不能解决的问题提供解决方法，或作为级别 3 的准备级别。

L3

  问题解决，该技术支持级别旨在借助工程方法解决级别 2 支持所确定的产品缺陷。

对于签约的客户与合作伙伴，SUSE Linux Enterprise High Availability Extension 将为除以下软件包外的其他所有软件包提供 L3 支持：

- 技术预览。

- 声音、图形、字体和作品。

- 需要额外客户合同的软件包。

- 模块 Workstation Extension 随附的某些软件包仅享受 L2 支持。

- 名称以 -devel 结尾的软件包（包含头文件和类似的开发人员资源）只能与其主软件包一起获得支持。

SUSE 仅支持使用原始软件包，即，未发生更改且未重新编译的软件包。

### 4.2 技术预览 #

技术预览是 SUSE 提供的旨在让用户大致体验未来创新的各种软件包、堆栈或功能。随附这些预览只是为了提供方便，让您有机会在自己的环境中测试新的技术。非常希望您能提供反馈！如果您测试了技术预览，请联系 SUSE 代表，将您的体验和用例告知他们。您的反馈对于我们的未来开发非常有帮助。

但是，技术预览存在以下限制：

- 技术预览仍处于开发阶段。因此，它们的功能可能不完备、不稳定，或者在其他方面不适合用于生产。

- 技术预览不受支持。

- 技术预览可能仅适用于特定的硬件体系结构。

- 技术预览的细节和功能可能随时会发生变化。因此，可能无法升级到技术预览的后续版本，而只能进行全新安装。

- 我们随时可能会放弃技术预览。例如，如果 SUSE 发现某个预览不符合客户或市场的需求，或者不能证明它符合企业标准，则可能会放弃该预览。SUSE 不承诺未来将提供此类技术的受支持版本。

有关产品随附的技术预览的概述，请参见 https://www.suse.com/releasenotes/ 上的发行说明。

# 1 Geo 群集面临的挑战 #

通常，地域环境的距离太远，难以支持站点之间的同步通讯。这带来了以下挑战：

- 如何确保群集站点的正常启动和运行？

- 如何确保资源仅启动一次？

- 如何确保不同站点间可以达到仲裁人数、不会出现节点分裂情境？

- 如何在所有节点和站点上保持 CIB 的最新状态？

- 如何管理站点间的故障转移？

- 如何处理需要停止资源时的长时间等待？

以下部分介绍了如何采用 SUSE Linux Enterprise 应对这些挑战。

# 2 概念概述 #

基于 SUSE® Linux Enterprise High Availability Extension 的 Geo 群集可视为“覆盖”群集，其中每个群集站点对应传统群集中的一个群集节点。覆盖群集由投票间群集票据管理器（以下简称“投票间”）管理。

Geo 群集中的各方都会运行一个服务，即 `boothd`。它连接到其他站点上运行的投票间守护程序，并交换连接性细节。投票间依靠称为“票据”的群集对象来确保群集资源在各站点之间的高度可用性。票据授予在特定群集站点上运行某些资源的权限。投票间可保证每个票据一次只会授予给一个站点。

如果两个投票间实例之间的通讯断开，则可能是因为群集站点之间的网络发生故障或其中一个群集站点中断。在此情况下，您需要使用一个额外的实例（第三个群集站点或`仲裁方`）来就各决策（例如在站点间进行资源的故障转移）达成一致意见。仲裁方是一台以特殊模式运行投票间实例的计算机（不属于群集）。每个 Geo 群集都可以有一个或多个仲裁方。

最常见的场景可能是，一个 Geo 群集包含两个站点和一个在第三个站点上运行的仲裁方。这就需要三个投票间实例。

也可以运行无仲裁方的双站点 Geo 群集。在此情况下，Geo 群集管理员需要手动管理票据。如果同时将一个票据授予多个站点，投票间会显示一条警告。

图 2.1︰ 双站点群集 - 2x2 个节点 + 仲裁方（可选） #

下面的列表更详细地介绍了 Geo 群集的组件和机制。

仲裁方

  每个站点运行一个投票间实例，负责与其他站点通讯。如果您的设置包含偶数个站点，拥有一个额外的实例会有助于就各项决策（例如在站点间进行资源的故障转移）达成一致意见。在这种情况下，请添加一台或多台在其他站点运行的仲裁方。仲裁方是一台以特殊模式运行投票间实例的计算机。因为所有投票间实例都相互通讯，仲裁方有助于提高票据授予或撤消决定的可靠性。仲裁方无法保留任何票据。

  仲裁方对双站点情境尤其重要：如果站点 `A` 无法再与站点 `B` 通讯，则可能有两种原因：

  - 站点 `A` 和 `B` 之间发生网络故障。

  - 站点 `B` 发生故障。

  但是，如果站点 `C`（仲裁方）仍然能与站点 `B` 通讯，则站点 `B` 一定还在正常运行。

投票间群集票据管理器

  投票间是管理票据分发以及 Geo 群集的站点间故障转移进程的实例。每个参与群集和仲裁方都会运行一个服务，即 `boothd`。它连接到其他站点上运行的投票间守护程序，并交换连接性细节。将票据授予站点后，投票间机制可以自动管理票据：如果持有票据的站点暂停服务，则投票间守护程序会选举下一个将获得该票据的站点。为了防止短暂连接故障，失去选票（因与选举主体断开连接而显式或隐式失去选票）的站点需要在超时时间后放弃票据。因此，可以确保在前一个站点放弃票据后才重新分发票据。另请参见 Dead man 依赖性 (`loss-policy="fence"`).

  对于包含两个站点和仲裁方的 Geo 群集，您需要 3 个投票间实例：每个站点一个实例，再加上在仲裁方上运行的实例。

  注意：投票间实例的数量有限

  目前的上限为 16 个投票间实例。

Dead man 依赖性 (`loss-policy="fence"`)

  撤消票据后，在停止依赖于该票据的所有资源之前可能需要很长时间，尤其是级联资源。要缩短该过程，群集管理员可以针对票据从站点撤消的情况配置一个 `loss-policy`（以及票据依赖项）。如果将 loss-policy 设置为 `fence`，托管依赖资源的节点将会被屏蔽。

  警告：潜在的数据丢失

  一方面，`loss-policy="fence"` 可以大大加快群集恢复过程，并确保更迅速地迁移资源。

  但另一方面，它可能会导致丢失所有未写入的数据，例如：

  - 共享储存中保存的数据。

  - 复制数据库（例如 MariaDB 或 PostgreSQL）或复制设备 (DRBD) 中的数据，由于网络链接缓慢，这些数据尚未到达其他站点。

票据

  票据授予在特定群集站点上运行某些资源的权限。一张票据某个时间内只能由一个站点所拥有。最初，每个站点都没有票据 - 每张票据都必须由群集管理员授予一次。之后，票据通过投票间来管理，用于资源的自动故障转移。但是，管理员还可以进行干预以及手动授予或撤消票据。

  出于管理目的撤消某个票据后，该票据不再由投票间管理。要使投票间再次开始管理该票据，必须再次将该票据授予站点。

  资源可按依赖性绑定到特定票据。仅当站点有定义好的票据时，才会启动相应资源。反之亦然，如果删除了票据，将会自动停止依赖于该票据的资源。

  站点有无票据的状态作为一种群集状态储存在 CIB 中。一个站点对于特定票据只有两种状态：`true`（站点拥有该票据）或 `false`（站点没有该票据）。将无特定票据状态（在 Geo 群集的初始状态期间）与票据被撤消后的状态视为相同的。它们都是用值 `false` 来表示。

  覆盖群集中的票据类似于传统群集中的资源。但和传统群集不同的是，在覆盖群集中票据是唯一一种资源类型。票据这种原始资源既不需要配置也不需要克隆。

票据故障转移

  您最初向某个站点授予自动票据之后，投票间将会自动管理此票据。如果持有票据的站点需要暂停服务，票据将在到达失效时间后自动撤消。如果其余站点具有仲裁，票据将会授予给另一个站点（故障转移）。依赖于该票据的资源将故障转移到持有该票据的新站点。`loss-policy`（在约束中定义）用于指定之前运行过资源的节点会发生什么情况。

  如果发生节点分裂情况时不需要自动故障转移，管理员也可以向运行良好的站点授予手动票据。第 8.1 节中介绍了如何通过命令行管理票据。

# 3 要求 #

软件要求 #

- 将加入群集的所有计算机（群集节点和仲裁方）上都至少需安装以下模块和扩展：

  - Basesystem Module 15 SP4

  - Server Applications Module 15 SP4

  - SUSE Linux Enterprise High Availability Extension 15 SP4

- 安装计算机时，请选择 `HA GEO 节点`作为`system role`。如此将安装最小系统，这种情况下，默认会安装 `GEO Clustering for High Availability (ha_geo)` 软件集中的软件包。

网络需求 #

- 要用于每个群集站点的虚拟 IP 在 Geo 群集中必须可访问。

- 必须可以通过每个投票间实例上的一个 UDP 和 TCP 端口访问站点。这意味着，必须相应地配置通讯双方之间的所有防火墙和 IPsec 隧道。

- 可能需要做出其他有关打开更多端口的设置决策（例如，为 DRBD 或数据库复制打开端口）。

其他要求和建议 #

- 所有站点上的所有群集节点应同步到群集外部的 NTP 服务器。有关详细信息，请参见 《SUSE Linux Enterprise Server 15 SP4 管理指南》。

  如果节点未同步，将难以分析日志文件和群集报告。

- 在 Geo 群集中使用奇数数量的站点。这样可确保在网络连接断开时仍存有大部分站点（从而避免出现节点分裂情形）。如果群集站点的数量为偶数，请使用一个仲裁方来处理票据的自动故障转移。如果您不使用仲裁方，则需要手动处理票据故障转移。

- 每个站点上的群集都有一个有意义的名称，例如 `amsterdam` 和 `berlin`。

  已在相应的 `/etc/corosync/corosync.conf` 文件中定义每个站点的群集名称。

      totem {
          [...]
          cluster_name: amsterdam
          }

  使用下面的 crmsh 命令来更改名称：

      root # crm cluster rename NEW_NAME

  停止群集服务然后再将其启动，以使更改生效：

      root # crm cluster restart

- 不支持在一个群集中采用混合体系结构。但是，对于 Geo 群集而言，Geo 群集的每个成员（群集站点或仲裁方）可以采用不同的体系结构。例如，您可以运行一个包含三个成员（两个群集站点和一个仲裁方）的 Geo 群集，其中的一个群集站点在 IBM Z 上运行，另一个群集站点在 x86 上运行，仲裁方在 POWER 上运行。

# 4 设置投票间服务 #

本章介绍投票间的设置和配置选项、如何将投票间配置同步到所有站点和仲裁方、如何启用和启动投票间服务，以及如何在投票间的服务运行时重新配置投票间。

## 4.1 投票间配置和设置选项 #

默认的投票间配置为 `/etc/booth/booth.conf`。此文件必须在 Geo 群集的所有站点（包括仲裁方）上相同。要使投票间配置在所有站点和仲裁方上同步，请根据第 4.5 节 “将投票间配置同步到所有站点和仲裁方”中所述使用 Csync2。

注意：`/etc/booth` 和文件的所有权

目录 `/etc/booth` 及其包含的所有文件需属于用户 `hacluster` 和组 `haclient`。每当从此目录复制新文件时，请使用 `cp` 命令的 `-p` 选项来保留所有权。或者，在创建新文件时，请随后使用 `chown` `hacluster:haclient 文件` 设置用户和组。

对于包含多个 Geo 群集的设置，可以“共享”同一个仲裁方（从 SUSE Linux Enterprise High Availability Extension 12 开始）。通过提供多个投票间配置文件，可以在同一个仲裁方上启动多个投票间实例，其中每个投票间实例在不同的端口上运行。这样，便可以使用一台计算机充当不同 Geo 群集的仲裁方。有关如何为多个 Geo 群集配置投票间的细节，请参见第 4.4 节 “使用多租户投票间设置”。

为了防止恶意方中断投票间服务，可以基于共享密钥配置身份验证来与投票间通讯。有关细节，请参见例 4.1 “投票间配置文件”中的5。与不同投票间服务器通讯的所有主机都需要此密钥。因此，请确保在 Csync2 配置中包含密钥文件，或者在所有参与方中手动同步此文件。

## 4.2 自动票据与手动票据 #

票据授予在特定群集站点上运行某些资源的权限。系统支持以下两种类型的票据：

- 自动票据由 `boothd` 守护程序控制。

- 手动票据仅可由群集管理员管理。

自动票据和手动票据具有以下属性：

- 自动票据和手动票据可以定义在一起：您可以在同一个 Geo 群集中定义并使用自动票据和手动票据。

- 手动票据管理仍然是手动进行的：对于手动控制的票据，无法进行自动票据管理。手动票据不需要进行仲裁选择，无法自动故障转移，也没有失效时间。

- 手动票据不会自动转移：手动授予给某个站点的票据会一直保留在该站点上，直到它们被手动撤消。即使该站点变为脱机状态，该票据也不会转移到其他站点。此行为可确保依赖于某个票据的服务始终保留在特定的站点上，不会转移到其他站点。

- 用于管理这两种类型的票据的命令是相同的：手动票据与自动票据使用相同的命令来管理（例如 `grant` 或 `revoke`）。

- 如果只使用手动票据，则不需要仲裁方： 如果在 Geo 群集中只配置手动票据，则不需要仲裁方，因为手动票据管理不需要仲裁决策。

要配置票据，请使用 `/etc/booth/booth.conf` 配置文件（更多信息请参见第 4.3 节 “使用默认投票间设置”）。

## 4.3 使用默认投票间设置 #

如果您已按《Geo Clustering Quick Start》（Geo 群集快速入门）中所述使用引导脚本设置基本 Geo 群集，那么这些脚本已使用最小参数集在所有站点上创建默认的投票间配置。要扩展或微调最小投票间配置，请参考例 4.1或第 4.4 节 “使用多租户投票间设置”中的示例。

要添加或更改投票间所需的参数，请手动编辑投票间配置文件，或使用 YaST 的 Geo 群集模块。要访问 YaST 模块，请从命令行使用 `yast2 geo-cluster` 将它启动（或者启动 YaST，然后选择高可用性 › Geo 群集）。

例 4.1︰ 投票间配置文件 #

    transport = UDP 1
    port = 9929 2
    arbitrator = 192.168.203.100 3
    site =  192.168.201.100 4
    site =  192.168.202.100 4
    authfile = /etc/booth/authkey 5
    ticket = "ticket-nfs" 6
         mode = MANUAL 7
    ticket = "ticketA" 6
         expire = 600 8
         timeout = 10 9
         retries = 5 10
         renewal-freq = 30 11
         before-acquire-handler12 = /etc/booth/ticket-A13 db-1 14
         acquire-after = 60 15
    ticket = "ticketB" 6
         expire = 600 8
         timeout = 10 9
         retries = 5 10
         renewal-freq = 30 11
         before-acquire-handler12 = /etc/booth/ticket-B13 db-8 14
         acquire-after = 60 15

1 | 用于站点间通讯的传输协议。仅支持 UDP，但将来可支持其他传输层。因此，目前可以省略此参数。
2 | 用于在每个站点上投票间实例之间通讯的端口。如果不使用默认端口 (`9929`)，请选择尚未用于其他服务的端口。确保在节点和仲裁方的防火墙上都打开该端口。投票间客户端使用 TCP 来与 `boothd` 通讯。投票间始终会同时绑定到 UDP 和 TCP 端口并予以侦听。
3 | 用作仲裁方的计算机的 IP 地址。请为 Geo 群集设置中要使用的每个仲裁方添加一个项。
4 | 用于站点上 `boothd` 的 IP 地址。请为 Geo 群集设置中要使用的每个站点添加一个项。确保为每个站点插入正确的虚拟 IP 地址 (`IPaddr2`)，否则投票间机制将不能正确运行。投票间可以使用 IPv4 和 IPv6 地址。 如果您已使用引导脚本设置投票间，那么您在设置期间指定的虚拟 IP 已写入到投票间配置中（并且也已添加到群集配置中）。要手动设置群集资源，请参见第 6.2 节 “配置 `boothd` 的资源组”。
5 | 可选的参数。基于共享密钥为客户端和服务器启用投票间身份验证。此参数指定密钥文件的路径。 密钥要求 # 密钥可以是二进制数或文本。 如果是文本，将忽略以下字符：前置和尾随空格、换行符。 密钥长度必须为 8 到 64 个字符。 密钥必须属于用户 `hacluster` 和组 `haclient`。 密钥必须只能由文件所有者读取。
6 | 将由投票间或群集管理员管理的票据。请为每个票据添加一个 `ticket` 条目。例如，此处指定的票据 `ticket-nfs` 可用于 NFS 和 DRBD 的故障转移，如 https://documentation.suse.com/sbp/all/html/SBP-DRBD/index.html 中所述。
7 | 可选的参数。定义票据模式。默认情况下，所有票据均由投票间管理。要定义由管理员管理的票据（手动票据），请将 mode 参数设为 `MANUAL` 或 `manual`。 手动票据没有 expire、renewal-freq 和 retries 参数。
8 | 可选的参数。定义票据的失效时间，以秒为单位。已获得票据的站点将会定期续订票据。如果投票间在截至所定义的失效时间内没有收到票据续订信息，票据将被撤消并授予其他站点。如果没有指定到期时间，默认情况下，票据将于 `600` 秒后过期。不应将该参数设置为小于 120 秒的值。引导脚本设置的默认值为 `600`。
9 | 可选的参数。定义超时期限，以秒为单位。如果投票间未在此期限内收到回复，则在该段时间过后，投票间将重发送包。定义的超时应足够长，以便包能够进入其他投票间成员（所有仲裁方和站点）。
10 | 可选的参数。定义投票间在放弃等待其他站点的确认之前需要重试发送包多少次。小于 `3` 的值无效，会阻止投票间启动。
11 | 可选的参数。设置票据续订频率周期。默认情况下，票据续订每隔失效时间的一半发生一次。如果在持续较长的一段时间内网络可靠性往往降低，则建议以更高的频率续订票据。在每次续订之前，应运行 `before-acquire-handler`。
12 | 可选的参数。支持一个或多个脚本。如果使用多个脚本，则每个脚本可以负责不同的检查，例如群集状态、数据中心连接、环境运行状况传感器和其他检查。将所有脚本储存在目录 `/etc/booth.d/票据名称`中，并确保它们具有正确的所有权（用户 `hacluster` 和组 `haclient`）。将目录名称指派为参数 before-acquire-handler 的值。 此目录中的脚本按字母顺序执行。在 `boothd` 尝试获取或续订票据之前，将调用所有脚本。要授予或续订票据，所有脚本必须成功。语义与单个脚本的语义相同：如果退出代码不为 `0`，`boothd` 将放弃票据。
13 | 产品中包含的 `/usr/share/booth/service-runnable` 脚本用作示例。要使用该脚本，请将它链接到相应的“票据”目录：
    root # ln -s /usr/share/booth/service-runnable /etc/booth.d/TICKET_NAME
假设 `/etc/booth.dTICKET_NAME` 目录包含 `service-runnable` 脚本。这个简单的脚本基于 `crm_simulate`。它可用于测试是否可以在当前群集站点上运行特定的群集资源。这意味着，它将检查群集运行状况是否足够良好，可以运行该资源（满足所有资源依赖关系、群集分区具有仲裁、没有脏节点，等等）。例如，如果依赖链中的某个服务在所有可用节点上的失败计数为 `INFINITY`，则无法在该站点上运行该服务。在这种情况下，声明票据就没有意义。
14 | `before-acquire-handler`（在本例中为 `service-runnable` 脚本）要测试的资源。需要参照相应票据保护的资源。在本示例中，资源·`db-1` 由 `ticketA` 保护，`db-8` 由 `ticketB` 保护。DRBD 的资源 (`ms_drbd_nfs`) 由票据 `ticket-nfs` 保护。
15 | 可选的参数。票据丢失后，投票间将额外等待这段时间，然后再获取票据。这样，丢失票据的站点便可以通过停止资源或者屏蔽资源来放弃资源。典型的延迟为 `60` 秒，但最终延迟取决于受保护的资源和屏蔽配置。默认值为 `0`。 如果您不确定停止资源、降级资源或屏蔽节点的时间有多长（该时间取决于 `loss-policy`），可以使用此参数来防止资源同时在两个站点上运行。

### 4.3.1 手动编辑投票间配置文件 #

1. 以 `root` 或同等身份登录到群集节点。

2. 如果 `/etc/booth/booth.conf` 尚不存在，请将示例投票间配置文件 `/etc/booth/booth.conf.example` 复制到 `/etc/booth/booth.conf`：

       root # cp -p /etc/booth/booth.conf.example /etc/booth/booth.conf

3. 根据例 4.1 “投票间配置文件”编辑 `/etc/booth/booth.conf`。

4. 确认更改并保存文件。

5. 在所有群集节点和仲裁方上，打开在防火墙中为投票间配置的端口。参见例 4.1 “投票间配置文件”中的位置 2。

### 4.3.2 使用 YaST 设置投票间 #

1. 以 `root` 或同等身份登录到群集节点。

2. 启动 YaST Geo 群集模块。

3. 选择编辑现有投票间配置文件，或者单击添加创建新的投票间配置文件。

   1. 在出现的屏幕中配置以下参数：

      - 配置文件： 投票间配置文件的名称。YaST 建议按默认使用 `booth`。这样，就会将投票间配置写入 `/etc/booth/booth.conf`。仅当您需要根据第 4.4 节 “使用多租户投票间设置”中所述为不同的 Geo 群集设置多个投票间实例时，才更改此值。

      - 传输： 用于站点间通讯的传输协议。仅支持 UDP，但将来可支持其他传输层。另请参见例 4.1 “投票间配置文件”中的位置 1。

      - 端口： 用于在每个站点上投票间实例之间通讯的端口。另请参见例 4.1 “投票间配置文件”中的位置 2。

      - 仲裁方： 用作仲裁方的计算机的 IP 地址。另请参见例 4.1 “投票间配置文件”中的位置 3。

        要指定仲裁方，请单击添加。在打开的对话框中，输入仲裁方的 IP 地址，然后单击确定。

      - 站点： 用于站点上 `boothd` 的 IP 地址。另请参见例 4.1 “投票间配置文件”中的位置 4。

        要指定 Geo 群集的站点，请单击添加。在打开的对话框中，输入一个站点的 IP 地址，然后单击确定。

      - 票据： 将由投票间或群集管理员管理的票据。另请参见例 4.1 “投票间配置文件”中的位置 6。

        要指定票据，请单击添加。在打开的对话框中，输入唯一的票据名称。若要使用相同的参数和值定义多个票据，请创建一个“票据模板”来为所有票据指定默认参数和值，从而减少配置工作量。为此，请使用 `__default__` 作为票据名称。

      - 身份验证： 要为投票间启用身份验证，请单击身份验证，然后在打开的对话框中，激活启用安全身份验证。如果已有一个密钥，请在身份验证文件中指定路径和文件名。要为新的 Geo 群集生成密钥文件，请单击生成身份验证密钥文件。随后将创建密钥并将其写入身份验证文件中指定的位置。

        此外，可以指定票据的可选参数。有关概述，请参见例 4.1 “投票间配置文件”中的位置 7 到 15。

        单击确定确认更改。

      图 4.1︰ 示例票据依赖项 #

   2. 单击确定关闭当前投票间配置屏幕。YaST 将显示定义的投票间配置文件的名称。

4. 在关闭 YaST 模块之前，请切换到防火墙配置类别。

5. 要打开您为投票间配置的端口，请启用打开防火墙中的端口。

   重要：防火墙设置仅适用于本地计算机

   防火墙设置仅适用于当前计算机。将为 `/etc/booth/booth.conf` 中指定的所有端口或者其他任何投票间配置文件打开 UDP/TCP 端口（请参见第 4.4 节 “使用多租户投票间设置”）。

   请确保同时在 Geo 群集的其他所有节点和仲裁方上打开相应的端口。可以手动或者通过将以下文件与 Csync2 同步来执行此操作：

   - `/usr/lib/firewalld`

   - `/usr/lib/firewalld/services/booth.xml`

6. 单击完成确认所有设置并关闭 YaST 模块。根据步骤 3.a 中指定的配置文件的 NAME，配置将写入 `/etc/booth/NAME.conf`。

## 4.4 使用多租户投票间设置 #

对于包含多个 Geo 群集的设置，可以“共享”同一个仲裁方（从 SUSE Linux Enterprise High Availability Extension 12 开始）。通过提供多个投票间配置文件，可以在同一个仲裁方上启动多个投票间实例，其中每个投票间实例在不同的端口上运行。这样，便可以使用一台计算机充当不同 Geo 群集的仲裁方。

假设您有两个 Geo 群集，一个位于 EMEA（欧洲、中东和非洲），另一个位于 APAC（亚太区）。

要为这两个 Geo 群集使用同一个仲裁方，请在 `/etc/booth` 目录中创建两个配置文件：`/etc/booth/emea.conf` 和 `/etc/booth/apac.conf`。最起码，这两个配置文件的以下参数必须不同：

- 用于投票间实例通讯的端口。

- 属于使用仲裁方的不同 Geo 群集的站点。

例 4.2︰ `/etc/booth/apac.conf` #

    transport = UDP 1
    port = 9133 2
    arbitrator = 192.168.203.100 3
    site = 192.168.2.254 4
    site = 192.168.1.112 4
    authfile = /etc/booth/authkey-apac 5
    ticket ="tkt-db-apac-intern" 6
         timeout = 10
         retries = 5
         renewal-freq = 60
         before-acquire-handler12 = /usr/share/booth/service-runnable13 db-apac-intern 14
    ticket = "tkt-db-apac-cust" 6
         timeout = 10
         retries = 5
         renewal-freq = 60
         before-acquire-handler = /usr/share/booth/service-runnable db-apac-cust

例 4.3︰ `/etc/booth/emea.conf` #

    transport = UDP 1
    port = 9150 2
    arbitrator = 192.168.203.100 3
    site = 192.168.201.100 4
    site = 192.168.202.100 4
    authfile = /etc/booth/authkey-emea 5
    ticket = "tkt-sap-crm" 6
         expire = 900
         renewal-freq = 60
         before-acquire-handler12 = /usr/share/booth/service-runnable13 sap-crm 14
    ticket = "tkt-sap-prod" 6
         expire = 600
         renewal-freq = 60
         before-acquire-handler = /usr/share/booth/service-runnable sap-prod

1 | 用于站点间通讯的传输协议。仅支持 UDP，但将来可支持其他传输层。因此，目前可以省略此参数。
2 | 用于在每个站点上投票间实例之间通讯的端口。配置文件使用不同的端口来允许在同一仲裁方上启动多个投票间实例。
3 | 用作仲裁方的计算机的 IP 地址。在上述示例中，我们为不同的 Geo 群集使用了同一个仲裁方。
4 | 用于站点上 `boothd` 的 IP 地址。两个投票间配置文件中定义的站点不同，因为这些站点属于两个不同的 Geo 群集。
5 | 可选的参数。基于共享密钥为客户端和服务器启用投票间身份验证。此参数指定密钥文件的路径。为不同的租户使用不同的密钥文件。 密钥要求 # 密钥可以是二进制数或文本。 如果是文本，将忽略以下字符：前置和尾随空格、换行符。 密钥长度必须为 8 到 64 个字符。 密钥必须属于用户 `hacluster` 和组 `haclient`。 密钥必须只能由文件所有者读取。
6 | 将由投票间或群集管理员管理的票据。理论上讲，可以在不同的投票间配置文件中定义相同的票据名称 — 票据不会造成干扰，因为它们属于不同投票间实例管理的不同 Geo 群集。但是，（为了便于讲述），我们建议按上述示例中所示，为每个 Geo 群集使用不同的票据名称。
12 | 可选的参数。如果设置该参数，则在 `boothd` 尝试获取或续订票据之前，将调用指定的命令。如果退出代码不为 `0`，`boothd` 将放弃票据。
13 | 此处提到的 `service-runnable` 脚本在产品中用作示例。它是一个基于 `crm_simulate` 的简单脚本。它可用于测试是否可以在当前群集站点上运行特定的群集资源。这意味着，它将检查群集运行状况是否足够良好，可以运行该资源（满足所有资源依赖关系、群集分区具有仲裁、没有脏节点，等等）。例如，如果依赖链中的某个服务在所有可用节点上的失败计数为 `INFINITY`，则无法在该站点上运行该服务。在这种情况下，声明票据就没有意义。
14 | `before-acquire-handler`（在本例中为 `service-runnable` 脚本）要测试的资源。需要参照相应票据保护的资源。

过程 4.1︰ 为不同的 Geo 群集使用相同的仲裁方 #

1. 如例 4.2 “`/etc/booth/apac.conf`”和例 4.3 “`/etc/booth/emea.conf`”中所述，在 `/etc/booth` 中创建不同的投票间配置文件。可以手动执行此操作，或者按第 4.3.2 节 “使用 YaST 设置投票间”中所述使用 YaST 来创建。

2. 在仲裁方上，打开 `/etc/booth` 中任一投票间配置文件内定义的端口。

3. 在属于使用仲裁方的单个 Geo 群集的节点上，打开相应投票间实例所用的端口。

4. 在使用相同投票间配置的所有群集节点和仲裁方上，同步相应的投票间配置文件。有关详细信息，请参见第 4.5 节 “将投票间配置同步到所有站点和仲裁方”。

5. 在仲裁方上，按在仲裁方上启动投票间服务中所述为多租户设置启动各个投票间实例。

6. 在各个 Geo 群集上，按在群集站点上启动投票间服务中所述启动投票间服务。

## 4.5 将投票间配置同步到所有站点和仲裁方 #

注意：在所有站点和仲裁方上使用相同的投票间配置

要使投票间正常工作，一个 Geo 群集中的所有群集节点和仲裁方必须使用相同的投票间配置。

可以使用 Csync2 来同步投票间配置。有关细节，请参见第 5.1 节 “Geo 群集的 Csync2 设置”和第 5.2 节 “使用 Csync2 同步更改”。

如果任何投票间配置发生更改，请务必在所有参与方上相应地更新配置文件，并按第 4.7 节 “运行时重配置投票间”中所述重启动投票间服务。

## 4.6 启用和启动投票间服务 #

在群集站点上启动投票间服务

  每个群集站点的投票间服务都通过投票间资源组（如果您是使用引导脚本设置 Geo 群集的，则其已自动配置，否则请按第 6.2 节 “配置 `boothd` 的资源组”中所述手动配置）来管理。要为每个站点启动一个投票间服务实例，请在每个群集站点上启动相应的投票间资源组。

在仲裁方上启动投票间服务

  从 SUSE Linux Enterprise 12 开始，投票间仲裁方由 systemd 管理。单元文件名为 `booth@.service`。`@` 表示可以使用一个参数（在本例中为配置文件的名称）运行该服务。

  要在仲裁方上启用投票间服务，请使用以下命令：

      root # systemctl enable booth@booth

  从命令行启用服务后，只要该服务未被禁用，就可以使用 YaST 服务管理器对它进行管理。如果该服务已禁用，则下一次重启动 systemd 时，它将从 YaST 的服务列表中消失。

  用于启动投票间服务的命令取决于投票间设置：

  - 如果按第 4.3 节中所述使用默认设置，则表示只配置了 `/etc/booth/booth.conf`。在这种情况下，请登录到每个仲裁方并使用以下命令：

        root # systemctl start booth@booth

  - 如果按第 4.4 节中所述以多租户模式运行投票间，则已在 `/etc/booth` 中配置了多个投票间配置文件。要为单个投票间实例启动服务，请使用 `systemctl start booth@` NAME，其中的 NAME 代表相应配置文件 `/etc/booth/NAME.conf` 的名称。

    例如，如果创建了投票间配置文件 `/etc/booth/emea.conf` 和 `/etc/booth/apac.conf`，请登录到仲裁方并执行以下命令：

        root # systemctl start booth@emea
        root # systemctl start booth@apac

  这将以仲裁方模式启动投票间服务。它可以与所有其他投票间守护程序通讯，但和群集站点上运行的投票间守护程序不同，它不能被授予票据。投票间仲裁方只参与选择。否则，它们处于休眠状态。

## 4.7 运行时重配置投票间 #

如果在已运行投票间服务的情况下需要更改投票间配置，请执行以下操作：

1. 根据需要调整投票间配置文件。

2. 将更新的投票间配置文件同步到属于 Geo 群集的所有群集节点和仲裁方。有关详细信息，请参见第 5 章 “跨所有站点和仲裁方同步配置文件”。

3. 按第 4.6 节 “启用和启动投票间服务”中所述，在仲裁方和站点上重启动投票间服务。这不会给已授予站点的票据造成任何影响。

# 5 跨所有站点和仲裁方同步配置文件 #

要跨群集中的所有节点和跨 Geo 群集复制重要配置文件，可以使用 Csync2。Csync2 可处理排入同步组的任意数量的主机。每个同步组都有自己的成员主机列表及其包含/排除模式，包含/排除模式定义了在同步组中应同步哪些文件。同步组、属于每个组的主机名以及每个组的包含/排除规则均在 Csync2 配置文件 `/etc/csync2/csync2.cfg` 中指定。

对于身份验证，Csync2 使用 IP 地址和同步组中的预共享密钥。需要为每个同步组生成一个密钥文件，并将其复制到所有组成员。

Csync2 将通过 TCP 端口（默认为 `30865`）访问其他服务器，并启动远程 Csync2 实例。有关 Csync2 的详细信息，请参见 http://oss.linbit.com/csync2/paper.pdf。

## 5.1 Geo 群集的 Csync2 设置 #

Book “管理指南”, Chapter 4 “使用 YaST 群集模块”, Section 4.5 “将配置传输到所有节点”中介绍了如何使用 YaST 为单个群集设置 Csync2。但是，如同无法处理 Geo 群集所需的设置一样，YaST 无法处理较复杂的 Csync2 设置。对于图 5.1 “Geo 群集的示例 Csync2 设置”中所示的以下设置，可以通过编辑配置文件来手动配置 Csync2。

要调整 Csync2，以便不仅能够在本地群集内部同步文件，而且还能跨地理分散的站点同步文件，您需要在 Csync2 配置中定义两个同步组：

- 全局组 `ha_global`（适用于需要跨 Geo 群集中的所有站点和仲裁方全局同步的文件）。

- 用于本地群集站点的组 `ha_local`（适用于需要在本地群集内部同步的文件）。

有关这两个同步组的多个 Csync2 配置文件的概述，请参见图 5.1 “Geo 群集的示例 Csync2 设置”。

图 5.1︰ Geo 群集的示例 Csync2 设置 #

身份验证密钥文件及其参照以红色显示。Csync2 配置文件的名称以蓝色显示，其参照以绿色显示。有关细节，请参见示例 Csync2 设置：配置文件。

示例 Csync2 设置：配置文件 #

`/etc/csync2/csync2.cfg`

  主要 Csync2 配置文件。我们特意精简了此文件，其中只包含以下信息：

  - 同步组 `ha_local` 的定义。该组包括两个节点（`this-site-host-1` 和 `this-site-host-2`），使用 `/etc/csync2/ha_local.key` 进行身份验证。要为此组同步的文件列表只在另一个 Csync2 配置文件 `/etc/csync2/ha_local.cfg` 中做了定义。`config` 语句包含了此定义。

  - 对另一个 Csync2 配置文件 `/etc/csync2.cfg/ha_global.cfg` 的参照包含在 `config` 语句中。

`/etc/csync2/ha_local.cfg`

  此文件仅与本地群集相关。它指定只在 `ha_local` 同步组内部同步的文件列表，因为这些文件特定于每个群集。最重要的文件如下：

  - `/etc/csync2/csync2.cfg`，此文件包含本地群集节点的列表。

  - `/etc/csync2/ha_local.key`，用于在本地群集内部进行 Csync2 同步的身份验证密钥。

  - `/etc/corosync/corosync.conf`，此文件定义本地群集节点之间的通讯通道。

  - `/etc/corosync/authkey`，Corosync 身份验证密钥。

  文件列表中的其余文件取决于特定的群集设置。图 5.1 “Geo 群集的示例 Csync2 设置”中所列的文件只是示例。如果还要同步任何站点特定应用程序的文件，请同时将这些文件包含在 `ha_local.cfg` 中。尽管 `ha_local.cfg` 面向属于 Geo 群集站点之一的节点，但其内容在所有站点上可以相同。如果需要不同的主机集或不同的密钥，可能需要添加额外的组。

`/etc/csync2.cfg/ha_global.cfg`

  此文件定义 Csync2 同步组 `ha_global`。该组跨越多个站点中的所有群集节点（包括仲裁方）。由于我们建议针对每个 Csync2 同步组使用不同的密钥，此组使用 `/etc/csync2/ha_global.key` 进行身份验证。`include` 语句定义要在 `ha_global` 同步组内部同步的文件列表。最重要的文件如下：

  - `/etc/csync2/ha_global.cfg` 和 `/etc/csync2/ha_global.key`（`ha_global` 同步组的配置文件，以及用于在组内部进行同步的身份验证密钥）。

  - `/etc/booth/`，用于保存投票间配置的默认目录。如果您为多个租户使用投票间设置，该设置将包含多个投票间配置文件。如果为投票间使用身份验证，则最好是也在此目录中放置密钥文件。

  - `/etc/drbd.conf` 和 `/etc/drbd.d`（如果在群集设置中使用 DRBD）。DRBD 配置可全局同步，因为它从资源配置文件中包含的主机名派生配置。

  - `/etc/zypp/repos.de`。软件包软件源有可能在所有群集节点上相同。

  显示的其他文件 (`/etc/root/*`) 是出于方便可以包含的示例（使群集管理员的工作变得更简单）。

注意

文件 `csync2.cfg` 和 `ha_local.key` 特定于站点，这意味着，需要为每个群集站点创建不同的文件。这些文件在属于同一群集的节点上相同，但在其他群集上则不同。每个 `csync2.cfg` 文件需要包含属于站点的主机（群集节点）列表，加上站点特定的身份验证密钥。

仲裁方也需要 `csync2.cfg` 文件。不过，仲裁方只需参照 `ha_global.cfg`。

## 5.2 使用 Csync2 同步更改 #

要成功地使用 Csync2 同步文件，必须满足以下先决条件：

- 在属于同一个同步组的所有计算机上提供相同的 Csync2 配置。

- 必须在该组的所有成员上提供每个同步组的 Csync2 身份验证密钥。

- Csync2 必须在所有节点和仲裁方上运行。

因此，在首次运行 Csync2 之前，需要做好以下准备：

1. 根据每个同步组登录到一台计算机，然后为相应的组生成身份验证密钥：

       root # csync2 -k NAME_OF_KEYFILE

   但是，不要在同一个组的其他任何成员上重复生成密钥文件。

   对于图 5.1 “Geo 群集的示例 Csync2 设置”，这会生成以下密钥文件：`/etc/csync2/ha_global.key` 以及每个站点的一个本地密钥 (`/etc/csync2/ha_local.key`)。

2. 将每个密钥文件复制到相应同步组的所有成员。对于图 5.1 “Geo 群集的示例 Csync2 设置”：

   1. 将 `/etc/csync2/ha_global.key` 复制到所有各方（Geo 群集所有站点上的仲裁方和所有群集节点）。需要在 `ha_global.cfg` 中定义的 `ha_global` 组内所列的所有主机上提供密钥文件。

   2. 将每个站点的本地密钥文件 (`/etc/csync2/ha_local.key`) 复制到属于 Geo 群集相应站点的所有群集节点上。

3. 将站点特定的 `/etc/csync2/csync2.cfg` 配置文件复制到属于 Geo 群集相应站点的所有群集节点，并复制到仲裁方。

4. 在所有节点和仲裁方上执行以下命令，使 csync2 服务在引导时自动启动：

       root # systemctl enable csync2.socket

5. 在所有节点和仲裁方上执行以下命令，以便立即启动服务：

       root # systemctl start csync2.socket

过程 5.1︰ 使用 Csync2 同步文件 #

1. 要对所有文件执行一次初始同步，请在要从中复制配置的计算机上执行以下命令：

       root # csync2 -xv

   这会将所有文件推送到同步组的其他成员，从而同步所有文件一次。如果所有文件都成功同步，则 Csync2 将完成，不会报错。

   如果在其他计算机（而不仅是当前节点）上对要同步的一个或多个文件进行了修改，Csync2 将报告冲突。您将得到类似以下内容的输出：

       While syncing file /etc/corosync/corosync.conf:
       ERROR from peer site-2-host-1: File is also marked dirty here!
       Finished with 1 errors.

2. 如果确信当前计算机上的文件版本是“最佳”版本，可以通过强制使用此文件并重新同步来解决冲突：

       root # csync2 -f /etc/corosync/corosync.conf
       root # csync2 -x

有关 Csync2 选项的更多信息，请运行 `csync2` `-help`。

注意：发生任何更改后推送同步

Csync2 仅推送更改。它不会在计算机之间连续同步文件。

每次更新需要同步的文件时，都必须将更改推送到同一个同步组的其他计算机：在执行更改的计算机上运行 `csync2` `-xv`。如果对未更改文件的任何其他计算机运行此命令，则不会执行任何操作。

# 6 配置群集资源和约束 #

除了定义特定群集设置所需的资源和约束外，Geo 群集还需要下文所述的其他资源和约束。可按以下示例中所示使用 crm 外壳 (crmsh) 或者使用 Hawk2 来配置这些资源和约束。

本章重点介绍特定于 Geo 群集的任务。有关您的首选群集管理工具的简介以及如何使用该工具配置资源和约束的一般说明，请参见以下其中一章：

- Book “管理指南”, Chapter 7 “使用 Hawk2 配置和管理群集资源”

- Book “管理指南”, Chapter 8 “配置和管理群集资源（命令行）”

如果您是使用引导脚本设置 Geo 群集的，那么投票间所需的群集资源（包括 boothd 的资源组）均已配置好。在此情况下，您可以跳过第 6.2 节，只需执行以下剩余步骤即可完成群集资源配置。

如果您要手动设置 Geo 群集，则需要执行以下所有步骤：

- 第 6.1 节 “配置资源的票据依赖项”

- 第 6.2 节 “配置 `boothd` 的资源组”

- 第 6.3 节 “添加顺序约束”

- 第 6.4 节 “将资源配置传输到其他群集站点”

重要：不跨站点进行 CIB 同步

CIB 不会跨 Geo 群集的群集站点自动同步。需要为每个站点相应地配置必须在 Geo 群集中保持高度可用的所有资源，或者需要将这些资源传输到其他一个或多个站点。

为简化传输过程，可以在配置任何包含站点特定参数的资源时为参数指定取决于运行资源的群集站点名称的值（另请参见第 3 章 “要求”中的其他要求和建议）。

在一个站点上配置资源后，可以标记所有群集站点上所需的资源，从当前 CIB 导出这些资源，然后将其导入另一站点的 CIB。有关详细信息，请参见第 6.4 节 “将资源配置传输到其他群集站点”。

## 6.1 配置资源的票据依赖项 #

对于 Geo 群集，可以指定哪些资源依赖于特定的票据。您可以与特定类型的约束一起，设置`丢失策略`，该策略定义撤消票据时应对相应资源采取哪些操作。`loss-policy` 属性可能具有以下值：

- `fence`：屏蔽运行相关资源的节点。

- `stop`：停止相关资源。

- `freeze`：不对相关资源执行任何操作。

- `demote`：将在主动模式下运行的相关资源降级为被动模式。

过程 6.1︰ 使用 crmsh 配置资源的票据依赖项 #

1. 在群集 amsterdam 的其中一个节点上，启动外壳并以 `root` 或同等身份登录。

2. 输入 `crm configure` 切换到交互式 crm 外壳。

3. 配置约束，用于定义哪些资源依赖于特定的票据。例如，要使原始资源 `rsc1` 依赖于 `ticketA`，请运行以下命令：

       crm(live)configure# rsc_ticket rsc1-req-ticketA ticketA: \
         rsc1 loss-policy="fence"

   如果已撤消 `ticketA`，应屏蔽运行资源的节点。

4. 如果希望其他资源依赖于其他票据，请使用 `rsc_ticket` 根据需要创建更多的约束。

5. 使用 `show` 查看更改。

6. 如果所有设置均正确无误，请使用 `commit` 提交更改，然后使用 `quit` 离开 crm 在线配置。

   配置将保存到 CIB。

## 6.2 配置 `boothd` 的资源组 #

如果您是使用 引导脚本设置 Geo 群集的，则可以跳过下面的过程，因为在此情况下，boothd 的资源和资源组已配置好。

每个站点都需要运行 `boothd` 的一个实例以与其他投票间守护程序通讯。该守护程序可以在任何节点上启动，因此应将其配置为原始资源。要使 `boothd` 资源保持在同一节点上，则在可行的情况下将资源粘性添加到配置中。每个守护程序都需要一个永久 IP 地址，因此请用虚拟 IP 地址配置另一个原始资源。将两个原始资源分组：

1. 在群集 `amsterdam` 的其中一个节点上，启动外壳并以 `root` 或同等身份登录。

2. 输入 `crm configure` 切换到交互式 crm 外壳。

3. 输入以下命令创建两个原始资源，并将它们添加到一个组 `g-booth`：

       crm(live)configure# primitive ip-booth ocf:heartbeat:IPaddr2 \
         params iflabel="ha" nic="eth1" cidr_netmask="24"
         params rule #cluster-name eq amsterdam ip="192.168.201.100" \
         params rule #cluster-name eq berlin ip="192.168.202.100"
       crm(live)configure# primitive booth-site ocf:pacemaker:booth-site \
         meta resource-stickiness="INFINITY" \
         params config="nfs" op monitor interval="10s"
       crm(live)configure# group g-booth ip-booth booth-site

   通过这种配置，每个投票间守护程序都将在各自的 IP 地址处可用，独立于运行守护程序的节点。

4. 使用 `show` 查看更改。

5. 如果所有设置均正确无误，请使用 `commit` 提交更改，然后使用 `quit` 离开 crm 在线配置。

   配置将保存到 CIB。

## 6.3 添加顺序约束 #

如果票据已授予某个站点，但因任何原因导致该站点的所有节点无法托管 `boothd` 资源组，则可能导致分布于不同地理位置的站点之间出现“节点分裂”现象。在这种情况下，系统无法通过任何 `boothd` 实例针对其他站点安全地管理票据故障转移。要避免该票据出现潜在的并发性违规（票据同时授予给多个站点），请添加一个顺序约束：

1. 在群集 amsterdam 的其中一个节点上，启动外壳并以 `root` 或同等身份登录。

2. 输入 `crm configure` 切换到交互式 crm 外壳。

3. 创建顺序约束，例如：

       crm(live)configure# order o-booth-before-rsc1 Mandatory: g-booth rsc1

   该约束定义 `rsc1`（依赖于 `ticketA`）只能在 `g-booth` 资源组之后启动。

4. 对于依赖于某个特定票据的任何其他资源，定义更多顺序约束。

5. 使用 `show` 查看更改。

6. 如果所有设置均正确无误，请使用 `commit` 提交更改，然后使用 `quit` 离开 crm 在线配置。

   配置将保存到 CIB。

## 6.4 将资源配置传输到其他群集站点 #

完成或更改一个群集站点的资源配置后，请将该配置传输到 Geo 群集的其他站点。

为了简化传输，可以标记所有群集站点上所需的任何资源，从当前 CIB 导出这些资源，然后将其导入另一站点的 CIB。标记不会在资源之间创建任何共置或顺序关系。

过程 6.2 “标记并导出资源配置”和过程 6.3 “导入标记的资源配置”中提供了操作方法的示例。它们基于以下先决条件：

先决条件 #

- 有一个包含两个站点的 Geo 群集：群集 `amsterdam` 和群集 `berlin`。

- 已在相应的 `/etc/corosync/corosync.conf` 文件中定义每个站点的群集名称。

      totem {
           [...]
           cluster_name: amsterdam
           }

  您可以手动完成此操作（即编辑 `/etc/corosync/corosync.conf`），也可以通过 YaST 群集模块进行（即切换到通讯通道类别，然后定义群集名称）。然后停止群集服务，再将其启动，以使更改生效：

      root # crm cluster restart

- 已在站点 `amsterdam` 上的 CIB 中配置应在 Geo 群集中高度可用的投票间和所有服务的必要资源。这些资源将导入到站点 `berlin` 上的 CIB 中。

过程 6.2︰ 标记并导出资源配置 #

1. 登录到群集 `amsterdam` 的节点之一。

2. 使用以下命令启动群集：

       root # crm cluster start

3. 输入 `crm configure` 切换到交互式 crm 外壳。

4. 查看当前 CIB 配置：

       crm(live)configure# show

5. 使用标记 `geo_resources` 来标记 Geo 群集中需要的资源和约束：

       crm(live)configure# tag geo_resources: \
         LIST_OF_RESOURCES_and_CONSTRAINTS_FOR_REQUIRED_SERVICES 1\
         rsc1-req-ticketA ip-booth booth-site g-booth o-booth-before-rsc1 2

   1 | Geo 群集中所有站点上都需要的特定设置的任何资源和约束（例如，SUSE 最佳实践文档中所述的 DRBD 的资源）。
   2 | boothd 的资源和约束（原始资源、投票间资源组、票据依赖项、其他顺序约束），请参见第 6.1 节至第 6.3 节。

6. 使用 `show` 查看更改。

7. 如果配置符合您的要求，请使用 `submit` 提交更改，然后使用 `quit` 退出 crm 在线外壳。

8. 将标记的资源和约束导出到名为 `exported.cib` 的文件：

       root # crm configure show tag:geo_resources geo_resources > exported.cib

   命令 `crm configure show tag:`标记名称将显示属于标记标记名称的所有资源。

过程 6.3︰ 导入标记的资源配置 #

要将保存的配置文件导入到第二个群集站点的 CIB 中，请执行以下操作：

1. 登录群集 `berlin` 的其中一个节点。

2. 使用以下命令启动群集：

       root # crm cluster start

3. 将群集 `amsterdam` 中的文件 `exported.cib` 复制到此节点。

4. 将文件 `exported.cib` 中标记的资源和约束导入群集 `berlin` 的 CIB：

       root # crm configure load update PATH_TO_FILE/exported.cib

   为 `crm configure load` 命令使用 `update` 参数时，crmsh 会尝试将文件内容集成到当前的 CIB 配置（而不是将当前 CIB 替换为文件内容）。

5. 使用以下命令查看更新的 CIB 配置：

       root # crm configure show

   导入的资源和约束将显示在 CIB 中。

# 7 通过 DNS 更新设置 IP 转移 #

如果 Geo 群集的一个站点关闭并且发生了票据故障转移，您通常需要相应地调整网络路由（或者需要事先为每个票据配置网络故障转移）。根据绑定到票据的服务类型，可以使用一种备选的解决方案来重配置路由：使用动态 DNS 更新并更改服务的 IP 地址。

此方案必须满足以下先决条件：

- 需要故障转移的服务已绑定到某个主机名。

- DNS 服务器必须针对动态 DNS 更新进行了配置。有关如何使用 BIND/named 执行此操作的信息，请参见 `named` 文档或访问 http://www.semicomplete.com/articles/dynamic-dns-with-dhcp/。 SUSE Linux Enterprise Server 15 SP4 的《管理指南》 中提供了有关如何设置 DNS（包括区域数据的动态更新）的详细信息。

- 以下示例假设 DNS 更新受到要更新的区域的共享密钥（TSIG 密钥）保护。可以使用 `dnssec-keygen` 创建该密钥：

      root # dnssec-keygen -a hmac-md5 -b 128 -n USER geo-update

  有关详细信息，请参见 `dnssec-keygen` 手册页或 SUSE Linux Enterprise Server 15 SP4 的《管理指南》。

例 7.1 “动态 DNS 更新的资源配置”演示了如何使用 `ocf:heartbeat:dnsupdate` 资源代理来管理 `nsupdate` 命令。 该资源代理支持 IPv4 和 IPv6。

例 7.1︰ 动态 DNS 更新的资源配置 #

    crm(live)configure# primitive dns-update-ip ocf:heartbeat:dnsupdate params \
      hostname="www.domain.com"1 ip="192.168.3.4"2\
      keyfile="/etc/whereever/Kgeo-update*.key"3\
      server="192.168.1.1"4 serverport="53"5

1 | 与需要连同票据一起故障转移的服务绑定的主机名。需要通过动态 DNS 更新此主机名的 IP 地址。
2 | 托管要迁移的服务的服务器的 IP 地址。 此处指定的 IP 地址也可以受群集控制。这不会处理本地故障转移，但可以确保在票据故障转移后，外部各方将会定向到正确的站点。
3 | 使用 `dnssec-keygen` 生成的公共密钥文件的路径。
4 | 要将更新发送到的 DNS 服务器的 IP 地址。如果未提供服务器，则默认为正确区域的主服务器。
5 | 与 DNS 服务器通讯时使用的端口。仅当指定了 DNS 服务器时，此选项才生效。

在使用上述资源配置的情况下，资源代理将负责从 DNS 记录中去除发生故障的 Geo 群集站点，并通过动态 DNS 更新来更改服务的 IP。

# 8 管理 Geo 群集 #

在投票间能够管理 Geo 群集中的某个票据之前，您需要先通过投票间命令行客户端或 Hawk2 手动将其授予给某个站点。

## 8.1 通过命令行管理票据 #

按第 8.1.1 节 “`booth` 命令概述”中所述使用 `booth` 命令行工具授予、列出或撤消票据。

警告：`crm_ticket` 和 `crm site ticket`

如果由于某些原因投票间服务未运行，您也可以使用 `crm_ticket` 或 `crm site ticket` 完全以手动方式管理票据。这两个命令仅在群集节点上可用。使用这些命令要非常小心，因为它们无法校验同一票据是否已授予给其他站点。有关详细信息，请阅读手册页。

只要投票间在正常运行，请一律仅使用 `booth` 进行手动干预。

### 8.1.1 `booth` 命令概述 #

您可以在群集中的任何计算机上运行 `booth` 命令，而不仅仅是正在运行 `boothd` 的计算机上。`booth` 命令会尝试通过查看投票间配置文件和本地定义的 IP 地址来查找“本地”群集。如果未指定 `booth` 应连接到的站点（使用 `-s` 选项），则其一律会连接到本地站点。

列出所有票据

      root # booth list
      ticket: ticketA, leader: none
      ticket: ticketB, leader: 10.2.12.101, expires: 2014-08-13 10:28:57

  如果未使用 `-s` 指定特定的站点，将从本地投票间实例请求有关票据的信息。

向站点授予票据

      root # booth grant -s 192.168.201.100 ticketA
      booth[27891]: 2014/08/13_10:21:23 info: grant request sent, waiting for the result ...
      booth[27891]: 2014/08/13_10:21:23 info: grant succeeded!

  在这种情况下，`ticketA` 将授予给站点 `192.168.201.100`，如果未使用 `-s` 选项，投票间将自动连接到当前站点（您运行投票间客户端的站点）并会请求 `grant` 操作。

  在授予票据前，该命令将执行健全性检查。如果同一票据已授予给其他站点，则系统会向您发出警告，并提示您先从当前站点撤消该票据。

从站点撤消票据

      root # booth revoke ticketA
      booth[27900]: 2014/08/13_10:21:23 info: revoke succeeded!

  投票间将检查当前向哪个站点授予了票据，并针对 `ticketA` 请求 `revoke` 操作。撤消操作将立即执行。

  `grant` 和（在某些情况下）`revoke` 操作可能需要一段时间才会返回确切的操作结果。客户端将一直等待结果，直到达到票据的 `timeout` 值才会放弃等待。如果使用了 `-w` 选项，客户端将会无限期等待。在日志文件中或者使用 `crm_ticket -L` 命令查找确切的状态。

强制执行授予操作

      root # booth grant -F ticketA

  此命令的结果取决于您使用的是自动票据还是手动票据。

  - 自动票据：只要投票间可确保仅将票据授予给一个站点，您就无法将同一票据授予给其他站点，即使使用 `-F` 选项也不例外。但如果出现节点分裂情况，投票间便可能无法检查是否在其他站点授予了自动票据。在此情况下，Geo 群集管理员可以覆盖自动过程，并手动将票据授予给仍在正常运行的站点。在此情况下，`-F` 选项会告知投票间不要等待来自其他不可访问的站点的响应（如果为此票据定义了参数 expire 和 acquire-after，这样将会忽略这两个参数）。投票间会立即将票据授予给指定站点。

  - 手动票据：使用手动票据时，`booth grant -F` 可让投票间立即将票据授予给指定站点。

  警告：潜在的数据丢失

  使用 `booth grant -F` 之前，请确保没有其他联机站点拥有同一票据。如果同一票据授予给多个站点，则依赖于该票据的资源可能会在多个站点上同时启动。这会导致并发性违规并可能造成数据损坏。

  作为 Geo 群集管理员，您需要在另一个站点恢复可访问状态时解决票据之间的冲突。

下面几节提供了在不同情形下管理票据的一些示例。

### 8.1.2 手动转移自动票据 #

假设您要将 `ticketA` 从站点 `amsterdam`（虚拟 IP 为 `192.168.201.100`）手动转移到站点 `berlin`（虚拟 IP 为 `192.168.202.100`），请执行以下操作：

1. 登录 `amsterdam`。

2. 使用以下命令将 `ticketA` 设为待机状态：

       root # crm_ticket -t ticketA -s

3. 等待任一资源（视 `ticketA` 而定）停止或完全降级。

4. 使用以下命令从站点 `amsterdam` 撤消 `ticketA`：

       root # booth revoke -s 192.168.201.100 ticketA

5. 从原始站点撤消票据后，使用以下命令将 `ticketA` 授予给站点 `berlin`：

       root # booth grant -s 192.168.202.100 ticketA

   这样依赖于此票据的资源便可以在站点 `berlin` 上启动。

6. 使用以下命令去除站点 `amsterdam` 上 `ticketA` 的待机模式：

       root # crm_ticket -t ticketA -a

   如果 `berlin` 发生故障，依赖于 `ticketA` 的资源将自动故障转移到站点 `amsterdam`。

### 8.1.3 转移手动票据 #

假设您要将手动票据 `ticket-nfs` 从站点 `amsterdam`（虚拟 IP 为 `192.168.201.100`）转移到站点 `berlin`（虚拟 IP 为 `192.168.202.100`），请执行以下操作：

1. 登录 `amsterdam`。

2. 使用以下命令将 `ticket-nfs` 设为待机状态：

       root # crm_ticket -t ticket-nfs -s

3. 等待依赖于 `ticket-nfs` 的任何资源停止或完全降级。

4. 使用以下命令从站点 `amsterdam` 撤消 `ticket-nfs`：

       root # booth revoke -s 192.168.201.100 ticket-nfs

5. 从原始站点撤消票据后，使用以下命令将 `ticket-nfs` 授予给站点 `berlin`：

       root # booth grant -s 192.168.202.100 ticket-nfs

   这样依赖于此票据的资源便可以在站点 `berlin` 上启动。

6. 如果您要在任何时间将资源转移回 `amsterdam`，请在站点 `amsterdam` 上去除 `ticket-nfs` 的待机模式：

       root # crm_ticket -t ticket-nfs -a

### 8.1.4 故障转移手动票据 #

我们假设（手动管理的）票据 `ticket-nfs` 已授予给站点 `amsterdam`（虚拟 IP 为 `192.168.201.100`）。目前无法访问此站点。站点 `berlin`（虚拟 IP 为 `192.168.202.100`）仍然可用。

1. 尝试联系站点 `amsterdam` 的本地管理员，并检查该站点是否发生故障。

   - 如果是，请执行步骤 2。

   - 如果因连接问题而无法访问 `amsterdam`，但该节点仍在运行，可请本地群集管理员在站点 `amsterdam` 上将 `ticket-nfs` 设为待机模式：

         root # crm_ticket -t ticket-nfs -s

     此操作将撤回依赖于 `ticket-nfs` 的资源。现在便可放心将票据授予给其他站点。

2. 登录 `berlin`。

3. 使用 `-F` 选项将 `ticket-nfs` 授予给站点 `berlin`：

       root # booth grant -F ticket-nfs

   系统会显示同一票据可能已授予给其他站点的警告，但会执行该命令。

4. 使用以下命令检查结果：

       root # booth list

   命令输出中应该会指出 `berlin` 现在是 `ticket-nfs` 的票据拥有者。依赖于此票据的所有资源都将在 `berlin` 上启动。

5. 在尝试重新将 `amsterdam` 添加到 Geo 群集中之前，请务必撤消 `amsterdam` 上的 `ticket-nfs`：

       root # booth revoke -s 192.168.201.100 ticket-nfs

## 8.2 使用 Hawk2 管理票据 #

在仪表板和状态视图中均可查看票据。Hawk2 显示以下票据状态：

- 已授予：已将票据授予给当前站点。

- 其他位置：已将票据授予给其他站点。

- 已撤消：已撤消票据。此外，如果在票据依赖项中参照了票据，但尚未将票据授予给任何站点，则 Hawk2 也将票据显示为已撤消。

注意：向当前站点授予票据和撤消票据

尽管您可以使用 Hawk2 查看所有站点的票据，但 Hawk2 触发的任何授予或撤消操作只适用于当前站点（当前使用 Hawk2 连接到的站点）。要将票据授予 Geo 群集的另一个站点，请在属于相应站点的其中一个群集节点上启动 Hawk2。

只能授予尚未指派给任何站点的票据。

过程 8.1︰ 使用 Hawk2 查看、授予和撤消票据 #

1. 启动 Web 浏览器并登录到 Hawk2。

2. 在左侧导航栏中，选择监视 › 状态。

   除了群集节点和资源的相关信息之外，Hawk2 还显示票据类别。其中会列出票据状态、票据名称以及上次授予票据的时间。您可以在已授予列中对票据进行管理。

3. 要显示有关票据的更多信息，以及有关群集站点和仲裁方的信息，请单击票据旁的细节图标。

   图 8.1︰ Hawk2 - 票据细节 #

4. 要从当前站点中撤消已授予的票据或者要向当前站点授予某个票据，请单击该票据旁边已授予列中的开关。单击后，将显示可用的操作。当 Hawk2 提示确认时，请确认选择。

   如果出于任何原因无法授予或撤消票据，Hawk2 将显示错误消息。如果已成功授予或撤消票据，Hawk2 将更新票据状态。

过程 8.2︰ 模拟授予和撤消票据 #

利用 Hawk2 的批模式，您可以在故障发生之前探测到该情况。要了解依赖于特定票据的资源是否按预期方式工作，您还可以测试授予或撤消票据产生的影响。

1. 启动 Web 浏览器并登录到 Hawk2。

2. 从顶层行中选择批模式。

3. 在批模式栏中，单击显示打开批模式窗口。

4. 要模拟票据的状态更改，请执行以下操作：

   1. 单击插入 › 票据事件。

   2. 依次选择要操作的票据和要模拟的操作。

   3. 确认更改。您的事件便会添加到批模式对话框中所列的事件队列中。此处列出的所有事件都会立即被模拟并反映到状态屏幕上。

   4. 关闭批模式对话框并查看模拟的更改。

5. 要退出批模式，请应用或丢弃模拟的更改。

图 8.2︰ Hawk2 模拟器 - 票据 #

有关 Hawk2 的批模式（以及可使用该批模式探测的其他情形）的详细信息，请参见Book “管理指南”, Chapter 7 “使用 Hawk2 配置和管理群集资源”, Section 7.9 “使用批模式”。

# 9 查错 #

投票间使用的日志记录机制与 CRM 相同。这样一来，更改日志级别的同时也会影响投票间日志记录。投票间日志消息还包含所有票据的信息。

投票间日志消息和投票间配置文件均包含在 `crm report` 中。

如果出现意外的投票间行为或任何问题，请使用 `sudo journalctl -n` 检查日志数据，或使用 `crm report` 创建详细的群集报告。

如果可以通过 SSH 从单个主机访问所有站点上的群集节点（包括仲裁方），则可以在同一份 `crm 报告`中收集所有节点的日志文件。使用 `-n` 选项调用 `crm report` 时，可以从使用 `-n` 指定的所有主机中获取日志文件。（如果不使用 `-n`，该命令将尝试从相应的群集获取节点列表）。例如，要创建一份 `crm 报告`，其中包含来自两个双节点群集（`192.168.201.111`|`192.168.201.112` 和 `192.168.202.111`|`192.168.202.112`）和仲裁方 (`147.2.207.14`) 的日志文件，请使用以下命令：

    root #  crm report -n "147.2.207.14 192.168.201.111 192.168.201.112 \
     192.168.202.111 192.168.202.112"  -f 10:00 -t 11:00 db-incident

如果问题只与投票间相关，并且您知道投票间在（站点内的）哪些群集节点上运行，请仅指定这两个节点和仲裁方。

如果无法从一台主机访问所有站点，请在仲裁方以及各站点的群集节点上分别运行 `crm report`，请记得指定相同的时间段。要收集仲裁方上的日志文件，必须为单个节点操作使用 `-S` 选项：

    amsterdam # crm report -f 10:00 -t 11:00 db-incident-amsterdam
    berlin # crm report -f 10:00 -t 11:00 db-incident-berlin
    arbitrator # crm report -S -f 10:00 -t 11:00 db-incident-arbitrator

但是，对于想要从中收集日志文件的所有计算机，最好是生成一份 `crm 报告`。

# 10 升级到产品的最新版本 #

有关如何升级群集节点的说明，请参见Book “管理指南”, Chapter 5 “升级群集和更新软件包”。本章还介绍了在开始升级前需要做好哪些准备工作，此外还概述了支持的升级路径并指出了可在何处找到每个步骤的细节。

如果您在群集站点之外使用了仲裁方，请按过程 10.1中所述升级仲裁方。

过程 10.1︰ 升级仲裁方 #

1. 按Book “管理指南”, Chapter 5 “升级群集和更新软件包”中所述升级到 SUSE Linux Enterprise Server 和 SUSE Linux Enterprise High Availability Extension 的所需目标版本。

2. 检查是否已启用Article “Geo 群集快速入门”, Section 3 “要求”中提到的模块和扩展。

3. 检查是否已安装 booth 软件包：

       root # zypper pa | grep booth

4. 如果未安装，请使用以下命令安装：

       root # zypper install booth

# 11 更多信息 #

- https://documentation.suse.com/sle-ha-15/ 上提供了更多有关此产品的文档。例如，《Geo Clustering Quick Start》（Geo 群集快速入门）将指导您使用 crm 外壳提供的 Geo 引导脚本完成 Geo 群集的基本设置。

- 以下 SUSE 最佳实践文档中提供了有关通过 DRBD 在 Geo 群集中数据复制的信息：https://documentation.suse.com/sbp/all/html/SBP-DRBD/index.html。

# A GNU licenses #

This appendix contains the GNU Free Documentation License version 1.2.

## GNU Free Documentation License #

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.

##### 0. PREAMBLE #

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.

##### 1. APPLICABILITY AND DEFINITIONS #

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.

##### 2. VERBATIM COPYING #

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.

##### 3. COPYING IN QUANTITY #

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.

##### 4. MODIFICATIONS #

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:

1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

4. Preserve all the copyright notices of the Document.

5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

8. Include an unaltered copy of this License.

9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

15. Preserve any Warranty Disclaimers.

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.

##### 5. COMBINING DOCUMENTS #

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".

##### 6. COLLECTIONS OF DOCUMENTS #

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.

##### 7. AGGREGATION WITH INDEPENDENT WORKS #

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.

##### 8. TRANSLATION #

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.

##### 9. TERMINATION #

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.

##### 10. FUTURE REVISIONS OF THIS LICENSE #

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.

##### ADDENDUM: How to use this License for your documents #

    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.