Guide pratique de la mobilité IPv6 avec Linux

Version française du Linux Mobile IPv6 HOWTO

Adaptation française: François Romieu

Relecture de la version française: Camille Huot

Préparation de la publication de la v.f.: Jean-Philippe Guérard

Version : 1.2.fr.1.0

2004-10-16

Historique des versions
Version 1.2.fr.1.02004-10-16FR, CH, JPG
Traduction française
Version 1.22004-04-20LKS
Mise à jour des liens. Le document est à nouveau placé sous GFDL. Updated links. Changed lisence back to GFDL
Version 1.12004-02-04LKS
Ajout des sections « Traversée de plusieurs réseaux distants » et « Retour au réseau domestique ». Dépoussiérage et restructuration. Added "Travelling through several foregin LAN's" and "Returning home". Some cleanup and restructuring.
Version 1.02003-12-02TMM
Relecture par le LDP. Reviewed by LDP
Version 0.5.22003-11-26LKS
Embellissements. Contribution de John Levon levon [chez] movementarian.org. A lot of cleanup. Thanks to John Levon levon [at] movementarian.org
Version 0.5.12003-11-22LKS
Le document passe de la licence GFDL à la licence OPL en raison de problèmes liés à la GFDL. Changed the license from GFDL to OPL due to some GFDL problems.
Version 0.52003-11-18LKS
Conversion du document en XML DocBook. Reprises. Converted to XML Docbook. Some cleanup.
Version 0.42002-11-07LKS
Corrections diverses et mise à jour. Contribution de Henrik Petander petander (chez) tcs hut fi. Fixed some errors + update. Thanks to Henrik Petander petander (at) tcs hut fi.
Version 0.3.12003-11-03LKS
Prise en compte de la version 1.0 de MIPL (noyau 2.4.22). Updated to MIPL relase 1.0 (kernel 2.4.22).
Version 0.32003-08-05LKS
Version initiale. Initial release.

Résumé

Ce document décrit les logiciels et les procédures à appliquer pour mettre en œuvre la mobilité IPv6 avec Linux.


Table des matières

1. Introduction
1.1. Qu'est-ce que la mobilité IP ?
1.2. Le besoin de la mobilité IP
1.3. Fonctionnement de la mobilité IPv6
2. IPv6
3. La mobilité IPv6 avec Linux
3.1. Mise à niveau du noyau
3.2. Programmes utilitaires
3.3. Fichier spécial pour MIPv6
3.4. Démarrage automatique
4. Environnement de test
4.1. Scénario de test
4.2. Description des étapes de la configuration
5. Quelques tests
5.1. Pré-requis
5.2. Détection des déplacements
5.3. ping6
5.4. La table de routage IP du noyau
5.5. Traversée de plusieurs réseaux distants
5.6. Retour au réseau domestique
5.7. Test en grandeur nature — transition en douceur
6. FAQ
7. Références
8. Droits de reproduction, remerciements et autres
8.1. Droits de reproduction et licence
8.2. Élaboration de ce document
8.3. Commentaires et corrections
8.4. Remerciements
A. GNU Free Documentation License
1. PREAMBLE
2. APPLICABILITY AND DEFINITIONS
3. VERBATIM COPYING
4. COPYING IN QUANTITY
5. MODIFICATIONS
6. COMBINING DOCUMENTS
7. COLLECTIONS OF DOCUMENTS
8. AGGREGATION WITH INDEPENDENT WORKS
9. TRANSLATION
10. TERMINATION
11. FUTURE REVISIONS OF THIS LICENSE
12. ADDENDUM: How to use this License for your documents

1. Introduction

Ce document décrit les logiciels et les procédures à appliquer pour mettre en œuvre la mobilité IPv6 avec Linux. Le document de travail « Mobility Support in IPv6 » précise le pourquoi et le comment de la mobilité IP comme indiqué ci-dessous.

1.1. Qu'est-ce que la mobilité IP ?

 

Chaque station mobile est toujours identifiée par l'adresse (mère) de son point d'attache originel indépendamment de son point de raccordement courant à Internet. Lorsqu'une station mobile est séparée de son point d'attache, elle négocie une adresse temporaire de réexpédition (ou adresse temporaire primaire) qui permet de connaître sa localisation en cours. Les paquets IPv6 à destination de l'adresse mère d'une station mobile sont routés de façon transparente vers son adresse temporaire primaire par l'agent d'attache (HA, Home Agent) de la station mobile. Le protocole permet aux nœuds IPv6 de mémoriser la correspondance entre l'adresse mère d'une station mobile et son adresse temporaire primaire afin qu'ils puissent envoyer directement les paquets destinés à la station mobile grâce à son adresse temporaire primaire.

 
 -- draft-ietf-mipv6-24, pages 1 et 2.

1.2. Le besoin de la mobilité IP

 

En l'absence de prise en charge de la mobilité dans IPv6, les paquets destinés à une station mobile (terminal ou routeur) ne sont pas en mesure de joindre la station lorsqu'elle est séparée de son lien d'origine (i. e. du lien dans lequel son préfixe de réseau IPv6 est en service) puisque le routage repose sur le préfixe de réseau de l'adresse de destination d'un paquet. Pour continuer à communiquer malgré ses déplacements, une station mobile pourrait changer d'adresse à chaque fois qu'elle change de lien. Elle serait alors incapable de maintenir les connexions de niveau transport et au delà lorsqu'elle se déplace. La prise en charge de la mobilité dans IPv6 est d'autant plus importante que les ordinateurs mobiles seront sûrement responsables d'une partie conséquente du trafic au cours de la vie d'IPv6.

 
 -- draft-ietf-mipv6-24, page 6.

Se reporter au document de travail « Mobility Support in IPv6 » (Mobilité IPv6) pour davantage de détails.

1.3. Fonctionnement de la mobilité IPv6

Mobilité IP

Mobilité IP

  1. La station mobile (Mobile Node — MN) atteint un réseau distant et obtient une nouvelle adresse temporaire.

  2. La station mobile effectue une mise à jour d'association avec son agent d'attache (HA) qui enregistre la nouvelle adresse temporaire primaire. L'agent d'attache accuse réception de l'association avec la station mobile.

  3. Un correspondant (CN) souhaite joindre la station mobile (MN). L'agent d'attache intercepte les paquets à destination de la station mobile.

  4. L'agent d'attache établit un tunnel pour les paquets issus du correspondant (CN) à destination de la station mobile au moyen de l'adresse temporaire de la station mobile.

  5. Lorsque la station mobile répond au correspondant (CN), elle peut employer son adresse temporaire primaire et communiquer directement avec le correspondant (CN). On parle alors de routage optimisé. La station mobile peut également faire transiter ses paquets par le tunnel qui la relie à son agent d'attache.

Se reporter au schéma « Mobile IP » pour une explication.

2. IPv6

IP version 6 (IPv6) constitue une évolution du protocole Internet destinée à succéder à la version 4 (IPv4) [RFC791]. Les différences entre IPv4 et IPv6 se répartissent pour l'essentiel dans les catégories suivantes :

  • extension de l'espace d'adressage ;

  • simplification des en-têtes ;

  • amélioration de la prise en charge des extensions et des options ;

  • capacité à marquer les flux ;

  • authentification et confidentialité.

Un minimum de connaissance du fonctionnement de l'autoconfiguration avec IPv6 est requis pour comprendre la mobilité dans IPv6 (MIPv6). Le document [RFC2462] contient des information relatives à l'autoconfiguration des adresses IPv6.

Le groupe de travail IPv6 de l'IETF permet de se renseigner sur IPv6 de façon générale.

3. La mobilité IPv6 avec Linux

Il existe actuellement deux souches logicielles de la mobilité IPv6 pour Linux. L'université anglaise de Lancaster a réalisé la première souche historique (http://www.cs-ipv6.lancs.ac.uk/MobileIP/). Le noyau géré le plus récent est le 2.1.90 et la mise en œuvre est compatible avec la version 5 du document de travail relatif à la mobilité IPv6 de l'IETF (ce document en est actuellement à la version 24). Le code source et le site web n'ont pas été mis à jour depuis 1998. L'ensemble est donc considéré obsolète.

L'autre souche, réalisée dans le cadre du projet MIPL de l'université de technologie d'Helsinki, est davantage à jour. Le noyau le plus récent pris en charge est le 2.4.22 et des greffons de code existent pour la série des noyaux 2.6 (se reporter à la FAQ). Le site http://www.mobile-ipv6.org/ contient des documents, le logiciel et une archive des discussions par courrier électronique.

3.1. Mise à niveau du noyau

La souche MIPL de MIPv6 demande une mise à niveau du noyau. Elle modifie la pile IPv6 de ce dernier. Une recompilation est donc nécessaire. La procédure est correctement documentée mais un rapide aperçu des étapes est donné ci-dessous.

Remarque importante : il n'est plus nécessaire de compiler deux noyaux différents (un pour la station mobile et l'autre pour la station d'accueil). Il suffit de compiler la prise en charge de la station mobile et celle de la station d'accueil dans le même noyau. Il n'est cependant pas possible de faire fonctionner le noyau à la fois pour une station mobile et pour une station d'accueil : le mode retenu dépend du module chargé.

  1. On commence par télécharger le dernier code source de MIPv6 pour Linux à l'adresse http://www.mobile-ipv6.org/. La dernière version à jour est mipv6-1.0-v2.4.22. Les quatre derniers chiffres indiquent le noyau Linux auquel le greffon doit être appliqué.

    # cd /usr/local/src
    # wget http://www.mobile-ipv6.org/download/mipv6-1.0-v2.4.22.tar.gz
    # tar zxfv mipv6-1.0-v2.4.22.tar.gz
    
  2. On télécharge et on décompresse ensuite le noyau Linux correspondant depuis le site ftp.kernel.org :

    # cd /usr/src
    # wget ftp://ftp.kernel.org/pub/linux/kernel/v2.4/linux-2.4.22.tar.bz2
    # tar jxvf linux-2.4.22.tar.bz2
    # ln -s linux-2.4.22 linux
    # cd linux
    
  3. Application du greffon MIPv6 :

    # patch -p1 --dry-run < /usr/local/src/mipv6-1.0-v2.4.22/mipv6-1.0-v2.4.22.patch
    

    L'option --dry-run vérifie que le greffon est applicable. Si un fragment est rejeté, il vaut mieux ne pas continuer. Si tout se déroule correctement, on peut effectivement appliquer les modifications :

    # patch -p1 < /usr/local/src/mipv6-1.0-v2.4.22/mipv6-1.0-v2.4.22.patch
    
  4. L'arborescence du noyau Linux est maintenant prête à être configurée. On exécute la commande make *config de son choix. Les options de configuration de MIPv6 se trouvent sous le menu « Networking Options ». Les options ci-dessous devraient apparaître dans le fichier « .config » :

    CONFIG_EXPERIMENTAL=y
    CONFIG_SYSCTL=y
    CONFIG_PROC_FS=y
    CONFIG_MODULES=y
    CONFIG_NET=y
    CONFIG_NETFILTER=y
    CONFIG_UNIX=y
    CONFIG_INET=y
    CONFIG_IPV6=m
    CONFIG_IPV6_SUBTREES=y
    CONFIG_IPV6_IPV6_TUNNEL=m
    CONFIG_IPV6_MOBILITY=m
    CONFIG_IPV6_MOBILITY_MN=m
    CONFIG_IPV6_MOBILITY_HA=m
    

    Comme le développement de MIPL n'est pas encore achevé, il peut être utile d'activer :

    CONFIG_IPV6_MOBILITY_DEBUG=y
    

    Les messages de mise au point permettent de comprendre plus facilement ce qui s'est produit quand une erreur a lieu. Ils sont également très utiles lorsqu'on rapporte une anomalie.

    On peut exécuter le script chkconf_kernel.sh inclus dans le paquet MIPL pour vérifier que toutes les options adéquates sont positionnées.

  5. On procède ensuite à la compilation et à l'installation du noyau.

    Suggestion : afin de distinguer plus facilement les noyaux qu'on recompile soi-même, il suffit par exemple de positionner la variable « EXTRAVERSION » dans le fichier /usr/src/linux/Makefile à la valeur « -MIPv6-1 ».

Le guide pratique du noyau Linux fournit des instructions détaillées pour la modification, la compilation et l'installation d'un nouveau noyau.

3.2. Programmes utilitaires

L'utilitaire mipdiag, les fichiers de configuration et les scripts d'initialisation doivent être installés pour que le module fonctionne correctement :

# cd /usr/local/src/mipv6-1.0-v2.4.22
# ./configure
# make && make install

3.3. Fichier spécial pour MIPv6

Le module MIPv6 nécessite également un nouveau fichier spécial. La commande suivante en crée un :

# mknod /dev/mipv6_dev c 0xf9 0

3.4. Démarrage automatique

  1. Red Hat :

    Les fichiers de commandes de démarrage se trouvent dans le répertoire /etc/init.d/ et sont référencés au moyen de liens symboliques suivant le niveau de fonctionnement (/etc/rcX.d/). On active MIPv6 au démarrage avec la commande :

    # chkconfig --add mobile-ip6
    

    On le désactive de façon similaire :

    # chkconfig --del mobile-ip6
    
  2. Debian :

    Si on a la chance d'opérer avec une distribution Debian, la commande suivante positionnera tous les liens nécessaires :

    # update-rc.d -n mobile-ip6 start 75 3 4 5 . stop 05 1 2 6 .
    
  3. Slackware :

    Les scripts de démarrage et de changement de niveau de fonctionnement se trouvent tous dans le répertoire /etc/rc.d. « configure » n'examine pas « /etc/rc.d ». On ajoute donc INIT_SLACK="/etc/rc.d" et INIT_SLACK à INITDIRS dans le script « configure » (il suffit de rechercher INITDIR dans ce fichier). La commande suivante permet alors d'achever le travail :

    # echo '/etc/rc.d/mobile-ip6 start' >> /etc/rc.d/rc.local
    

    Si le fichier Makefile n'est pas modifié, le script mobile-ip6 est installé à la racine et il faut alors le déplacer manuellement dans le répertoire /etc/rc.d.

4. Environnement de test

On dispose à présent d'un noyau opérationnel modifié pour MIPL, d'utilitaires et de scripts de démarrage automatique. Si une anomalie se produit, il est conseillé de reprendre les sections précédentes très attentivement.

4.1. Scénario de test

Les adresses employées pour le scénario de test sont de type site-local. On peut également employer des adresses globales mais il faut noter que les adresses locales ne fonctionneront pas. L'environnement de test comprend quatre stations comme indiqué par le schéma du test de mobilité IPv6.

  1. HA — station d'accueil : la station d'accueil se trouve dans le réseau domestique à l'adresse fec0:106:2700::2. Elle comprend une interface sans fil.

  2. MN — station mobile : l'adresse de la station mobile dans le réseau domestique est fec0:106:2700::4. Quand la station mobile se déplace, elle engendre une nouvelle « adresse temporaire primaire ».

  3. R — routeur : il s'agit du routeur entre le réseau domestique et Internet. Il inclut une interface réseau sans fil d'adresse fec0:106:2700::1 et une interface filaire d'adresse fec0:106:2300::2.

  4. AR — routeur d'accès : le lien réseau entre AR et R constitue l'« internet » du banc de test. Dans le cadre du test, il se limite à deux adresses IP aux extrémités d'un câble croisé mais il peut s'agir de n'importe quel type de réseau. Le routeur d'accès est équipé de deux interfaces. Une interface filaire se trouve à l'adresse fec0:106:2300::1 tandis qu'une interface sans fil occupe l'adresse fec0:106:1100::1.

Environnement de test de mobilité IPv6

Environnement de test de mobilité IPv6

4.2. Description des étapes de la configuration

4.2.1. Mise en place d'un réseau IPv6 fonctionnel

Avant de procéder au test de la mobilité IPv6, un réseau IPv6 fonctionnel est nécessaire. Toutes les stations doivent être en mesure de s'atteindre les unes les autres au moyen de l'utilitaire ping. Le point précédent est fondamental. Ainsi, lorsqu'AR n'est pas capable de joindre HA, il n'y a pas de mise à jour de raccordement.

De brèves instructions pour élaborer un réseau IPv6 sont présentées ci-dessous. L'excellent Guide pratique IPv6 pour Linux de Peter Bieringer contient davantage d'informations pour effectuer cette tâche.

Le chiffrement a été désactivé pour simplifier la présentation mais il est conseillé de toujours y avoir recours dans le cas de réseaux sans fil.

Il convient de noter que des réseaux sans fil distincts relèvent de ESSID différents.

  1. MN : la station mobile est équipée d'une interface sans fil. Le renvoi doit être inhibé mais il faut activer autoconf et ra :

    # iwconfig eth0 mode ad-hoc essid homenet enc off
    # ifconfig eth0 inet6 add fec0:10:2700::4/64
    # echo "0" > /proc/sys/net/ipv6/conf/eth0/forwarding
    # echo "1" > /proc/sys/net/ipv6/conf/eth0/autoconf
    # echo "1" > /proc/sys/net/ipv6/conf/eth0/accept_ra
    # echo "1" > /proc/sys/net/ipv6/conf/eth0/accept_redirects
    # /etc/init.d/mobile-ip6 start
    
  2. HA : la station d'accueil comprend une interface sans fil. Le renvoi doit être activé puisque des trames reçues depuis l'interface physique sont transmises via l'interface virtuelle de tunnel. Remarque : une route par défaut est nécessaire sans quoi le HA aura des difficultés pour contacter la station mobile MN dans le réseau distant. Une solution consiste à employer HA en tant que routeur du réseau domestique.

    # iwconfig eth0 mode ad-hoc essid homenet enc off
    # ifconfig eth0 inet6 add fec0:106:2700::2/64
    # echo "1" > /proc/sys/net/ipv6/conf/eth0/forwarding
    # echo "0" > /proc/sys/net/ipv6/conf/eth0/autoconf
    # echo "0" > /proc/sys/net/ipv6/conf/eth0/accept_ra
    # echo "0" > /proc/sys/net/ipv6/conf/eth0/accept_redirects
    # ip route add ::/0 via fec0:106:2700::1
    # /etc/init.d/mobile-ip6 start
    
  3. R : le routeur domestique comprend deux interfaces, une sans fil et une filaire. Le renvoi doit être activé dans le routeur domestique.

    # ifconfig eth0 inet6 add fec0:106:2300::2/64
    # iwconfig eth1 mode ad-hoc essid homenet enc off
    # ifconfig eth1 inet6 add fec0:106:2700::1/64
    # echo "1" > /proc/sys/net/ipv6/conf/all/forwarding
    # echo "0" > /proc/sys/net/ipv6/conf/all/autoconf
    # echo "0" > /proc/sys/net/ipv6/conf/all/accept_ra
    # echo "0" > /proc/sys/net/ipv6/conf/all/accept_redirects
    # ip route add fec0:106:1100::/64 via fec0:106:2300::1
    
  4. AR : le routeur d'accès qui appartient à un réseau distant comprend également deux interfaces (filaire et sans fil). Là encore, le renvoi des trames doit être activé.

    # ifconfig eth0 inet6 add fec0:106:2300::1/64
    # iwconfig eth1 mode ad-hoc essid visitnet enc off
    # ifconfig eth1 inet6 add fec0:106:1100::1/64
    # echo "1" > /proc/sys/net/ipv6/conf/all/forwarding
    # echo "0" > /proc/sys/net/ipv6/conf/all/autoconf
    # echo "0" > /proc/sys/net/ipv6/conf/all/accept_ra
    # echo "0" > /proc/sys/net/ipv6/conf/all/accept_redirects
    # ip route add fec0:106:2700::/64 via fec0:106:2300::2
    

L'utilitaire sysctl évite d'avoir à accéder directement au système de fichiers sous proc.

Remarque : l'environnement de test s'appuie sur des routes statiques. Tous les hôtes doivent à présent pouvoir se contacter avec ping.

4.2.2. Configuration de la mobilité IPv6

La dernière étape de la configuration est relative à MIPL et s'effectue dans le fichier network-mip6.conf. Avec une distribution de type Debian ou Slackware, ce fichier se trouve dans le répertoire /etc tandis qu'avec une distribution RedHat, il figure dans le répertoire /etc/sysconfig. Le contenu du fichier est en principe assez parlant.

  1. HA : le fichier de configuration doit contenir les informations ci-dessous :

    # cat /etc/network-mip6.conf
    
    # Fichier de configuration de la station d'accueil
    FUNCTIONALITY=ha
    DEBUGLEVEL=1
    MIN_TUNNEL_NR=1
    MAX_TUNNEL_NR=5
    TUNNEL_SITELOCAL=yes
    
  2. MN : le fichier de configuration doit contenir les informations ci-dessous :

    # cat /etc/network-mip6.conf
    
    # Fichier de configuration de la station mobile
    FUNCTIONALITY=mn
    DEBUGLEVEL=1
    TUNNEL_SITELOCAL=yes
    MIN_TUNNEL_NR=1
    MAX_TUNNEL_NR=3
    HOMEDEV=mip6mnha1
    HOMEADDRESS=fec0:106:2700::4/64  # adresse d'origine de la station mobile
    HOMEAGENT=fec0:106:2700::2/64    # adresse de la station d'accueil
    
  3. On active ensuite la mobilité IP :

    # /etc/init.d/mobile-ip6 start
    Starting Mobile IPv6 : OK
    

On vérifie que le HA a démarré correctement au moyen de la commande ifconfig. Si le tunnel ip6tnl1 apparaît, la mobilité IPv6 est active :

# ifconfig
eth1     Link encap:Ethernet  HWaddr 00:02:2D:2D:DE:79
         inet6 addr: fec0:106:2700::2/64 Scope:Site
         inet6 addr: fe80::202:2dff:fe2d:de79/64 Scope:Link
         UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
         RX packets:618 errors:6 dropped:6 overruns:0 frame:6
         TX packets:1485 errors:22 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:100
         RX bytes:87914 (85.8 KiB)  TX bytes:252596 (246.6 KiB)
         Interrupt:3 Base address:0x100

ip6tnl1  Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 1
         UP POINTOPOINT RUNNING NOARP  MTU:1460  Metric:1
         RX packets:6 errors:0 dropped:0 overruns:0 frame:0
         TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:0
         RX bytes:576 (576.0 b)  TX bytes:624 (624.0 b)

ip6tnl2  Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 2
         UP RUNNING NOARP  MTU:1460  Metric:1
         RX packets:0 errors:0 dropped:0 overruns:0 frame:0
         TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:0
         RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)

lo       Link encap:Local Loopback
         inet addr:127.0.0.1  Mask:255.0.0.0
         inet6 addr: ::1/128 Scope:Host
         UP LOOPBACK RUNNING  MTU:16436  Metric:1
         RX packets:8 errors:0 dropped:0 overruns:0 frame:0
         TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:0
         RX bytes:560 (560.0 b)  TX bytes:560 (560.0 b)
1

Le tunnel est actif et prêt à établir des connexions.

2

Un autre tunnel actif.

Les modules mipv6 du noyau doivent également être chargés (MN) :

# lsmod
Module                  Size  Used by    Not tainted
mip6_mn                59888   0  (unused)
ipv6_tunnel            11448   1  [mip6_mn]
mip6_base              40728   0  [mip6_mn]
ipv6                  179764  -1  [mip6_mn ipv6_tunnel mip6_base]
...

4.2.3. Configuration de radvd au niveau du routeur d'accès (AR)

Quand la station mobile arrive dans un nouveau réseau, elle configure une adresse lien-local avant de poursuivre. [RFC2462] (IPv6 Stateless Address Autoconfiguration) décrit la phase suivante :

 

La phase suivante de l'autoconfiguration implique d'obtenir une annonce de routeur ou bien de déterminer qu'aucun routeur n'est disponible. Si des routeurs se manifestent, ils vont envoyer des annonces qui précisent le type d'autoconfiguration que le système hôte doit effectuer. En l'absence de routeur, une autoconfiguration à état connu est nécessaire.

Les routeurs émettent périodiquement des annonces mais le délai d'attente entre annonces est en général bien supérieur à la durée qu'une station ne souhaite consacrer à son autoconfiguration. Pour recevoir rapidement une annonce, une station émet une ou plusieurs sollicitations à destination du groupe de multidiffusion (multicast) de l'ensemble des routeurs.

 
 -- page 8

radvd intervient à ce moment là.

[RFC2462] fournit davantage de renseignements au sujet de l'autoconfiguration sans état des adresses IPv6.

On configure radvd au niveau de l'interface sans fil d'AR. Le fichier radvd.conf doit contenir :

# cat /etc/radvd.conf
interface eth1
{
      AdvSendAdvert on;
      AdvIntervalOpt on;

      MinRtrAdvInterval 3;
      MaxRtrAdvInterval 10;
      AdvHomeAgentFlag off;

      prefix fec0:106:1100::/64
      {
          AdvOnLink on;
          AdvAutonomous on;
          AdvRouterAddr on;
      };
};

On démarre alors radvd :

# /etc/init.d/radvd start

On peut à présent employer radvdump pour examiner les messages réellement envoyés par radvd :

# radvdump
Router advertisement from fe80::202:2dff:fe54:d1b2 (hoplimit 255)
Received by interface eth1
      # Note: {Min,Max}RtrAdvInterval cannot be obtained with radvdump
      AdvCurHopLimit: 64
      AdvManagedFlag: off
      AdvOtherConfigFlag: off
      AdvHomeAgentFlag: off
      AdvReachableTime: 0
      AdvRetransTimer: 0
      Prefix fec0:106:1100::/64
              AdvValidLifetime: 2592000
              AdvPreferredLifetime: 604800
              AdvOnLink: on
              AdvAutonomous: on
              AdvRouterAddr: off
      AdvSourceLLAddress: 00 02 2D 54 D1 B2

Remarque : le recours à radvd pour HA conjugué à l'activation d'« autoconf » (via proc) conduit à l'apparition d'une adresse IPv6 (superflue) générée automatiquement au niveau de MN en plus de son adresse statique.

4.2.4. Configuration de radvd au niveau de la station d'accueil

Pour que la station mobile MN sache quand elle est de retour dans son réseau domestique, la station d'accueil HA doit également envoyer des annonces de routeurs. On active donc également RADVD au niveau de la station d'accueil. Le fichier /etc/radvd.conf doit contenir :

# cat /etc/radvd.conf
interface eth0
{
   AdvSendAdvert on;
   MaxRtrAdvInterval 3;
   MinRtrAdvInterval 1;
   AdvIntervalOpt off;
   AdvHomeAgentFlag on;
   HomeAgentLifetime 10000;
   HomeAgentPreference 20;
   AdvHomeAgentInfo on;
   prefix fec0:106:2700::2/64
   {
     AdvRouterAddr on;
     AdvOnLink on;
     AdvAutonomous on;
     AdvPreferredLifetime 10000;
     AdvValidLifetime 12000;
   };
};

De même que précédemment, radvdump permet de vérifier que des messages sont périodiquement envoyés par radvd :

# radvdump
Router advertisement from fe80::202:2dff:fe54:d11e (hoplimit 255)
Received by interface eth0
    # Note: {Min,Max}RtrAdvInterval cannot be obtained with radvdump
    AdvCurHopLimit: 64
    AdvManagedFlag: off
    AdvOtherConfigFlag: off
    AdvHomeAgentFlag: on
    AdvReachableTime: 0
    AdvRetransTimer: 0
    Prefix fec0:106:2700::2/64
            AdvValidLifetime: 12000
            AdvPreferredLifetime: 10000
            AdvOnLink: on
            AdvAutonomous: on
            AdvRouterAddr: on
    AdvSourceLLAddress: 00 02 2D 54 D1 1E
    AdvHomeAgentInfo:
            HomeAgentPreference: 20
            HomeAgentLifetime: 1000
# ifconfig eth0
eth0  Link encap:Ethernet  HWaddr 00:90:7D:F3:03:1A
      inet6 addr: fec0:106:2700:0:290:7dff:fef3:31a/64 Scope:Site 1
      inet6 addr: fec0:106:2700::4/64 Scope:Site                  2
      inet6 addr: fe80::290:7dff:fef3:31a/64 Scope:Link           3
      UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
      RX packets:513 errors:89 dropped:89 overruns:0 frame:85
      TX packets:140 errors:41 dropped:0 overruns:0 carrier:0
      collisions:0 txqueuelen:100
      RX bytes:56084 (54.7 Kb)  TX bytes:19212 (18.7 Kb)
      Interrupt:3 Base address:0x100
1

Une nouvelle adresse autogénérée (superflue). Comme autoconf est activé par le positionnement de /proc/sys/net/ipv6/conf/eth0/autoconf à 1, la station mobile MN génère une nouvelle adresse avec le préfixe de la station d'accueil HA et sa propre adresse MAC. L'auteur ne connaît pas de méthode pour éviter l'apparition d'une telle adresse.

2

L'adresse statique IPv6 d'origine.

3

L'adresse lien-local créée au démarrage.

5. Quelques tests

5.1. Pré-requis

Il est nécessaire d'effectuer chaque configuration comme indiqué précédemment. Il est particulièrement important de disposer d'identifiants ESSID différents pour le réseau domestique et pour le réseau d'accueil.

Au démarrage de la mobilité IPv6 sur la station mobile MN, des sollicitations de routeurs en multidiffusion apparaissent :

# tcpdump -i eth0 -vv ip6 or proto ipv6

...
13:32:54.681763 fe80::202:a5ff:fe6f:a08a > ff02::2: icmp6: router solicitation \
(src lladdr: 0:2:a5:6f:a0:8a) (len 16, hlim 255)

13:32:55.681763 fe80::202:a5ff:fe6f:a08a > ff02::2: icmp6: router solicitation \
(src lladdr: 0:2:a5:6f:a0:8a) (len 16, hlim 255)

13:32:57.681765 fe80::202:a5ff:fe6f:a08a > ff02::2: icmp6: router solicitation \
(src lladdr: 0:2:a5:6f:a0:8a) (len 16, hlim 255)
...

5.2. Détection des déplacements

La détection des déplacements repose sur la détection d'indisponibilité des voisins pour décider que le routeur par défaut n'est plus joignable. La station mobile doit alors découvrir un nouveau routeur par défaut, souvent avec un nouveau lien.

Pour voir plus facilement ce qui se passe, l'emploi de trois consoles différentes est suggéré pour les commandes suivantes :

# watch ifconfig eth0
# watch route -A inet6
# tcpdump -i eth0 -vv ip6 or proto ipv6

Pour « migrer » vers un nouveau réseau, on emploie la commande suivante au niveau de la station mobile MN :

# iwconfig eth1 essid visitnet

La station mobile MN appartient alors au nouveau réseau sans fil et comme elle émet des « sollicitations de routeurs » (en multicast), l'AR répond avec son préfixe. La station mobile MN se configure alors avec une nouvelle adresse IPv6 issue du préfixe reçu et de son adresse MAC. ifconfig eth0 permet de voir la nouvelle adresse IPv6 :

# ifconfig eth0
eth0  Link encap:Ethernet  HWaddr 00:90:7D:F3:03:1A
      inet6 addr: fec0:106:1100:0:290:7dff:fef3:31a/64 Scope:Site 1
      inet6 addr: fec0:106:2700:0:290:7dff:fef3:31a/64 Scope:Site 2
      inet6 addr: fec0:106:2700::4/64 Scope:Site                  3
      inet6 addr: fe80::290:7dff:fef3:31a/64 Scope:Link           4
      UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
      RX packets:854 errors:154 dropped:154 overruns:0 frame:148
      TX packets:293 errors:58 dropped:0 overruns:0 carrier:0
      collisions:0 txqueuelen:100
      RX bytes:96536 (94.2 Kb)  TX bytes:44664 (43.6 Kb)
      Interrupt:3 Base address:0x100
1

La nouvelle adresse « distante » obtenue par combinaison du préfixe de l'AR et de l'adresse MAC.

2

L'adresse superflue dans le réseau d'origine (due aux annonces radvd de HA et à l'activation d'autoconf au niveau de MN).

3

L'adresse domestique « d'origine ».

4

L'adresse lien-local établie au démarrage.

À peu près au même moment, la station mobile MN effectue une mise à jour d'association avec la station d'accueil HA. Plusieurs paquets à destination de HA apparaissent dans le terminal. On vérifie que la mise à jour d'association a été envoyée et acquittée au niveau de la station mobile MN :

# mipdiag -s
Mobile IPv6 Statistics
NEncapsulations           : 0
NDecapsulations           : 0
NBindUpdatesRcvd          : 0
NBindAcksRcvd             : 1    1
NBindNAcksRcvd            : 0
NBindRqsRcvd              : 0
NBindUpdatesSent          : 1    2
NBindAcksSent             : 0
NBindNAcksSent            : 0
NBindRqsSent              : 0
NBindUpdatesDropAuth      : 0
NBindUpdatesDropInvalid   : 0
NBindUpdatesDropMisc      : 0
NBindAcksDropAuth         : 0
NBindAcksDropInvalid      : 0
NBindAcksDropMisc         : 0
NBindRqsDropAuth          : 0
NBindRqsDropInvalid       : 0
NBindRqsDropMisc          : 0
1

Réception d'un accusé de réception d'association.

2

Envoi d'une mise à jour d'association.

La commande suivante permet, elle aussi, de vérifier l'association (au niveau de la station mobile MN) :

# mipdiag -l
Mobile IPv6 Binding update list
Recipient CN: fec0:106:2700::2
BINDING home address: fec0:106:2700::4 care-of address: fec0:106:1100:0:290:7dff:fef3:31a
        expires: 936 sequence: 0 state: 1
        delay: 3 max delay 32 callback time: 736

La vérification est également possible, au niveau de la station d'accueil HA, au moyen de l'option d'affichage des statistiques (-s) et de l'option d'affichage du « cache des liaisons » (-c) :

# mipdiag -c
Mobile IPv6 Binding cache
Home Address      Care-of Address                    Lifetime  Type
fec0:106:2700::4  fec0:106:1100:0:290:7dff:fef3:31a  971       2

5.3. ping6

On effectue un ping à destination de l'interface eth1 (fec0:106:1100::1) d'AR depuis la station mobile MN :

# ping6 fec0:106:1100::1
PING fec0:106:1100::1(fec0:106:1100::1) from fec0:106:2700::4 : 56 data bytes
64 bytes from fec0:106:1100::1: icmp_seq=1 ttl=62 time=8.01 ms
64 bytes from fec0:106:1100::1: icmp_seq=2 ttl=62 time=8.02 ms
...

tcpdump affiche les paquets à la volée :

12:13:51.789688 fec0:106:1100:0:202:a5ff:fe6f:a08a > fec0:106:2700::2: \  1
fec0:106:2700::4 > fec0:106:1100::1: icmp6: echo request \ 2
(len 64, hlim 64) (len 104, hlim 255)

12:13:51.797675 fec0:106:2700::2 > fec0:106:1100:0:202:a5ff:fe6f:a08a: \ 3
fec0:106:1100::1 > fec0:106:2700::4: icmp6: echo reply \
(len 64, hlim 62) (len 104, hlim 253)
1

Le paquet transite de la station mobile MN à HA avec la nouvelle adresse IPv6 de la station mobile.

2

Le paquet transite ensuite de HA à AR.

3

AR répond à HA et renvoie les paquets au moyen du tunnel avec MN.

Les statistiques ont été mises à jour (au niveau de la station mobile MN) :

# mipdiag -s
Mobile IPv6 Statistics
NEncapsulations           : 56
NDecapsulations           : 25
...

5.4. La table de routage IP du noyau

Entre autres choses intéressantes, MIPv6 repositionne la route par défaut vers le tunnel. La nouvelle route devient :

# route -A inet6
Kernel IPv6 routing table
Destination      Next Hop       Flags Metric Ref    Use Iface
::/0             ::             UD    64     0        0 ip6tnl1
....

On peut ajouter la nouvelle route manuellement si elle n'apparaît pas automatiquement :

# ip route ::/0 via dev ip6tnl

5.5. Traversée de plusieurs réseaux distants

La traversée de plusieurs réseaux n'est pas différente de la migration vers un réseau. Il faut juste garder à l'esprit qu'une nouvelle adresse est créée pour chaque réseau visité.

Une station mobile MN se déplace entre plusieurs réseaux distants.

  1. MN va d'abord dans « visitnet » comme vu précédemment.

  2. MN passe ensuite de « visitnet » à « visitnet2 ».

  3. À son entrée dans « visitnet2 », la station mobile MN crée une nouvelle adresse IPv6 et effectue une mise à jour d'association supplémentaire avec la station d'accueil HA.

  4. MN retourne alors dans son réseau domestique (se reporter à la partie suivante).

Le routeur d'accès AR du réseau « visitnet2 » est configuré de la même façon que le routeur d'accès du réseau « visitnet » à ceci près qu'il emploie l'adresse fec0:106:1000::/64 au lieu de l'adresse fec0:106:1100::/64.

Pour que la station mobile passe du réseau « visitnet » au réseau « visitnet2 », on émet depuis la station mobile MN la commande :

# iwconfig eth0 essid visitnet2

La station mobile MN se reconfigure alors dans le nouveau réseau :

# ifconfig eth0
eth1  Link encap:Ethernet  HWaddr 00:90:7D:F3:03:1A
      inet6 addr: fec0:106:1000:0:290:7dff:fef3:31a/64 Scope:Site 1
      inet6 addr: fec0:106:1100:0:290:7dff:fef3:31a/64 Scope:Site
      inet6 addr: fec0:106:2700:0:290:7dff:fef3:31a/64 Scope:Site
      inet6 addr: fec0:106:2700::4/64 Scope:Site
      inet6 addr: fe80::290:7dff:fef3:31a/64 Scope:Link
      UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
      RX packets:1073 errors:212 dropped:212 overruns:0 frame:204
      TX packets:371 errors:72 dropped:0 overruns:0 carrier:0
      collisions:0 txqueuelen:100
      RX bytes:120340 (117.5 Kb)  TX bytes:56912 (55.5 Kb)
      Interrupt:3 Base address:0x100
1

La nouvelle adresse obtenue par autoconfiguration dans le réseau « visitnet2 ».

Remarque : il peut s'avérer nécessaire de redémarrer la mobilité IPv6 au niveau de la station mobile MN quand cette dernière arrive dans un nouveau réseau.

# /etc/init.d/mobile-ip6 restart
Stopping Mobile IPv6: OK
Starting Mobile IPv6: OK

La station mobile MN effectue alors une mise à jour d'association avec la station d'accueil HA. On note au passage la nouvelle adresse « temporaire » (care-of) :

# mipdiag -l
Mobile IPv6 Binding update list
Recipient CN: fec0:106:2700::2
BINDING home address: fec0:106:2700::4 care-of address: fec0:106:1000:0:290:7dff:fef3:31a
expires: 973 sequence: 14 state: 1
delay: 3 max delay 32 callback time: 773

Le « cache des liaisons » de la station d'accueil HA a été mis à jour :

# mipdiag -c
Mobile IPv6 Binding cache
Home Address      Care-of Address                    Lifetime  Type
fec0:106:2700::4  fec0:106:1000:0:290:7dff:fef3:31a  943       2

5.6. Retour au réseau domestique

La commande suivante suffit pour ramener la station mobile MN dans son réseau domestique :

# iwconfig eth0 essid homenet

La station mobile MN sait qu'elle est de retour car la station d'accueil HA émet des messages radvd dans lesquels le bit HA (AdvHomeAgentFlag, voir Section 4.2.4, « Configuration de radvd au niveau de la station d'accueil ») est positionné.

On constate que la station mobile MN « est de retour » car le cache des informations de liaison de la station d'accueil HA est purgé (il est vide) :

Mobile IPv6 Binding cache
Home Address      Care-of Address                     Lifetime  Type

5.7. Test en grandeur nature — transition en douceur

Pour bien réaliser le fonctionnement de la mobilité IP, on se sert de GnomeMeeting (se reporter au schéma avec GnomeMeeting) et on initie une conférence. Remarque : il faut employer la dernière version de GnomeMeeting pour avoir accès à la prise en charge d'IPv6. On effectue ensuite un « déplacement » et on constate alors une transition discrète.

GnomeMeeting

GnomeMeeting dans un contexte IPv6 pour tester la mobilité entre réseaux sans fil.

6. FAQ

  1. Q : pourquoi faut-il créer un fichier /dev/mipv6_dev ?

    R : le fichier de périphérique est essentiellement employé par le programme mipdiag pour modifier le paramétrage du noyau au moyen d'ioctl. mknod crée un fichier spécial adapté au module mobile-ip6.

  2. Q : les noyaux 2.6.x sont-ils supportés ?

    R : voici la réponse d'Henrik Petander dans la liste de diffusion MIPL :

    « Voici une revue rapide de l'état de MIPL pour la famille des noyaux 2.6 : »

    « L'infrastructure noyau demandée par la mobilité IPv6 a été mise au point en coopération avec le projet USAGI. L'optimisation du routage, ainsi que la gestion des tunnels et de la politique de routage sont opérationnels. »

    « Le travail se concentre à présent sur le programme résidant en espace utilisateur qui prend en charge la signalisation MIPv6 et contrôle les opérations du noyau. Les utilitaires avancent également à un rythme correct. La logique protocolaire est toutefois absente : les utilisateurs n'ont donc rien à tester pour l'instant. Un prototype opérationnel et testé devrait être disponible d'ici la fin du mois de mars. »

  3. Q : MIPL est-il compatible avec IPSec ?

    R : la série des noyaux 2.4.x ne gère pas IPSec. MIPL pour Linux va gérer IPSec dès sa sortie. Il sera possible d'employer une souche IPSec fournie par un tiers.

  4. Q : comment contrôler la nature du routage entre une station mobile MN et un correspondant CN (recours au tunnel avec la station d'attache HA ou bien communication directe après association et acquittement) ?

    R : on utilise le paramètre suivant :

    /proc/sys/conf/net/ipv6/mobility/accept_return_routability

    Pour désactiver le renvoi d'informations de routage et son optimisation, on positionne le paramètre à 0 :

    # echo 0 > /proc/sys/..../accept_return_routability

    La station mobile MN ne communiquera alors plus avec le correspondant CN qu'au travers du tunnel.

  5. Q : des réseaux sans fil distincts peuvent-ils avoir des ESSID et des clefs WEP différentes ?

    R : oui, mais le changement doit être effectué manuellement lors de l'entrée dans un nouveau réseau. La souche MIPL de MIPv6 ne sait pas procéder à la transition automatiquement.

  6. Q : lorsque la station mobile MN a traversé plusieurs réseaux et qu'elle retourne dans son réseau d'attache, son interface supporte encore les adresses IPv6 générées automatiquement dans tous les réseaux visités. Peut-on supprimer ces adresses ?

    R : à défaut d'une méthode de suppression automatique des dites adresses, il est possible de les éliminer manuellement :

    # ifconfig eth0 inet6 del <ipv6-address>

  7. Q : la station B comprend deux interfaces sur des réseaux distincts. B ne répond pas aux sollicitations ICMP émises depuis la station A alors qu'A sait où trouver les réseaux de B. Pourquoi ?

    R : la station B ignore comment joindre la station A. Il faut donc ajouter une route :

    # ip route add fec0:106:2700::/64 via fec0:106:2300::1

    ou

    # route -A inet6 add fec0:106:2700::/64 gw fec0:106:2300::1 dev eth0

  8. Q : comment mettre en place une passerelle par défaut pour IPv6 ?

    R : on emploie la commande « route » habituelle :

    # route -A inet6 add default gw <ipv6-host>

    ou sa variante moderne « ip » :

    # ip route ::/0 via <ipv6-host>

  9. Q : pourquoi les stations sollicitent-elles les routeurs au moyen d'une émission en multidiffusion au lieu d'une émission avec un adressage anycast ?

    R : la station attend une réponse de chaque routeur et non d'un seul. Elle obtient ainsi tous les paramètres et peut choisir le « meilleur » routeur par défaut.

  10. Q : pourquoi la station mobile ne remarque-t-elle pas qu'elle s'est déplacée ?

    R : la station s'imagine que son dernier routeur est toujours joignable. Ceci peut être dû à des durées de vie très élevées au niveau des annonces de routeur. Il faut vérifier la configuration du programme responsable de l'envoi des annonces depuis le routeur. Si le programme gère les intervalles d'annonces de routage, ces derniers peuvent aider la station mobile MN à détecter les déplacements. Se reporter à la page de manuel de radvd.conf pour les détails.

7. Références

  1. Mobilité IPv6 pour Linux http://www.mipl.mediapoli.com/

  2. Groupe de travail pour la mobilité IP (IETF) http://www.ietf.org/html.charters/mobileip-charter.html

  3. Document de travail (draft) de la mobilité IPv6 http://www.ietf.org/rfc/rfc3775.txt

  4. Groupe de travail IPv6 (IETF) http://www.ietf.org/html.charters/ipv6-charter.html

  5. RFC2460 Internet Protocol, Version 6 (IPv6) Specification http://abcdrfc.free.fr/rfc-vf/rfc2460.html

  6. RFC2461 Neighbor Discovery for IP Version 6 (IPv6) http://www.ietf.org/rfc/rfc2461.txt

  7. RFC2462 IPv6 Stateless Address Autoconfiguration http://www.ietf.org/rfc/rfc2462.txt

  8. Guide pratique IPv6 de Peter Bieringer http://mirrors.deepspace6.net/Linux+IPv6-HOWTO-fr/

  9. État du support IPv6 des applications communicantes http://www.deepspace6.net/docs/ipv6_status_page_apps.html

  10. Guide pratique du noyau Linux http://www.freenix.fr/unix/linux/HOWTO/Kernel-HOWTO.html

8. Droits de reproduction, remerciements et autres

8.1. Droits de reproduction et licence

Copyright © 2003, 2004 Lars Strand.

Copyright © 2004 François Romieu, Camille Huot et Jean-Philippe Guérard pour la version française.

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

Vous êtes autorisé à copier, distribuer et modifier ce document selon les termes de la Licence de documentation libre GNU [GFDL], version 1.3 ou toute version postérieure publiée par le Free Software Foundation ; sans section invariante, ni texte de première ou de quatrième de couverture. Une copie de cette licence est incluse dans la section « GNU Free Documentation License ».

8.2. Élaboration de ce document

Ce document a été écrit à l'origine en LaTeX avec Emacs. La version HTML a été élaborée avec latex2html avant que la conversion en DocBook XML n'ait lieu. La traduction a été réalisée avec un éditeur de texte.

La dernière version originale de ce document se trouve à l'adresse :

HTML : http://www.tldp.org/HOWTO/Mobile-IPv6-HOWTO/

La dernière version française de ce document est disponible à l'adresse :

HTML : http://www.traduc.org/docs/howto/lecture/Mobile-IPv6-HOWTO.html

8.3. Commentaires et corrections

Les suggestions, les corrections et les améliorations sont appréciées. Les contributeurs sont les bienvenus. Les polémiques ne sont pas nécessaires.

L'auteur peut être joint par courrier électronique en anglais à l'adresse .

Page d'accueil : http://www.gnist.org/~lars.

N'hésitez pas à faire parvenir tout commentaire relatif à la version française de ce document à en précisant son titre, sa date et sa version.

8.4. Remerciements

Ce document a été rédigé dans le cadre de l'Interoperable Networks for Secure Communications (INSC task 6)

Merci à Andreas Hafslund (andreha [chez] unik.no) pour son soutien. Merci également à UniK (University Graduate Center) http://www.unik.no et au FFI (Norwegian Defence Research Establishment) http://www.ffi.mil.no pour leur soutien en matériel.

Merci également aux autres auteurs de guides pratiques que j'ai référencés :

Le guide pratique IPv6 pour Linux par Peter Bieringer.

A. GNU Free Documentation License

Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

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

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

3. VERBATIM COPYING

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.

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

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

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

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

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

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

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

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

12. ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

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.