安裝與設定快速入門 #
SUSE Linux Enterprise High Availability Extension 15 SP2
此文件將引導您使用 ha-cluster-bootstrap
套件所提供的開機程序檔,完成最基本的雙節點叢集設定。其中包括將虛擬 IP 位址設定為叢集資源,以及在共享儲存上使用 SBD 做為節點圍籬區隔機制。
1 使用案例 #
透過本文件中介紹的程序,可完成對具有以下內容的雙節點叢集的最基本設定:
兩個節點:
alice
(IP:192.168.1.1
) 和bob
(IP:192.168.1.2
);兩者之間透過網路彼此連接。一個浮動的虛擬 IP 位址 (
192.168.2.1
)。用戶端可透過此位址連接到服務,而不管此服務在哪個實體節點上執行。一個共享儲存裝置,用做 SBD 圍籬區隔機制。這樣可以避免電腦分裂的情況。
若主動主機發生故障 (主動/被動設定),資源會從一個節點容錯移轉到另一個節點。
使用開機程序檔設定叢集後,我們將使用圖形 Hawk2 來監控叢集。它是叢集管理工具之一,隨附於 SUSE® Linux Enterprise High Availability Extension 中。為了對資源容錯移轉是否有效進行基本的測試,我們會將其中一個節點置於待命模式,然後檢查虛擬 IP 位址是否已移轉到另一個節點。
該雙節點叢集可用於測試的目的,也可以用做基本叢集組態,稍後再進行擴充。將叢集用於線上環境之前,請先根據自身要求對其進行修改。
2 系統要求 #
本章介紹第 1 節中所述案例的關鍵系統要求。若要將叢集調整為可用於生產環境,請參閱Book “管理指南”, Chapter 2 “系統要求與建議”中的完整清單。
2.1 硬體要求 #
- 伺服器
兩部已安裝第 2.2 節 「軟體要求」中指定的軟體的伺服器。
伺服器可以是裸機,也可以是虛擬機器。它們不需要使用相同的硬體 (記憶體、磁碟空間等等),但必須具有相同的架構。系統不支援跨平台叢集。
- 通訊通道
每個叢集節點至少有兩個 TCP/IP 通訊媒體。網路設備必須支援您希望用於叢集通訊的通信方式:多點傳播或單路廣播。通訊媒體應支援 100 Mbit/s 或更高的資料速率。對於受支援的叢集設定,需要兩個或以上的備援通訊路徑。可以透過以下方式來實現:
網路裝置結合 (優先)。
Corosync 中的另一個通訊通道。
- 節點圍籬區隔/STONITH
若要避免「電腦分裂」的情況,叢集需要有節點圍籬區隔機制。在出現電腦分裂的情況下,叢集節點會因硬體或軟體故障或者網路連接斷開而分成兩個或更多互不相識的群組。圍籬區隔機制會隔離存在問題的節點 (通常是透過重設節點或關閉節點的電源)。這也稱為 STONITH (「將其他節點爆頭」)。節點圍籬區隔機制可以是實體裝置 (電源開關),也可以是 SBD (依磁碟 STONITH) 等機制與監視程式相結合。使用 SBD 需要共享儲存。
2.2 軟體要求 #
將加入叢集的所有節點上都至少需安裝以下模組和延伸:
Base System Module 15 SP2
Server Applications Module 15 SP2
SUSE Linux Enterprise High Availability Extension 15 SP2
2.3 其他要求與建議 #
- 時間同步
叢集節點必須與叢集外的 NTP 伺服器同步。自 SUSE Linux Enterprise High Availability Extension 15 起,採用 chrony 做為 NTP 的預設實作。如需詳細資訊,請參閱 《SUSE Linux Enterprise Server 15 SP2 管理指南》。
若節點未同步,叢集可能無法正常運作。此外,記錄檔案和叢集報告在未同步的情況下很難進行分析。使用開機程序檔時,若尚未設定 NTP,系統會向您發出警告。
- 主機名稱與 IP 位址
使用靜態 IP 位址。
在
/etc/hosts
檔案中列出了所有叢集節點,包括完全合格的主機名稱和簡短主機名稱。叢集的成員必須能夠籍由名稱找到彼此,這是一項基本要求。如果名稱不可用,內部叢集通訊將會失敗。
- SSH
所有叢集節點必須能透過 SSH 互相存取。諸如
crm report
(用於疑難排解) 等工具以及 Hawk2 的 ,要求節點之間透過無密碼的 SSH 方式來存取,否則它們只能從目前節點收集資料。若使用開機程序檔設定叢集,系統會自動建立並複製 SSH 金鑰。
3 開機程序檔綜覽 #
來自 ha-cluster-bootstrap 套件的所有指令都會執行開機程序檔,而且所需的時間和手動介入極少。
使用
ha-cluster-init
可定義叢集通訊所需的基本參數。如此可讓您擁有一個正常運作的單節點叢集。使用
ha-cluster-join
可將更多節點新增到叢集中。使用
ha-cluster-remove
可從叢集中移除節點。
所有開機程序檔都會記錄至 /var/log/ha-cluster-bootstrap.log
。查看此檔案即可瞭解開機程序的詳細資料。開機過程中設定的任何選項都可在之後使用 YaST 叢集模組加以修改。如需詳細資料,請參閱Book “管理指南”, Chapter 4 “使用 YaST 叢集模組”。
每個程序檔都有相應的 man 頁面,其中涵蓋功能範圍、程序檔選項,以及程序檔可建立和修改的檔案的綜覽。
開機程序檔 ha-cluster-init
會檢查並設定以下元件:
- NTP
如果 NTP 未設定為在開機時啟動,則會出現一則訊息。自 SUSE Linux Enterprise High Availability Extension 15 起,採用 chrony 做為 NTP 的預設實作。
- SSH
它會建立用於在叢集節點之間進行無密碼登入的 SSH 金鑰。
- Csync2
它會設定 Csync2 在叢集中的所有節點之間複製組態檔案。
- Corosync
它會設定叢集通訊系統。
- SBD/監視程式
它會檢查是否存在監視程式,並詢問您是否將 SBD 設定為節點圍籬區隔系統。
- 虛擬浮動 IP
它會詢問您是否設定虛擬 IP 位址以使用 Hawk2 進行叢集管理。
- 防火牆
它會開啟叢集通訊所需的防火牆連接埠。
- 叢集名稱
它會為叢集定義名稱,預設為
hacluster
。叢集名稱是選擇性元件,對 Geo 叢集最有用。叢集名稱通常會反映位置,以便您更容易區分 Geo 叢集內部的站點。
4 安裝 SUSE Linux Enterprise High Availability Extension #
High Availability
安裝模式 (在指令行上以 sles_ha
指定) 中包含了使用 High Availability Extension 設定和管理叢集的套件。此模式只在 SUSE Linux Enterprise High Availability Extension 已做為 SUSE® Linux Enterprise Server 的延伸安裝後才能使用。
如需如何安裝延伸的資訊,請參閱 《Deployment Guide for SUSE Linux Enterprise Server 15 SP2》(SUSE Linux Enterprise Server 15 SP2 部署指南)。
High Availability
模式 #若尚未安裝此模式,請執行以下步驟:
透過指令行使用 Zypper 來安裝:
root #
zypper
install -t pattern ha_sles在所有將成為叢集成員的機器上安裝 High Availability 模式。
注意:在所有參與方上安裝軟體套件若想自動安裝 SUSE Linux Enterprise Server 15 SP2 與 SUSE Linux Enterprise High Availability Extension 15 SP2,請使用 AutoYaST 複製現有節點。如需詳細資訊,請參閱Book “管理指南”, Chapter 3 “安裝 High Availability Extension”, Section 3.2 “使用 AutoYaST 進行批量安裝和部署”。
在 SUSE Customer Center 上註冊機器。如需詳細資訊,請參閱 《SUSE Linux Enterprise Server 15 SP2 升級指南》。
5 將 SBD 用做圍籬區隔機制 #
若您擁有 SAN (儲存區域網路) 等共享儲存,可以使用它們來避免電腦分裂的情況。若要實現此目的,請設定 SBD 做為節點圍籬區隔機制。SBD 使用監視程式支援與外部/sbd
STONITH 資源代辦。
5.1 SBD 的要求 #
使用 ha-cluster-init
設定第一個節點時,可以決定是否使用 SBD。如果要使用,則需輸入共享儲存裝置的路徑。依預設,ha-cluster-init
會在要用於 SBD 的裝置上自動建立一個小分割區。
若要使用 SBD,必須符合以下要求:
針對叢集中的所有節點,共享儲存裝置的路徑必須永久且一致。請使用穩定的裝置名稱,例如
/dev/disk/by-id/dm-uuid-part1-mpath-abcedf12345
。SBD 裝置不得使用基於主機的 RAID、LVM2,也不能位於 DRBD* 例項上。
如需如何設定共享儲存的詳細資料,請參閱 《SUSE Linux Enterprise Server 15 SP2 儲存管理指南》。
5.2 對 SBD 啟用 Softdog 監視程式 #
依預設,SUSE Linux Enterprise 伺服器的核心中會啟用監視程式支援:本產品隨附了多個核心模組,可提供特定於硬體的監視程式驅動程式。High Availability Extension 使用 SBD 精靈做為「饋送」監視程式的軟體元件。
以下程序使用 softdog
監視程式。
Softdog 驅動程式假設至少有一個 CPU 仍然在執行。如果所有 CPU 均已堵塞,則 softdog 驅動程式中應該將系統重新開機的代碼永遠都不會執行。相反地,即使所有 CPU 均已堵塞,硬體監視程式也仍然會繼續運作。
強烈建議您於生產環境中使用叢集之前,以最適合您硬體的相應硬體模組取代 softdog
模組。
不過,如果沒有與您的硬體相符的監視程式,則可以將 softdog
當成核心監視程式模組使用。
如第 5.1 節 「SBD 的要求」中所述建立永久的共享儲存。
啟用 softdog 監視程式:
root #
echo
softdog > /etc/modules-load.d/watchdog.confroot #
systemctl
restart systemd-modules-load測試 softdog 模組是否已正確載入:
root #
lsmod
| grep dog softdog 16384 1
強烈建議您測試 SBD 圍籬區隔機制是否能正常阻止電腦分裂情況。此類測試可透過阻擋 Corosync 叢集通訊來完成。
6 設定第一個節點 #
使用 ha-cluster-init
程序檔設定第一個節點。此操作所需的時間和手動介入都極少。
ha-cluster-init
設定第一個節點 (alice
) #以
root
身分登入要當成叢集節點使用的物理機器或虛擬機器。執行如下指令啟動開機程序檔:
root #
ha-cluster-init
--name CLUSTERNAME以一個有意義的名稱 (例如叢集的地理位置
amsterdam
) 取代 CLUSTERNAME 預留位置。若要在稍後建立 Geo 叢集,這樣做特別有用,因為它使站點的識別變得簡單。如果您需要使用單點傳播而不是多路廣播 (預設方式) 來進行叢集通訊,請使用選項
-u
。安裝後,在檔案/etc/corosync/corosync.conf
中找到值udpu
。如果ha-cluster-init
偵測到節點正在 Amazon Web Services (AWS) 上執行,該程序檔將自動使用單點傳播做為叢集的預設通訊方式。這些程序檔會檢查是否存在 NTP 組態與硬體監視程式服務。這會產生 SSH 存取與 Csync2 同步所需的公用和私密 SSH 金鑰,並啟動相應的服務。
設定叢集通訊層 (Corosync):
輸入要繫結到的網路位址。程序檔預設將建議
eth0
網路位址。您也可以輸入不同的網路位址,如bond0
位址。輸入多路廣播位址。程序檔會建議一個隨機位址,您可將其做為預設值。當然,您特定的網路需要支援此多路廣播位址。
輸入多路廣播連接埠。程序檔會建議預設值
5405
。
將 SBD 設定為節點圍籬區隔機制:
輸入
y
確認您要使用 SBD。輸入要用於 SBD 的區塊裝置分割區的永久路徑 (請參閱第 5 節 「將 SBD 用做圍籬區隔機制」)。該路徑必須在叢集的所有節點間保持一致。
設定使用 Hawk2 進行叢集管理所需的虛擬 IP 位址。(稍後,我們將使用此虛擬 IP 資源測試容錯移轉是否成功)。
輸入
y
確認您要設定虛擬 IP 位址。為 Hawk2 的管理 IP 輸入想要的且未使用的 IP 位址:
192.168.2.1
您可以連接到此虛擬 IP 位址,而無需使用 Hawk2 登入個別叢集節點。
最後,該程序檔將啟動 Pacemaker 服務以使叢集上線,並啟用 Hawk2。Hawk2 要使用的 URL 會顯示在螢幕上。
您現在便擁有了一個正常運作的單節點叢集。若要檢視其狀態,請執行以下步驟:
在任一機器上,啟動網頁瀏覽器並確定已啟用 JavaScript 和 Cookie。
輸入任一執行 Hawk Web 服務之叢集節點的 IP 位址或主機名稱做為 URL。或者,輸入您在程序 2 「使用
ha-cluster-init
設定第一個節點 (alice
)」的步驟 5中設定的虛擬 IP 位址的位址。https://HAWKSERVER:7630/
注意:證書警告當您首次嘗試存取該 URL 時,如果系統顯示證書警告,則表示使用了自行簽署的證書。依預設,自行簽署的證書不被視為可信證書。
請咨詢您的叢集操作人員取得證書詳細資料,以驗證該證書。
若仍要繼續,您可以在瀏覽器中新增一個例外以略過此警告。
在 Hawk2 登入畫面中,輸入在開機程序中建立的使用者的
與 (使用者為hacluster
,密碼為linux
)。重要:安全密碼請立即以安全的密碼取代預設密碼:
root #
passwd
hacluster按一下
。登入後,Hawk2 Web 介面依預設會顯示「狀態」畫面,其中包括目前叢集狀態的概覽:圖 1︰ Hawk2 中單節點叢集的狀態 #
7 新增第二個節點 #
若您已設定並執行單節點叢集,請按程序 4 中所述,使用 ha-cluster-join
開機程序檔新增第二個叢集節點。該程序檔只需要存取一個現存叢集節點,然後便會自動在目前機器上完成基本設定。如需詳細資料,請參閱 ha-cluster-init
man 頁面。
開機程序檔負責變更特定於雙節點叢集的組態,例如 SBD 和 Corosync。
ha-cluster-join
新增第二個節點 (bob
) #以
root
身分登入要加入叢集的實體或虛擬機器。執行如下指令啟動開機程序檔:
root #
ha-cluster-join
如果 NTP 未設定為在開機時啟動,則會出現一則訊息。該程序檔還會檢查硬體監視程式裝置 (在要設定 SBD 時,此類裝置非常重要)。如果不存在此類裝置,將會向您發出警告。
如果您決定仍要繼續,系統將提示您輸入現存節點的 IP 位址。輸入第一個節點 (
alice
) 的 IP 位址192.168.1.1
)。如果尚未設定兩部機器之間的無密碼 SSH 存取,系統將提示您輸入現有節點的
root
密碼。登入指定節點後,程序檔將會複製 Corosync 組態,設定 SSH 與 Csync2,並使目前機器以新叢集節點的身分上線。除此之外,它還會啟動 Hawk2 所需的服務。
在 Hawk2 中檢查叢集狀態。在圖形 2 「雙節點叢集的狀態」)。
› 下,您應該會看見兩個狀態為綠色的節點 (請參閱8 測試叢集 #
第 8.1 節 「測試資源容錯移轉」是一項簡單的測試,可檢查當目前執行資源的節點被設定為待命
時,叢集是否將虛擬 IP 位址移動到另一個節點。
不過,實際測試會涉及特定的使用案例與情況,包括測試圍籬區隔機制以避免電腦分裂的情況。若尚未正確設定圍籬區隔機制,叢集將無法正常運作。
將該叢集用於生產環境之前,請依據自己的使用案例或者借助 ha-cluster-preflight-check
程序檔對叢集進行全面測試。
8.1 測試資源容錯移轉 #
請使用以下快速測試程序檢查資源容錯移轉:
開啟終端機並 ping
192.168.2.1
(即您的虛擬 IP 位址)。root #
ping
192.168.2.1按程序 3 「登入 Hawk2 Web 介面」中所述登入您的叢集。
在 Hawk2
› 中,檢查虛擬 IP 位址 (資源admin_addr
) 正在哪個節點上執行。假設資源正在alice
上執行。將
alice
置於 模式 (請參閱圖形 3 「處於待命模式的節點alice
」)。圖 3︰ 處於待命模式的節點alice
#按一下
› 。資源admin_addr
已移轉至bob
。
移轉時,您應該會看見不斷向虛擬 IP 位址進行 ping 的流程。這表示叢集設定與浮動 IP 正常運作。使用 C
可取消 Ctrl–ping 指令。
8.2 使用 ha-cluster-preflight-check 指令進行測試 #
指令 ha-cluster-preflight-check
會對叢集執行標準化測試。它會觸發叢集故障,並驗證組態以找出問題。在生產環境中使用叢集之前,建議先使用此指令來確定一切符合預期。
該指令支援以下檢查:
環境檢查
-e
/--env-check
: 此項測試將會檢查:主機名稱是否可解析?
是否已啟用並啟動時間服務?
是否為目前節點設定了監視程式?
是否已啟用
firewalld
服務,並開啟了叢集相關的連接埠?
叢集狀態檢查
-c
/--cluster-check
: 檢查叢集的不同狀態和服務。此項測試將會檢查:叢集服務 (Pacemaker/Corosync) 是否已啟用並正在執行?
是否已啟用 STONITH?它還會檢查是否已設定並啟動 STONITH 相關的資源。如果您設定了 SBD,SBD 服務是否已啟動?
叢集是否具有最低節點數?顯示目前 DC 節點,以及處於線上、離線和未清理狀態的節點。
是否存在已啟動、已停止或有故障的資源?
電腦分裂檢查
--split-brain-iptables
: 透過阻擋 Corosync 連接埠來模擬電腦分裂情境。檢查是否可如預期般圍籬區隔一個節點。停止 SBD、Corosync 和 Pacemaker 的精靈
-kill-sbd
/-kill-corosync
/-kill-pacemakerd
: 執行此類測試後,可在/var/lib/ha-cluster-preflight-check
中找到報告。該報告包括測試案例說明、動作記錄,以及對可能結果的說明。圍籬區隔節點檢查
--fence-node
:圍籬區隔從指令行傳遞的特定節點。
例如,若要測試環境,請執行:
root #
crm_mon -1
Stack: corosync Current DC: alice (version ...) - partition with quorum Last updated: Fri Mar 03 14:40:21 2020 Last change: Fri Mar 03 14:35:07 2020 by root via cibadmin on alice 2 nodes configured 1 resource configured Online: [ alice bob ] Active resources: stonith-sbd (stonith:external/sbd): Started aliceroot #
ha-cluster-preflight-check
-e [2020/03/20 14:40:45]INFO: Checking hostname resolvable [Pass] [2020/03/20 14:40:45]INFO: Checking time service [Fail] INFO: chronyd.service is available WARNING: chronyd.service is disabled WARNING: chronyd.service is not active [2020/03/20 14:40:45]INFO: Checking watchdog [Pass] [2020/03/20 14:40:45]INFO: Checking firewall [Fail] INFO: firewalld.service is available WARNING: firewalld.service is not active
可以在 /var/log/ha-cluster-preflight-check.log
中檢查結果。
9 更多資訊 #
https://documentation.suse.com/sle-ha/15-SP2 上提供了更多有關此產品的文件。如需其他組態和管理任務,請參閱全面的 《管理指南》。
10 法律聲明 #
版權所有 © 2006– 2023 SUSE LLC 和貢獻者。保留所有權利。
根據 GNU 自由文件授權 (GNU Free Documentation License) 1.2 版或 1.3 版 (自由選擇),使用者可以複製、散佈與/或修改本文件;「恆常章節」為此著作權聲明與授權。「GNU 自由文件授權」一節中包含 1.2 版授權的一份副本。
如需 SUSE 商標,請參閱 http://www.suse.com/company/legal/。所有其他協力廠商的商標所有權分屬其各自的公司。®、™ 等商標符號表示 SUSE 及其關係企業的商標。星號 (*) 表示協力廠商的商標。
本手冊中所有資訊在編輯時,都已全力注意各項細節。但這不保證百分之百的正確性。因此,SUSE LLC 及其附屬公司、作者或譯者都不需對任何錯誤或造成的結果負責。
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:
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.
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.
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
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.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
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.
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.
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.
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.
Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
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 http://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.