Le présent document explique comment configurer une grappe très basique de deux noeuds à l'aide des scripts d'amorçage fournis par le paquetage ha-cluster-bootstrap
. Ce processus inclut la configuration d'une adresse IP virtuelle en tant que ressource de grappe et l'utilisation d'un détecteur de vues de grappe divergentes (SBD pour Split Brain Detector) sur un stockage partagé en tant que mécanisme d'isolation.
Les procédures décrites dans le présent document permettent de configurer une grappe de base à deux noeuds présentant les caractéristiques suivantes :
Deux noeuds: alice
(adresse IP: 192.168.1.1
) et bob
(adresse IP : 192.168.1.2
), connectés entre eux via le réseau.
Une adresse IP virtuelle flottante (192.168.2.1
), qui permet aux clients de se connecter au service quel que soit le noeud physique sur lequel il s'exécute.
Un périphérique de stockage partagé, utilisé comme mécanisme d'isolation SBD afin d'éviter les scénarios de vues de grappe divergentes.
Un système de basculement des ressources d'un noeud vers l'autre en cas de défaillance de l'hôte actif (configuration active/passive).
Une fois la grappe configurée au moyen des scripts d'amorçage, nous la surveillerons à l'aide de l'interface graphique Hawk (HA Web Konsole), l'un des outils de gestion de grappe fournis avec SUSE® Linux Enterprise High Availability Extension. Pour tester le bon fonctionnement du basculement des ressources, nous mettrons simplement l'un des noeuds en mode veille et vérifierons si l'adresse IP virtuelle est migrée vers l'autre noeud.
La grappe à deux noeuds peut être utilisée à des fins de test ou comme une configuration de grappe minimale que vous pouvez étendre par la suite. Avant d'utiliser la grappe dans un environnement de production, modifiez-la en fonction de vos besoins.
Cette section décrit la configuration système minimale requise pour le scénario présenté dans la Section 1, « Scénario d'utilisation ». Si vous souhaitez adapter la grappe en vue de l'utiliser dans un environnement de production, consultez la liste complète des recommandations ainsi que la configuration système requises du Book “Administration Guide”, Chapter 2 “System Requirements and Recommendations”.
Deux serveurs exécutant les logiciels spécifiés à la Configuration logicielle requise.
Ces serveurs peuvent être des machines virtuelles ou sans système d'exploitation. Ils ne nécessitent pas une configuration matérielle identique (mémoire, espace disque, etc.), mais doivent avoir la même architecture. Les grappes multi plate-forme ne sont pas prises en charge.
Au moins deux médias de communication TCP/IP par noeud de grappe. L'équipement réseau doit prendre en charge le moyen de communication que vous souhaitez utiliser pour les communications au sein de la grappe, à savoir la multidiffusion ou la monodiffusion. Les médias de communication doivent prendre en charge un débit de données de 100 Mbit/s ou plus. La prise en charge d'une grappe requiert au moins deux chemins de communication redondants. Cette configuration peut être obtenue via :
La liaison de périphériques réseau (option à privilégier).
Un deuxième canal de communication dans Corosync.
La tolérance aux pannes réseau sur la couche d'infrastructure (par exemple, hyperviseur).
Pour éviter un scénario de « vues de grappe divergentes », les grappes ont besoin d'un mécanisme d'isolation de noeud. Dans un scénario de vues de grappe divergentes, les noeuds de grappe sont divisés en deux groupes ou plus qui ne se connaissent pas (en raison d'une défaillance matérielle ou logicielle, ou d'une interruption de la connexion réseau). Un mécanisme d'isolation isole le noeud en question (généralement en le réinitialisant ou en le mettant hors tension). Ce processus est également appelé STONITH (« Shoot the other node in the head »). Un mécanisme d'isolation de noeud peut être un dispositif physique (un bouton marche/arrêt) ou un mécanisme de type SBD (STONITH par disque) associé à un système de surveillance (watchdog). L'utilisation d'un SBD nécessite un stockage partagé.
Les logiciels ci-dessous doivent être installés sur tous les noeuds de la grappe.
SUSE® Linux Enterprise Server 12 SP5 (avec toutes les mises à jour en ligne disponibles)
SUSE Linux Enterprise High Availability Extension 12 SP5 (avec toutes les mises à jour en ligne disponibles)
Les noeuds de la grappe doivent se synchroniser avec un serveur NTP situé en dehors de la grappe. Pour plus d'informations, consultez le site https://documentation.suse.com/sles-12/html/SLES-all/cha-netz-xntp.html.
Si les noeuds ne sont pas synchronisés, il se peut que la grappe ne fonctionne pas correctement. En outre, les fichiers journaux et les rapports de grappe sont très difficiles à analyser en l'absence de synchronisation. Si vous utilisez les scripts d'amorçage, le système vous avertira si un service NTP n'est pas encore configuré.
Utilisez des adresses IP statiques.
Répertoriez tous les noeuds de la grappe, avec leur nom d'hôte complet et leur nom d'hôte abrégé, dans le fichier /etc/hosts
. Il est essentiel que les membres de la grappe puissent se trouver sur la base de leurs noms. Si les noms ne sont pas disponibles, la communication interne au sein de la grappe ne fonctionnera pas.
Tous les noeuds de la grappe doivent pouvoir accéder les uns aux autres via le protocole SSH. Des outils tels que les rapports CRM
(pour le dépannage) et l' de Hawk2 requièrent un accès SSH sans mot de passe entre les noeuds, faute de quoi ils peuvent uniquement collecter des données du noeud actif.
Si vous utilisez les scripts d'amorçage pour configurer la grappe, les clés SSH sont automatiquement créées et copiées.
Toutes les commandes du paquetage ha-cluster-bootstrap exécutent des scripts d'amorçage qui ne nécessitent qu'un minimum de temps et d'effort manuel.
Le script ha-cluster-init
permet de définir les paramètres de base nécessaires pour la communication au sein de la grappe. À ce moment-là, vous disposez d'une grappe opérationnelle comportant un seul noeud.
Le script ha-cluster-join
vous permet d'ajouter des noeuds à votre grappe.
Le script ha-cluster-remove
vous permet de supprimer des noeuds de votre grappe.
Tous les scripts d'amorçage consignent des données dans le fichier/var/log/ha-cluster-bootstrap.log
. Pour toute information à propos du processus d'amorçage, consultez ce fichier. Toutes les options définies au cours du processus d'amorçage peuvent être modifiées ultérieurement à l'aide du module de grappe YaST. Pour plus d'informations, reportez-vous au Book “Administration Guide”, Chapter 3 “Installing the High Availability Extension”, Section 3.1 “Manual Installation”.
Chaque script est fourni avec une page de manuel présentant les différentes fonctions, les options du script et les fichiers que ce dernier peut créer et modifier.
Le script d'amorçage ha-cluster-init
vérifie et configure les composants suivants :
Si un service NTP n'a pas été configuré pour se lancer au moment du démarrage, un message s'affiche.
Le script crée les clés SSH nécessaires pour que les noeuds de la grappe puissent accéder les uns aux autres sans mot de passe.
Le script configure Csync2 de manière à répliquer les fichiers de configuration sur tous les noeuds d'une grappe.
Le script configure le système de communication de la grappe.
Le script vérifie si un système de surveillance existe et vous demande si vous souhaitez configurer un SBD comme mécanisme d'isolation de noeud.
Le script vous demande si vous souhaitez configurer une adresse IP virtuelle pour l'administration de la grappe à l'aide de Hawk2.
Le script ouvre les ports du pare-feu qui sont nécessaires pour les communications de grappe.
Le script définit un nom pour la grappe. Par défaut, il s'agit de clusterNUMÉRO
. Ce nom est facultatif et principalement utile pour les grappes géographiques. En règle générale, le nom de la grappe reflète l'emplacement et facilite la distinction d'un site à l'intérieur d'une grappe géographique.
Les paquetages nécessaires pour configurer et gérer une grappe avec High Availability Extension sont inclus dans le modèle d'installation Haute disponibilité
. Ce modèle est disponible uniquement si SUSE Linux Enterprise High Availability Extension a été installé en tant qu'extension de SUSE® Linux Enterprise Server.
Pour plus d'informations sur l'installation des extensions, reportez-vous au SUSE Linux Enterprise 12 SP5 Deployment Guide (Guide de déploiement de SUSE Linux Enterprise 12 SP5) : https://documentation.suse.com/sles-12/html/SLES-all/cha-add-ons.html.
Si le modèle n'est pas encore installé, installez-le avec la commande zypper install -t pattern ha_sles
. Vous pouvez également installer le modèle avec YaST. Procédez de la façon suivante :
Démarrez YaST et sélectionnez
› .Cliquez sur l'onglet
et activez le modèle dans la liste des modèles.Cliquez sur
pour démarrer l'installation des paquetages.Installez le modèle Haute disponibilité sur toutes les machines qui feront partie de votre grappe.
Pour procéder à une installation automatisée de SUSE Linux Enterprise Server 12 SP5 et de SUSE Linux Enterprise High Availability Extension 12 SP5, utilisez AutoYaST pour cloner des noeuds existants. Pour plus d'informations, reportez-vous au Book “Administration Guide”, Chapter 3 “Installing the High Availability Extension”, Section 3.2 “Mass Installation and Deployment with AutoYaST”.
Enregistrez les machines sur le SUSE Customer Center. Pour plus d'informations, reportez-vous au site https://documentation.suse.com/sles-12/html/SLES-all/cha-update-offline.html#sec-update-registersystem.
Si vous disposez d'un stockage partagé, tel qu'un SAN (Storage Area Network), vous pouvez l'utiliser pour éviter des scénarios de vues de grappe divergentes en configurant un SBD en tant que mécanisme d'isolation de noeud. Un SBD utilise la prise en charge de la surveillance et l'agent de ressource STONITH external/sbd
.
Lors de la configuration du premier noeud à l'aide du script ha-cluster-init
, vous pouvez décider d'utiliser ou non un SBD. Si vous choisissez d'utiliser un SBD, vous devez spécifier le chemin d'accès au périphérique de stockage partagé. Par défaut, le script ha-cluster-init
crée automatiquement une petite partition sur le périphérique à utiliser pour le SBD.
Pour pouvoir utiliser un SBD, les conditions suivantes doivent être remplies :
Le chemin d'accès au périphérique de stockage partagé doit être persistant et cohérent sur tous les noeuds de la grappe. Utilisez des noms de périphérique stables, tels que /dev/disk/by-id/dm-uuid-part1-mpath-abcedf12345
.
Le périphérique SBD ne doit pas utiliser cLVM2 ou la technologie RAID basée sur un hôte, ni résider sur une instance DRBD*.
Pour plus d'informations sur la configuration d'un stockage partagé, reportez-vous au manuel Storage Administration Guide for SUSE Linux Enterprise Server 12 SP5 (Guide d'administration du stockage de SUSE Linux Enterprise Server 12 SP5) : https://documentation.suse.com/sles-12/html/SLES-all/stor-admin.html.
Dans SUSE Linux Enterprise Server (SLES), la prise en charge de la surveillance dans le kernel est activée par défaut : SLES inclut plusieurs modules de kernel qui fournissent des pilotes de surveillance propres au matériel. High Availability Extension utilise le daemon SBD comme composant logiciel pour « alimenter » le système de surveillance.
La procédure suivante utilise la surveillance softdog
.
Le pilote softdog part du principe qu'au moins un processeur est toujours en cours d'exécution. Si tous les processeurs sont bloqués, le code dans le pilote softdog qui devrait redémarrer le système ne sera jamais exécuté. En revanche, les systèmes de surveillance matérielle continuent à travailler même si tous les processeurs sont bloqués.
Avant d'utiliser la grappe dans un environnement de production, il est vivement recommandé de remplacer le module softdog
par le module matériel respectif qui correspond le mieux à votre matériel.
Toutefois, si aucun système de surveillance ne correspond à votre matériel, softdog
peut être utilisé en tant que module de surveillance de kernel.
Créez un stockage partagé persistant comme décrit dans la Section 5.1, « Configuration requise pour le SBD ».
Activez la surveillance logicielle :
root #
echo
softdog > /etc/modules-load.d/watchdog.confroot #
systemctl
restart systemd-modules-load
Vérifiez si le module de surveillance logicielle est chargé correctement :
root #
lsmod
| egrep "(wd|dog)" softdog 16384 1
Sur bob
, initialisez la partition du détecteur de vues de grappe divergentes (SBD) :
root #
sbd
-d /dev/SBDDEVICE create
Démarrez le SBD pour écouter sur le périphérique SBD :
root #
sbd
-d /dev/SBDDEVICE watch
Sur alice
, envoyez un message de test :
root #
sbd
-d /dev/SBDDEVICE message bob test
Sur bob
, vérifiez l'état à l'aide de la commande systemctl
et vous devriez voir le message reçu :
root #
systemctl
status sbd [...] info: Received command test from alice on disk SBDDEVICE
Arrêtez de surveiller le périphérique SBD sur bob
à l'aide de la commande ci-dessous :
root #
systemctl
stop sbd
Il est vivement recommandé de tester le bon fonctionnement du mécanisme d'isolation SBD en cas de vues de grappe divergentes. Ce type de test peut être exécuté en bloquant la communication de grappe Corosync.
Configurez le premier noeud à l'aide du script ha-cluster-init
. Cette opération ne nécessite qu'un minimum de temps et d'effort manuel.
alice
) à l'aide du script ha-cluster-init
#
Connectez-vous en tant qu'utilisateur root
à la machine physique ou virtuelle que vous souhaitez utiliser comme noeud de grappe.
Démarrez le script d'amorçage en exécutant la commande suivante :
root #
ha-cluster-init
--name CLUSTERNAME
Remplacez la marque de réservation NOM_GRAPPE par un nom pertinent, comme l'emplacement géographique de votre grappe (par exemple, amsterdam
). Cela est particulièrement utile si vous souhaitez créer une grappe géographique ultérieurement, car cela simplifie l'identification d'un site. Si vous exécutez la commande sans l'option --name
, le nom par défaut est hacluster
.
Si vous avez besoin de la monodiffusion plutôt que la multidiffusion (par défaut) pour la communication de votre grappe, utilisez l'option -u
. Après l'installation, recherchez la valeur udpu
dans le fichier /etc/corosync/corosync.conf
. Si ha-cluster-init
détecte un noeud en cours d'exécution sur Amazon Web Services (AWS), le script utilisera la monodiffusion automatiquement par défaut pour la communication de grappe.
Le script vérifie la configuration NTP et la présence d'un service de surveillance matérielle. Il génère les clés SSH publiques et privées utilisées pour l'accès SSH et la synchronisation Csync2, et démarre les services respectifs.
Configurez la couche de communication de grappe (Corosync) :
Spécifiez une adresse réseau pour la liaison. Par défaut, le script propose l'adresse réseau eth0
. Vous pouvez également spécifier une autre adresse réseau, par exemple bond0
.
Spécifiez une adresse de multidiffusion. Le script propose une adresse aléatoire que vous pouvez utiliser comme adresse par défaut. Bien entendu, votre réseau spécifique doit prendre en charge cette adresse de multidiffusion.
Spécifiez un port de multidiffusion. Par défaut, le script propose le port 5405
.
Enfin, le script démarre le service Pacemaker pour mettre en ligne la grappe à un noeud et activer Hawk2. L'URL à utiliser pour Hawk2 apparaît à l'écran.
Configurez le SBD comme mécanisme d'isolation de noeud :
Spécifiez y
pour confirmer que vous souhaitez utiliser le SBD.
Entrez un chemin d'accès persistant à la partition du périphérique de bloc que vous souhaitez utiliser pour le SBD (voir Section 5, « Utilisation d'un SBD comme mécanisme d'isolation »). Le chemin doit être cohérent sur tous les noeuds de la grappe.
Configurez une adresse IP virtuelle pour l'administration de la grappe avec Hawk2. (Nous utiliserons cette ressource IP virtuelle ultérieurement pour tester le bon fonctionnement du basculement).
Spécifiez y
pour confirmer que vous souhaitez configurer une adresse IP virtuelle.
Spécifiez une adresse IP inutilisée que vous souhaitez employer comme adresse IP d'administration pour Hawk2 : 192.168.2.1
.
Au lieu de vous connecter à un noeud de grappe individuel avec Hawk2, vous pouvez vous connecter à l'adresse IP virtuelle.
Vous disposez maintenant d'une grappe opérationnelle comportant un seul noeud. Pour visualiser son état, procédez comme suit :
Sur une machine, démarrez un navigateur Web et assurez-vous que JavaScript et les cookies sont activés.
Spécifiez comme URL l'adresse IP ou le nom d'hôte d'un noeud de grappe qui exécute le service Web Hawk. Vous pouvez également spécifier l'adresse IP virtuelle que vous avez configurée à l'Étape 6 de la Procédure 2, « configuration du premier noeud (alice
) à l'aide du script ha-cluster-init
» :
https://HAWKSERVER:7630/
Si un avertissement de certificat s'affiche la première fois que vous tentez d'accéder à l'URL, un certificat auto-signé est utilisé. Par défaut, les certificats auto-signés ne sont pas considérés comme fiables.
Demandez à votre opérateur de grappe de vous fournir les informations relatives au certificat afin de vérifier ce dernier.
Pour continuer, vous pouvez ajouter une exception dans le navigateur afin d'ignorer l'avertissement.
Dans l'écran de connexion de Hawk2, spécifiez le hacluster
, mot de passe : Linux
).
Remplacez dès que possible le mot de passe par défaut par un mot de passe sécurisé :
root #
passwd
hacluster
Cliquez sur
. Une fois que vous êtes connecté, l'interface Web Hawk2 affiche l'écran d'état par défaut, lequel permet de visualiser rapidement l'état actuel de la grappe :
Si vous disposez d'une grappe à un noeud opérationnelle, ajoutez-y le deuxième noeud à l'aide du script d'amorçage ha-cluster-join
, comme décrit dans la Procédure 4. Le script nécessite uniquement un accès à un noeud de grappe existant et procède automatiquement à la configuration de base sur la machine actuelle. Pour plus d'informations, reportez-vous à la page de manuel relative au script ha-cluster-join
.
Les scripts d'amorçage prennent en charge la modification de la configuration spécifique à une grappe à deux noeuds, par exemple, SBD et Corosync.
bob
) à l'aide du script ha-cluster-join
#
Connectez-vous en tant qu'utilisateur root
à la machine physique ou virtuelle censée rejoindre la grappe.
Démarrez le script d'amorçage en exécutant la commande suivante :
root #
ha-cluster-join
Si un service NTP n'a pas été configuré pour se lancer au moment du démarrage, un message s'affiche. Le script vérifie également la présence d'un périphérique de surveillance matérielle (ce type de périphérique est important si vous souhaitez configurer un SBD) et vous avertit si aucun périphérique de ce type n'est présent.
Si vous décidez de continuer, le système vous invite à spécifier l'adresse IP d'un noeud existant. Spécifiez l'adresse IP du premier noeud (alice
, 192.168.1.1
).
Si vous n'avez pas déjà configuré un accès SSH sans mot de passe entre les deux machines, le système vous invite également à spécifier le mot de passe root
du noeud existant.
Une fois connecté au noeud spécifié, le script copie la configuration Corosync, configure SSH et Csync2, et met en ligne la machine actuelle en tant que nouveau noeud de grappe. Par ailleurs, le script démarre le service requis pour Hawk2.
Vérifiez l'état de la grappe dans Hawk2. Dans Figure 2, « État de la grappe à deux noeuds »).
› , vous devriez normalement voir deux noeuds présentant un état vert (voir
La Procédure 5, « test du basculement des ressources » est un test simple qui permet de vérifier si la grappe déplace l'adresse IP virtuelle vers l'autre noeud lorsque le noeud qui exécute actuellement la ressource est mis en mode veille
.
Toutefois, un test réaliste implique des cas et des scénarios d'utilisation spécifiques, notamment la vérification du bon fonctionnement du mécanisme d'isolation destiné à éviter une situation de vues de grappe divergentes. Si vous n'avez pas configuré votre mécanisme d'isolation correctement, la grappe ne fonctionnera pas convenablement.
Avant d'utiliser la grappe dans un environnement de production, testez-la scrupuleusement en fonction de l'utilisation que vous comptez en faire.
Ouvrez un terminal et exécutez une commande ping sur l'adresse 192.168.2.1
, autrement dit votre adresse IP virtuelle :
root #
ping
192.168.2.1
Connectez-vous à votre grappe, comme décrit dans la Procédure 3, « connexion à l'interface Web Hawk2 ».
Dans Hawk2 adresse_admin
). Supposons que la ressource s'exécute sur alice
.
Mettez alice
en mode (voir Figure 3, « Noeud alice
en mode veille »).
alice
en mode veille #
Cliquez sur adresse_admin
a été migrée vers bob
.
Pendant la migration, vous devriez normalement voir un flux continu de requêtes ping envoyées à l'adresse IP virtuelle. Cela montre que la configuration de grappe et l'adresse IP flottante fonctionnent correctement. Annulez la commande ping
en appuyant sur Ctrl–C.
Le site https://documentation.suse.com/sle-ha-12 fournit davantage d'informations à propos de ce produit. La documentation inclut également un manuel complet Administration Guide for SUSE Linux Enterprise High Availability Extension (Guide d'administration de SUSE Linux Enterprise High Availability Extension). Pour en savoir plus sur les tâches de configuration et d'administration, consultez ce manuel.
Copyright © 2006– 2024 SUSE LLC et contributeurs. Tous droits réservés.
Il est autorisé de copier, distribuer et/ou modifier ce document conformément aux conditions de la licence de documentation libre GNU version 1.2 ou (à votre discrétion) 1.3, avec la section permanente qu'est cette mention de copyright et la licence. Une copie de la version de licence 1.2 est incluse dans la section intitulée « Licence de documentation libre GNU ».
Pour les marques commerciales SUSE, consultez le site Web http://www.suse.com/company/legal/. Toutes les autres marques de fabricants tiers sont la propriété de leur détenteur respectif. Les symboles de marque commerciale (®,™, etc.) indiquent des marques commerciales de SUSE et de ses filiales. Des astérisques (*) désignent des marques commerciales de fabricants tiers.
Toutes les informations de cet ouvrage ont été regroupées avec le plus grand soin. Cela ne garantit cependant pas sa complète exactitude. Ni SUSE LLC, ni les sociétés affiliées, ni les auteurs, ni les traducteurs ne peuvent être tenus responsables des erreurs possibles ou des conséquences qu'elles peuvent entraîner.
This appendix contains the GNU Free Documentation License version 1.2.
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 noncommercially. 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 in order 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 noncommercially, 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:
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.
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 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.
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.