Linux Mobile IPv6 HOWTO

2006-17-04

Revision History
Revision 1.5b2006-17-04LKS
Note! To be completed. Updated to MIPL release 2.0.1 (kernel 2.6). Major update.
Revision 1.22004-04-20LKS
Updated links. Changed lisence back to GFDL
Revision 1.12004-02-04LKS
Added "Travelling through several foregin LAN's" and "Returning home". Some cleanup and restructuring.
Revision 1.02003-12-02TMM
Reviewed by LDP
Revision 0.5.22003-11-26LKS
A lot of cleanup. Thanks to John Levon levon [at] movementarian.org
Revision 0.5.12003-11-22LKS
Changed the license from GFDL to OPL due to some GFDL problems.
Revision 0.52003-11-18LKS
Converted to XML Docbook. Some cleanup.
Revision 0.42002-11-07LKS
Fixed some errors + update. Thanks to Henrik Petander petander (at) tcs hut fi.
Revision 0.3.12003-11-03LKS
Updated to MIPL relase 1.0 (kernel 2.4.22).
Revision 0.32003-08-05LKS
Initial release.

Abstract

This document describes the software and procedures to set up and use mobile IPv6 for Linux.


Table of Contents

Introduction
What is Mobile IP?
Why Mobile IP?
How does it work?
IPv6
IPSec
What is IPSec?
AH and ESP?
Transport modes
Mobile IPv6 for Linux
Patching the kernel
Userspace tools
Automatic startup
Test bed
Testcase
Step-by-step configuration
Starting MIPv6
Doing some tests
Pre-test
Movement detection
ping6
Kernel IP routing table
Travelling through several foregin LAN's
Returning home
Real life testing - smooth handover
FAQ
Useful Resources
Copyright, acknowledgments and miscellaneous
Copyright and License
How this document was produced
Feedback
Acknowledgments
A. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
ADDENDUM: How to use this License for your documents

Introduction

This document describes the software and procedures to set up and use mobile IPv6 for Linux. The RFC3775: "Mobility Support in IPv6" answers the what and why of mobile IP:

What is Mobile IP?

Each mobile node is always identified by its home address, regardless of its current point of attachment to the Internet. While situated away from its home, a mobile node is also associated with a care-of address, which provides information about the mobile node's current location. IPv6 packets addressed to a mobile node's home address are transparently routed to its care-of address. The protocol enables IPv6 nodes to cache the binding of a mobile node's home address with its care-of address, and to then send any packets destined for the mobile node directly to it at this care-of address.” --- RFC3775, page 1.

Why Mobile IP?

Without specific support for mobility in IPv6 [RFC2460], packets destined to a mobile node would not be able to reach it while the mobile node is away from its home link. In order to continue communication in spite of its movement, a mobile node could change its IP address each time it moves to a new link, but the mobile node would then not be able to maintain transport and higher-layer connections when it changes location. Mobility support in IPv6 is particularly important, as mobile computers are likely to account for a majority or at least a substantial fraction of the population of the Internet during the lifetime of IPv6.” --- RFC3775, page 5.

For all the details, read RFC3775: "Mobility Support in IPv6"

How does it work?

Mobile IP

Mobile IP

  1. The Mobile Node (MN) travels to a foreign network and gets a new care-of-address.

  2. The MN performs a binding update to its Home Agent (HA) (the new care-of-address gets registered at HA). HA sends a binding acknowledgement to MN.

  3. A Correspondent Node (CN) wants to contact the MN. The HA intercepts packets destined to the MN.

  4. The HA then tunnels all packets to the MN from the CN using MN's care-of-address.

  5. When the MN answers the CN, it may use its current care-of-address (and perform a binding to the CN) and communicate with the CN directly (“route optimization”) or it can tunnel all its packets through the HA.

See figure "Mobile IP" for an explanation.

IPv6

IP version 6 (IPv6) is a new version of the Internet Protocol, designed as the successor to IP version 4 (IPv4) [RFC791]. The changes from IPv4 to IPv6 fall primarily into the following categories:

  • Expanded addressing capabilities

  • Header format simplification

  • Improved support for extensions and options

  • Flow labeling capability

  • Authentication and privacy capabilities

You should have basic knowledge of IPv6 stateless auto-configuring to fully understand how “mobile IPv6” (MIPv6) works. You can read up on IPv6 Stateless Address Autoconfiguration in [RFC2462].

For more information on IPv6 in general, visit the IETF's IPv6 Working Group.

IPSec

What is IPSec?

To be completed.

AH and ESP?

To be completed.

Transport modes

To be completed.

Mobile IPv6 for Linux

The Helsinki University of Technology MIPL project are behind the only up-to-date Mobile IPv6 implementation for Linux. The latest kernel supported is 2.6.15 and is compatible with RFC3775. Visit http://www.mobile-ipv6.org/ for papers, software or to browse the mail archive.

The implementation includes both a kernel modification (a kernel patch) and user space software.

Patching the kernel

Caution

Patching and recompiling the kernel can easily render your system unbootable. If you've never done this before, I strongly suggest you take a look at the Linux Kernel HOWTO.

The MIPL MIPv6 implementation requires a kernel patch. The implementation modifies the IPv6 kernel stack, so a kernel recompile is necessary. The installation process is well documented, but I will give a brief step-by-step howto.

Both the Mobile Node (MN) and Home Agent (HA) needs their kernel patched, but they do not require all the same kernel options. Details below.

  1. Download the latest Linux MIPv6 source code from http://mobile-ipv6.org/. The latest release today is: mipv6-2.0-v2.6.15. The last four numbers corresponds to the Linux kernel the patch should be applied to:

          # cd /usr/local/src
          # wget http://mobile-ipv6.org/download/mipv6-2.0-v2.6.15.tar.gz
          # tar zxfv mipv6-1.0-v2.4.22.tar.gz
        
  2. Download and unpack the correspondent Linux kernel version from ftp.kernel.org:

          # cd /usr/src
          # wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.15.tar.bz2
          # tar jxvf linux-2.6.15.tar.bz2
          # ln -s linux-2.5.16 linux
          # cd linux
         
  3. Apply the MIPv6 patch:

          # zcat /usr/local/src/mipv6-2.0.1-linux-2.6.15.patch.gz | patch -p1 --dry-run
        

    Warning

    If you get any “failed chunks” (errors/warnings), do not proceed. Go carefully over the above step once more.

    The --dry-run option checks that the patch will apply correctly. If everything went fine do:

          # zcat /usr/local/src/mipv6-2.0.1-linux-2.6.15.patch.gz | patch -p1  
        
  4. Now your kernel tree is ready for configuration. Run your favorite make *config. The MIPv6 options are under “Networking Options”. Depending on whether the node should act as a Mobile Node or Home Agent or whether you want to use IPSec, the options in the .config file differs:

    Make sure these options are present:

         CONFIG_EXPERIMENTAL=y
         CONFIG_SYSVIPC=y
         CONFIG_PROC_FS=y
         CONFIG_NET=y
         CONFIG_INET=y 
         CONFIG_IPV6=y
         CONFIG_IPV6_MIP6=y
         CONFIG_XFRM=y
         CONFIG_XFRM_USER=y
         CONFIG_XFRM_ENHANCEMENT=y
         CONFIG_IPV6_TUNNEL=y
         CONFIG_IPV6_ADVANCED_ROUTER=y
         CONFIG_IPV6_MULTIPLE_TABLES=y
         

    The Mobile Node also needs:

         CONFIG_IPV6_SUBTREES=y
         CONFIG_ARPD=y
         

    We want to enable IPSec, so we also need:

         
         CONFIG_INET6_ESP=y
         CONFIG_NET_KEY=y
         CONFIG_NET_KEY_MIGRATE=y
         

    To be sure you have all the correct options, you can run chkconf_kernel.sh, which is a small shell script included in the MIPL tarball. If the script reports any missing options, fix it before you proceed.

        # ./chkconf_kernel.sh  /usr/src/linux
    
        Checking kernel configuration...
        Using /usr/src/linux/.config
        
        All kernel options are as they should.
      
  5. Next you should compile and install your kernel.

    Tip

    Hint: To easily distinguish this kernel from other kernels, you can change the “EXTRAVERSION” variable in the /usr/src/linux/Makefile to for example “-MIPv6-1”.

Read the Linux Kernel HOWTO for detailed instruction on how to patch, compile and install your new kernel.

Userspace tools

The userspace tool mip6d, config files and init scripts must be installed for the module to work correctly:

Download and unpack the user space soure code:

      # cd /usr/local/src/
      # wget http://mobile-ipv6.org/software/download/mipv6-2.0.1.tar.gz
      # tar zxfv mipv6-2.0.1.tar.gz
      # cd mipv6-2.0.1
    

Next, configure, compile and install the source code. Note that we include the --enable-vt option to configure. This option is not required, but will provide us with helpful information. It will enable a virtual terminal listning on localhost port 7777.

      # CPPFLAGS=-I/usr/src/linux/include ./configure --enable-vt
      # make
      # make install
    

Automatic startup

The documentation mention that there is a set of init (startup) scripts available under the extra/ directory. I could only find some example configuration files there. Below is a init script for Debian and Ubuntu. It should be a small effort to make this work on other distributions as well.

All init scripts are located under /etc/init.d and symlinked to correct runlevel (/etc/rcX.d).

Note

Note that this script override and sets the verbosity level to 0.

    #!/bin/sh
    #
    # mip6d:       Starts the Mobile IPv6 Daemon
    #   
    # description: This is a daemon which provide IPv6 Mobility
    #              support (RFC3775). Init script for Debian and Ubuntu.
    #   
    # (C) GNU GPL Lars Strand <lars strand at linpro no>
    #
    
    PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin
    DAEMON=/usr/local/sbin/mip6d
    DESC=mip6d
    CONFIG=/etc/mip6d.conf
    OPTIONS="-d 0 -c $CONFIG"
    
    set -e 
    
    # Check for IPv6 support in kernel
    if [ ! -e /proc/sys/net/ipv6 ]; then
      echo "IPv6 support must be enabled in the kernel for $DESC to work."
      exit 1
    fi
    
    # Can we fint the mip6d?
    if [ ! -x $DAEMON ]; then
        echo "Unable to find $DAEMON."
        exit 1
    fi
    
    chkconfig() {
        if [ ! -e $CONFIG -o ! -s $CONFIG ]; then
            echo ""
            echo "ERROR: $CONFIG does not exist or is empty." 
            echo "       See mip6d.conf(5) for configuration file syntax and example"
            echo "       configuration. $DESC will *not* be started."
            echo ""
            exit 1
        fi
    }

    # See how we were called.
    case "$1" in
        start)
            echo -n "Starting $DESC..."
            chkconfig
            if ! start-stop-daemon --oknodo --start --exec $DAEMON -- $OPTIONS; then
                echo "failed." && exit 1 
            fi
            echo " done."
            ;;
         stop)
            echo -n "Stopping $DESC..."
            start-stop-daemon --oknodo --stop --exec $DAEMON
            echo " done."
            ;;
         restart)
            chkconfig
            echo -n "Restarting $DESC..."
            start-stop-daemon --oknodo --stop --exec $DAEMON
            sleep 1
            start-stop-daemon --oknodo --start --exec $DAEMON -- $OPTIONS
            echo " done."
            ;;
         *)
            echo "Usage: $0 {start|stop|restart}" >&2
            exit 1
            ;;
    esac
    
    exit 0
    

Test bed

Now you should have a working MIPv6 patched kernel, installed userlevel tools and enabled automatic startup at boot. If anything went wrong, go through the above sections carefully.

Testcase

The addresses we are using in our test-bed are site-local. You may as well use global addresses, but do note that link local addresses won't work! Our test-bed consist of four nodes; see figure "Mobile IPv6 testbed".

  1. HA - Home Agent: The HA is located at the home network with address fec0:106:2700::2, with one wireless interface.

  2. MN - Mobile Node: When MN is on the “home network”, it has address fec0:106:2700::4. When MN travels to another network, it generates a new “care-of” address.

  3. R - Router: This is the router from the home network to the internet. It has one wireless interface with address fec0:106:2700::1 and a wired interface with address fec0:106:2300::2.

  4. AR - Access Router: The link between AR and R is our “internet” - but in this testcase only a cross-cable (can be any network). The AR has two interfaces; the wired interface to R has address fec0:106:2300::1, the wireless has address fec0:106:1100::1.

Mobile IPv6 testbed

Mobile IPv6 testbed

Step-by-step configuration

Setting up a fully functional IPv6 network

Before we can start testing mobile IP, we need a fully functional IPv6 network.

Note

All the nodes should be able to ping each other. This is a crucial part. If, for example, AR is not able to ping HA, then there will be no binding update.

I will give a brief instruction to get our network up and running using IPv6. For more info on setting up an IPv6 network, you can read Peter Bieringer's excellent Linux IPv6 HOWTO.

I've turned off wireless encryption for simplicity - NOTE that you should ALWAYS use encryption when dealing with wireless networks!

Also note that the different wireless networks have different ESSIDs!

  1. MN: The Mobile Node has one wireless interface. Forwarding should be turned off, but should accept autoconf and ra's:

              # iwconfig eth0 mode ad-hoc essid homenet enc off
              # ifconfig eth0 inet6 add fec0:106: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
              
  2. HA: The Home Agent has one wireless interface. It should have forwarding turned on because it uses normal routing to deliver packets captured from a physical interface to the virtual tunnel interface. Note: You must add a default route or else HA will have problem contacting the MN on visited LAN's. One possible solution is to use HA as the default router of the home network.

              # 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
              
  3. R: The (home) Router has two interfaces; one wireless and one line. The Router must have forwarding turned on.

              # 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: The Access Router (on a foreign network) also has two interfaces; one wireless and one line. Forwarding must be turned on.

              # 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
              

Instead of modifying proc variables, you can use sysctl.

Note: We are setting static routes on our test-bed. You should now be able to ping all the hosts from every host.

Configuring Mobile IPv6

When you issue make install, neither init script nor configuration file is installed. Example configuration files are found under the extra/ directory under the source code. You may also consult mip6d.conf(5) man page. The file should be pretty self-explanatory.

  1. HA: The HA config file should contain these settings:

             # Mobile IPv6 configuration file: Home Agent
             #
             # filename: /etc/mip6d.conf         
             
             NodeConfig HA;
             
             ## If set to > 0, will not detach from tty
             DebugLevel 10;
             
             ## List of interfaces where we serve as Home Agent
             Interface "eth0";
    
             ##
             ## IPsec configuration
             ##
             UseMnHaIPsec enabled;
    
             IPsecPolicySet {
                     HomeAgentAddress fec0:106:2700::2;
                     HomeAddress fec0:106:2700::2/64;
    
                     IPsecPolicy HomeRegBinding UseESP;
                     IPsecPolicy MobPfxDisc UseESP;
                     IPsecPolicy TunnelMh UseESP;
              }
             
  2. MN: The MN config file should look like this:

             # Mobile IPv6 configuration file: Mobile Node
             #
             # filename: /etc/mip6d.conf         
    
             NodeConfig MN;
    
             ## If set to > 0, will not detach from tty
             DebugLevel 10;
    
             MnDiscardHaParamProb enabled;
    
             Interface "eth0";
    
             MnHomeLink "eth0" {
                     HomeAgentAddress fec0:106:2700::2;
                     HomeAddress fec0:106:2700::4/64;
             }
    
             ##
             ## IPsec configuration
             ## 
    
             UseMnHaIPsec enabled;
    
             IPsecPolicySet {
                     HomeAgentAddress fec0:106:2700::2;
                     HomeAddress fec0:106:2700::4/64;
    
                     IPsecPolicy HomeRegBinding UseESP;
                     IPsecPolicy MobPfxDisc UseESP;
                     IPsecPolicy TunnelMh UseESP;
             }
             

Configuring IPSec

To be completed.

Configuring radvd on AR

When MN comes to a new network, it does a link-local address configuration, going to the next phase if that succeeds. I'll let [RFC2462] (IPv6 Stateless Address Autoconfiguration) describe the next phase:

The next phase of autoconfiguration involves obtaining a Router Advertisement or determining that no routers are present. If routers are present, they will send Router Advertisements that specify what sort of autoconfiguration a host should do. If no routers are present, stateful autoconfiguration should be invoked.

Routers send Router Advertisements periodically, but the delay between successive advertisements will generally be longer than a host performing autoconfiguration will want to wait. To obtain an advertisement quickly, a host sends one or more Router Solicitations to the all-routers multicast group.” --- page 8

This is where we use Linux IPv6 Router Advertisement Daemon (RADVD).

Read [RFC2462] more more details concerning IPv6 Stateless Address Autoconfiguration.

We'll configure RADVD on AR's wireless interface. The radvd.conf file should contain this:

    # 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;
          };
    };
    

We then start it:

    # /etc/init.d/radvd start
    

You should now be able to use radvdump to see that the radvd messages really are being sent periodically:

    # 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
    

Note

When using radvd on HA and enabling “autoconf” (in proc), you will also get an autogenerated IPv6 address on MN (which is superfluous) in addition to your static address:

Configuring radvd on HA

To enable the MN to know when it's home, HA should also be sending out RAs. We should therefore enable RADVD on the HA as well. The /etc/radvd.conf file should contain:

     # 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;
        };
      };
      

Also do a radvdump on HA to check whether radvd messages are beeing sent:

    # 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
    

Also, you'll notice that MN (when home) generates a new address based on RADVD messages:

    # ifconfig eth0
    eth0  Link encap:Ethernet  HWaddr 00:90:7D:F3:03:1A  
          inet6 addr: fec0:106:2700::4/64 Scope:Site                  1
          inet6 addr: fe80::290:7dff:fef3:31a/64 Scope:Link           2
          inet6 addr: fec0:106:2700:0:290:7dff:fef3:31a/64 Scope:Site 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

Our original static IPv6 address

2

The link-local address generated at boot.

3

A new (superfluous) autogenerated address. Since we are setting autoconf in /proc/sys/net/ipv6/conf/eth0/autoconf to 1, MN will generate a new adress combined with HA's prefix and it's own MAC address. I do not think is it possible to avoid having this address generated.

Starting MIPv6

  1. Start Mobile IPv6 on HA. We do not use the init scripts when we do the testing. We want to view the verbosity messages:

              # mip6d -c /etc/mip6d.conf
              mip6d[3794]: MIPL Mobile IPv6 for Linux v2.0.1 started (Home Agent) 1
              main: MIPL Mobile IPv6 for Linux started in debug mode, not detaching from terminal
              conf_show: config_file = /etc/mip6d.conf 2
              conf_show: vt_hostname = localhost
              conf_show: vt_service = 7777
              conf_show: mip6_entity = 2
              conf_show: debug_level = 10
              conf_show: PolicyModulePath = [internal]
              conf_show: DefaultBindingAclPolicy = 0
              conf_show: NonVolatileBindingCache = disabled
              conf_show: KeyMngMobCapability = disabled
              conf_show: UseMnHaIPsec = enabled 3
              conf_show: MnMaxHaBindingLife = 262140
              conf_show: MnMaxCnBindingLife = 420
              conf_show: MnRouterProbes = 0
              conf_show: MnRouterProbeTimeout = 0.000000
              conf_show: InitialBindackTimeoutFirstReg = 1.500000
              conf_show: InitialBindackTimeoutReReg = 1.000000
              conf_show: UseCnBuAck = disabled
              conf_show: DoRouteOptimizationMN = enabled
              conf_show: MnUseAllInterfaces = disabled
              conf_show: MnDiscardHaParamProb = disabled
              conf_show: SendMobPfxSols = enabled
              conf_show: SendMobPfxAdvs = enabled
              conf_show: SendUnsolMobPfxAdvs = enabled
              conf_show: MaxMobPfxAdvInterval = 86400
              conf_show: MinMobPfxAdvInterval = 600
              conf_show: HaMaxBindingLife = 262140
              conf_show: DoRouteOptimizationCN = enabled
              xfrm_cn_init: Adding policies and states for CN
              xfrm_ha_init: Adding policies and states for HA
              vt_server_init: VT server listens 127.0.0.1[7777] OK 4
           
    1

    The node is acting as a HA.

    2

    The configuration file is /etc/mip6d.conf

    3

    We are using IPSec.

    4

    A VT server listning on localhost port 7777.

  2. Next we start Mobile IPv6 on MN. As with HA, we want the verbose messages, so we do not use the init script.

           # mip6d -c /etc/mip6d.conf
           mip6d[9121]: MIPL Mobile IPv6 for Linux v2.0.1 started (Mobile Node) 1
           main: MIPL Mobile IPv6 for Linux started in debug mode, not detaching from terminal
           conf_show: config_file = /etc/mip6d.conf 2
           conf_show: vt_hostname = localhost
           conf_show: vt_service = 7777
           conf_show: mip6_entity = 1
           conf_show: debug_level = 10
           conf_show: PolicyModulePath = [internal]
           conf_show: DefaultBindingAclPolicy = 0
           conf_show: NonVolatileBindingCache = disabled
           conf_show: KeyMngMobCapability = disabled
           conf_show: UseMnHaIPsec = enabled 3
           conf_show: MnMaxHaBindingLife = 262140
           conf_show: MnMaxCnBindingLife = 420
           conf_show: MnRouterProbes = 0
           conf_show: MnRouterProbeTimeout = 0.000000
           conf_show: InitialBindackTimeoutFirstReg = 1.500000
           conf_show: InitialBindackTimeoutReReg = 1.000000
           conf_show: UseCnBuAck = disabled
           conf_show: DoRouteOptimizationMN = enabled
           conf_show: MnUseAllInterfaces = disabled
           conf_show: MnDiscardHaParamProb = enabled
           conf_show: SendMobPfxSols = enabled
           conf_show: SendMobPfxAdvs = enabled
           conf_show: SendUnsolMobPfxAdvs = enabled
           conf_show: MaxMobPfxAdvInterval = 86400
           conf_show: MinMobPfxAdvInterval = 600
           conf_show: HaMaxBindingLife = 262140
           conf_show: DoRouteOptimizationCN = enabled
           xfrm_cn_init: Adding policies and states for CN
           xfrm_mn_init: Adding policies and states for MN
           conf_home_addr_info: HoA address fec0:106:2700:0:0:0:0:4 4
           conf_home_addr_info: HA address fec0:106:2700:0:0:0:0:2
           __tunnel_add: created tunnel ip6tnl1 (17) from fec0:106:2700:0:0:0:0:4 to fec0:106:2700:0:0:0:0:2 user count 1
           conf_home_addr_info: Home address fec0:106:2700:0:0:0:0:4
           flag_hoa: set HoA fec0:106:2700:0:0:0:0:4/128 iif 17 flags 10 preferred_time 4294967295 valid_time 4294967295
           conf_home_addr_info: Added new home_addr_info successfully
           __md_discover_router: discover link on iface eth0 (4)
           vt_server_init: VT server listens 127.0.0.1[7777] OK 5
           md_change_default_router: add new router fe80:0:0:0:201:2ff:fef1:91ee on interface eth1 (4)
           mn_addr_do_dad: DAD succeeded!
           mn_move: 1535
           mn_move: in home net 6
           mv_hoa: move HoA fec0:106:2700:0:0:0:0:4/64 from iface 17 to 4
           
    1

    The node is acting as a MN.

    2

    The configuration file is /etc/mip6d.conf

    3

    We are using IPSec.

    4

    The next lines shows Home Address (HoA) and Home Agent address (HA). Further down it creates a IPv6 tunnel.

    5

    A VT server listning on localhost port 7777.

    6

    The node detects that it's on the home network and changed the Home Address (HoA) from the tunnel (ip6tnl1) to the actual interface (eth0).

    Also when we issue the ifconfig, we'll notice the tunnel (ip6tnl1) is up:

             # ifconfig
               eth0      Link encap:Ethernet  HWaddr 00:90:7D:F3:03:1A  
                         inet6 addr: fec0:106:2700::4/64 Scope:Site                 
                         inet6 addr: fe80::290:7dff:fef3:31a/64 Scope:Link          
                         inet6 addr: fec0:106:2700:0:290:7dff:fef3:31a/64 Scope:Site
                         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
    
               ip6tnl1   Link encap:UNSPEC  HWaddr FE-C0-01-06-27-00-00-00-00-00-00-00-00-00-00-00  1
                         inet6 addr: fe80::211:43ff:fecc:279c/64 Scope:Link
                         UP POINTOPOINT 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:20352 errors:0 dropped:0 overruns:0 frame:0
                         TX packets:20352 errors:0 dropped:0 overruns:0 carrier:0
                         collisions:0 txqueuelen:0 
                         RX bytes:1840264 (1.7 MiB)  TX bytes:1840264 (1.7 MiB)
              
    1

    Tunnel is up and ready for connections.

Doing some tests

Pre-test

Do every configuration as shown above; it's especially important to have a different ESSID on the home net and visited network.

When you start mobile-IPv6 on MN, you will see multicast router solicitations messages from RADVD:

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

      

Movement detection

Generic movement detection uses Neighbor Unreachability Detection to detect when the default router is no longer bi-directionally reachable, in which case the mobile node must discover a new default router (usually on a new link).

To easily see whats going on, you should have one xterm window for each of these commands (on MN):

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

To “travel” to another net, you can issue the command on MN:

      # iwconfig eth1 essid visitnet
      

The MN is then on the other wireless network, and since it is sending out “router solicitation” (multicast), our AR will respond with it's prefix. MN will then configure itself with at new IPv6 address with the received prefix and it's own MAC address. If you type ifconfig eth0 you will see the new IPv6 address:

      # 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

The new “foreign” address, generated by combining AR's prefix and MAC-address

2

The superfluous home network address (because of HA radvd messages and MN autoconf set to “true”).

3

The “original” (home) address

4

The link-local address generated at boot

To be completed.

ping6

To be completed

Kernel IP routing table

To be completed.

Travelling through several foregin LAN's

To travel to several visited networks, is no different than travel to one network. The only thing you must have in mind is that you will generate a new address for each visited network.

MN travelling through severeal different LANs.

  1. MN first visits 'visitnet', as we have been through above.

  2. MN is then travelling from 'visitnet' to 'visitnet2'.

  3. When at 'visitnet2', MN generates a new IPv6 address and do a new binding update to HA.

  4. MN then travels back home. (Se next section.)

The AR at “visitnet2”, is configured exactly as the other AR (at “visitnet”), except using address fec0:106:1000::/64 instead of fec0:106:1100::/64.

To make the mobile node travel from “visitnet” to “visitnet2”, issue the command (on MN):

     # iwconfig eth0 essid visitnet2
     

You will then see the MN configures itself to the new network:

     # 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

The new autoconfigured address at 'visitnet2'.

To be completed.

Returning home

To make the MN return home, you can just issue the command:

    # iwconfig eth0 essid homenet
    

The MN will know it is back home, since HA is sending out radvd messages with the HA-bit set (AdvHomeAgentFlag), see the section called “Configuring radvd on HA”

To be completed.

Real life testing - smooth handover

To really get the feel on how mobile IP works, fire up GnomeMeeting (See the figure GnomeMeeting and start a netmeeting. Note! You must use the latest GnomeMeeting to get support for IPv6! Then do a “travel” and you can see an almost smooth handover.

GnomeMeeting

Using GnomeMeeting with IPv6 to test roaming between two wireless networks

FAQ

  1. Q: Is it normal to use iwconfig eth0 essid visitnet to control handover?

    A: No, it has nothing to do with Mobile IPv6. It is just as an example on how you can easily test that your setup works. ESSIDs are layer 2, while Mobile IPv6 is layer 3.

  2. Q: Can different wireless networks have different ESSIDs/WEP keys?

    A: Yes, but you must change this upon arrival to the new network. MIPv6 from MIPL can't do this automatically.

  3. Q: If MN has travelled through several visited LAN, and then returning home; the interface still has all the autogenerated IPv6 addresses from all the visited networks! Is there any way to “flush/delete” these addresses?

    A: No, I do not know of any automatic way these adresses can be removed, but you can delete them manually:

    # ifconfig eth0 inet6 del <ipv6-address>

  4. Q: Host B has two interfaces with two different subnets assigned. When I ping B from host A, it does not answer! Why not? Host A knows where host B (subnets) are!

    A: The host B doesn't know where host A is (B doesn't know where A's net is), so you must add a route entry:

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

    or

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

  5. Q: How do I set a default gateway in IPv6?

    A: You do that using the traditional “route”:

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

    or the newer “ip” command:

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

  6. Q: Why does the host send a multicast address rather than an anycast address, requesting for router solicitation?

    A: Because the host wants an answer from every router, not from just any router. The idea is to be able to get all parameters and to choose the “best” default router.

  7. Q: Why doesn't MN notice that it has moved?

    A: It thinks that it's previous router is still reachable. This may result from very large lifetimes in router advertisements. Check the configuration of the program sending router advertisements in the router. If the program supports router advertisement intervals, you can use this to help MN in movement detection by setting the use of interval to on. See radvd.conf(5) for details.

Useful Resources

  1. Mobile IPv6 for Linux http://mobile-ipv6.org/

  2. Mobility for IPv6 (mip6) Working Group (IETF) http://www.ietf.org/html.charters/mip6-charter.html

  3. IPv6 Working Group (IETF) http://www.ietf.org/html.charters/ipv6-charter.html

  4. RFC2460: Internet Protocol, Version 6 (IPv6) Specification http://www.ietf.org/rfc/rfc2460.txt

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

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

  7. RFC3775: Mobility Support in IPv6 http://www.ietf.org/rfc/rfc3775.txt

  8. RFC3776: Using IPsec to Protect Mobile IPv6 Signaling Between Mobile Nodes and Home Agents http://www.ietf.org/rfc/rfc3776.txt

  9. RFC3963: Network Mobility (NEMO) Basic Support Protocol http://www.ietf.org/rfc/rfc3963.txt

  10. RFC4068: Fast Handovers for Mobile IPv6 http://www.ietf.org/rfc/rfc4068.txt

  11. RFC4140: Hierarchical Mobile IPv6 Mobility Management (HMIPv6) http://www.ietf.org/rfc/rfc4140.txt

  12. RFC4301: Security Architecture for the Internet Protocol http://www.ietf.org/rfc/rfc4301.txt

  13. RFC4302: IP Authentication Header http://www.ietf.org/rfc/rfc4302.txt

  14. RFC4303: IP Encapsulating Security Payload (ESP) http://www.ietf.org/rfc/rfc4303.txt

  15. RFC4306: Internet Key Exchange (IKEv2) Protocol http://www.ietf.org/rfc/rfc4306.txt

  16. Peter Bieringer's Linux IPv6 HOWTO (en) http://ldp.linux.no/HOWTO/Linux+IPv6-HOWTO/

  17. Linux Kernel HOWTO http://www.tldp.org/HOWTO/Kernel-HOWTO/

  18. Linux NEMO HOWTO http://www.nautilus6.org/doc/nepl-howto/

  19. Current Status of IPv6 Support for Networking Applications http://www.deepspace6.net/docs/ipv6_status_page_apps.html

Copyright, acknowledgments and miscellaneous

Copyright and License

Copyright (c) 2003-2006 Lars Strand.

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

How this document was produced

This document was originally written in LaTeX using Emacs. HTML version created with latex2html. Later it was converted to DocBook XML.

An up-to-date version of this document can be found at:

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

Feedback

Suggestions, corrections, additions wanted. Contributors wanted and acknowledged. Flames not wanted.

I can always be reached at

Homepage: http://www.gnist.org/~lars

Acknowledgments

This document was produced as a part of Interoperable Networks for Secure Communications (INSC task 6)

Thanks to Andreas Hafslund (andreha [at] unik.no) for initial support. Also thanks to UniK (University Graduate Center) http://www.unik.no and FFI (Norwegian Defence Research Establishment) http://www.ffi.mil.no for hardware support.

Thanks also to the other HOWTO authors whose works I have referenced:

Linux IPv6 HOWTO (en) by 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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

FUTURE REVISIONS OF THIS LICENSE

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

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

ADDENDUM: How to use this License for your documents

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.