How to setup TAHI tests for UMIP

Back to index

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Overview

Below, you'll find the steps required to setup a TAHI test environment for UMIP. TAHI test suites are conformance tests provided by the WIDE TAHI working group. These tests aim at validating the implementation of the IPv6 protocol suite (IPv6 core protocols, IPsec, IKEv2, DHCPv6, Mobile IPv6, NEMO Basic Support, etc.).

TAHI test suites basically check all the features and possible scenarios in which a protocol can operate. Each test suite is composed by numerous tests. Each of these tests is dedicated to a specific part of the standard and can detect whether an implementation complies with it. The test results can greatly help developers to find out in which case their implementation does not behave as expected. It is thus an important tool to check the compliance with the standard, but also to track possible regressions during the development phase.

Before installing and configuring the TAHI test environment, let's first explain its overall architecture. A TAHI test environment is mainly composed by two entities:

After a few pre-requisites, we will explain how to setup a TN with the TAHI Mobile IPv6 test suite, and how to setup a NUT with UMIP. We will then explain how to run the test suite. A FAQ is available at the end of this article, providing answers for common questions.

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Pre-requisites

The following network topology will be used. In the remaining of this document, replace the network interface names by the one you have on your computer. 

                           TN                                   NUT
                     +------------+       Ethernet       +---------------+
                     |       [em1]+----------------------+[eth1]         |
                     |            |                      |               |
                     |       [em2]+----------------------+[eth2]         |
       Internet -----+[em0]       |                      |         [eth0]+----- Internet
                     |            |                      |               |
                     |    [serial]+----------------------+[serial]       |
                     |            |     Serial cable     |               |
                     +------------+                      +---------------+

In case you plan to have the NUT rebooted between each test, both the TN and the NUT must have a serial port. However, this is not mandatory as we can also run the tests in a consecutive manner.

An easy way to setup a TAHI testbed is to use virtual machines, e.g. using VirtualBox. It is very convenient, especially because you can easily emulate ethernet links and a serial connection between the TN and the NUT. Using VirtualBox, you can:

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Tester Node (TN)

FreeBSD configuration

The TN needs to run Freebsd 7.3 release or higher (it can also run on Linux, see the FAQ for more information). Install it (downloading CD1 is enough for the installation). Once the system is installed, you need to install a few more tools: wget, tcpdump, apache22, p5-Expect and p5-Digest-MD5. For that purpose, you can use portsnap: 

# portsnap fetch
# portsnap extract

Notes: the fetch can take some time. The extract command is only used the first time, next time you can just use 'portsnap update' to update your ports. Install the required tools with: 

# cd /usr/ports/ftp/wget && make install clean
# cd /usr/ports/www/apache22 && make install clean
# cd /usr/ports/lang/p5-Expect && make install clean
# cd /usr/ports/security/p5-Digest-MD5 && make install clean
# cd /usr/ports/textproc/p5-YAML && make install clean
# cd /usr/ports/net/tcpdump && make install clean

If you experience issues with the tcpdump port (an error such as: undefined reference to 'pcap_free_datalinks'), you should first install the libpcap from the sources, and then try to reinstall tcpdump: 

# wget http://www.tcpdump.org/release/libpcap-1.3.0.tar.gz
# tar zxf libpcap-1.3.0.tar.gz
# cd libpcap-1.3.0
# ./configure --prefix=/usr
# make && make install
# cd /usr/ports/net/tcpdump && make install clean

Now, download the following software from the TAHI website:

Install the v6eval package (it will be installed in /usr/local/v6eval/): 

$ tar zxf v6eval-X.X.tar.gz
$ cd v6eval-X.X/
$ make
# make install

Install the ike-mipv6 module: 

$ tar zxf ike-mipv6-X.X.tar.gz
$ cd ike-mipv6-X.X
$ make
# make install

Install the v6eval-remotes module. It will be used to control the NUT from the TN, using the serial line (replace <version> with your perl version): 

$ tar zxf v6eval-remotes-X.X.tar.gz
$ cd v6eval-remotes-X.X
$ make
# cp -r bin/remotes/linux-v6/ /usr/local/v6eval/bin/linux-v6/
# cd /usr/local/lib/perl5/site_perl/<version>/

You need to modify the /usr/local/lib/perl5/site_perl/<version>/V6evalRemote.pm file. Copy all of the commented lines starting with 'linux-v6' in the list located above the commented lines. For example: 

[...]
# login prompt
%prompt_user = (
                'linux-v6',    'login: ',
               );
[...]

Create a BPF (Berkeley Packet Filter) device. For that purpose, edit the /etc/rc.conf file and add: 

devfs_system_ruleset="devfsrules_unhide_bpf"

Edit also the /etc/defaults/devfs.rules file and add: 

[devfsrules_unhide_bpf=1025]
add path 'bpf*' user root group wheel mode 0660 unhide

IPv6 support must be disabled on the TN. Also, the interfaces that will be connected to the NUT must be up. Edit the /etc/rc.conf file and add the following lines (replace em1 and em2 with the name of your devices): 

ipv6_enable="NO"
ifconfig_em1="up"
ifconfig_em2="up"

Configure apache to start on boot. Add in the /etc/rc.conf file the following line: 

apache22_enable="YES"

You can start apache the first time with: 

# apachectl start

Remove the apache index file: 

# rm /usr/local/www/apache22/data/index.html

Test results will be available online at http://<IP address of the TN>/. Be aware that the test results will contain the root password of the NUT. You should thus setup some authentication (e.g. via htaccess) to restrict the access to the results. If you want to disclose these results, you can anonymize them as explained later before copying them to a public place.

If you plan to have the NUT rebooted between each test, you have to configure the serial line with: 

# touch /var/log/aculog
# chown uucp:dialer /var/log/aculog
# chmod 660 /var/log/aculog

Once the serial connection has been configured on the NUT too (see later in the NUT section), you can test you serial connection by running the following command (supposing that cuad0 is your serial interface). You should see the login prompt of the NUT: 

# cu -l /dev/cuad0

The user who will execute the tests must be in the wheel and dialer groups. You can add this user in these groups with (replace <user> with the user name): 

# pw usermod <user> -G wheel,dialer

Generic TAHI configuration

We can now configure the TAHI test suite. Go to the /usr/local/v6eval/etc directory, and create a tn.def file from the sample one: 

# cd /usr/local/v6eval/etc
# cp tn.def.sample tn.def
# vi tn.def

Especially, modify RemoteDevice to match the name of your serial device, and replace the interface names of Link0 and Link1 with your interface names that will be connected to the NUT. Typically, your file should look like this: 

# tn.def
# Replace 'cuad0' with your serial device name
RemoteDevice    cuad0
RemoteDebug     0
RemoteIntDebug  0
RemoteLog       1
RemoteSpeed     0
RemoteLogout    0
RemoteMethod    serial

# Replace 'em1' and em2 with the name of the interfaces
# connected to the NUT. DO NOT CHANGE other parameters.
Link0     em1     00:00:00:00:01:00
Link1     em2     00:00:00:00:01:01

Now, create the nut.def file from the sample one: 

# cp nut.def.sample nut.def
# vi nut.def

This file includes information of your NUT (i.e. the computer that will run UMIP). It will be slightly different for each of the HA, MN or CN test suite, so the best is to create a file for each configuration: nut.def.ha, nut.def.mn and nut.def.cn for the HA, MN and CN test suites respectively.

The System parameter must be set to linux-v6. Set the HostName of your NUT if it has one. The Type depends on what runs on the NUT: set it to host for a MN or a CN, router for a HA. You also need to specify the root password of the NUT with the Password parameter. Finally, you need to specifiy the interfaces name of the NUT that will be connected to the TN (1 interface for the MN NUT, 2 interfaces for the HA NUT), and set the exact MAC address of these interfaces. Typically, your file should look like this: 

# nut.def
System		linux-v6
TargetName	Linux + UMIP 
HostName	nut.example.com

# Here, you have to set 'host' when you plan to run a MN 
# or a CN on the NUT, and 'router' when you plan to run 
# a HA on the NUT
#Type		router
Type		host

# Replace 'NUT_ROOT_PASSWORD' by the root password of the NUT.
User		root
Password	NUT_ROOT_PASSWORD

# Replace 'eth1' with the interface of the NUT that will be 
# connected to the TN, and replace 'aa:bb:cc:dd:ee:ff' with
# the REAL MAC address of that interface.
Link0     eth1     aa:bb:cc:dd:ee:ff

# The NUT in HA mode uses another interface to emulate a foreign
# link. Configure it (only for the HA!) by replacing 'eth2' with
# the second interface of the NUT that will be connected to the
# TN, and replace 'aa:bb:cc:dd:ee:ff' with the REAL MAC address
# of that interface.
Link1     eth2     aa:bb:cc:dd:ee:ff

Configuring the TAHI MN Test Suite

This section explains how to configure the MN test suite. Uncompress and install the MN test suite from the previously downloaded software: 

$ tar zxf ct-mipv6-mn-X.X.tar.gz
$ cd ct-mipv6-mn-X.X
# make install
# cp -pR /usr/local/v6eval/ct-mipv6-mn /usr/local/www/apache22/data/ct-mipv6-mn 
# chmod -R +w /usr/local/www/apache22/data/ct-mipv6-mn

We believe the MN test suite needs to be patched. If IPsec is configured, the TAHI test #42 expects that the MN sends a Neighbor Advertisement protected by IPsec. UMIP never protects Neighbor Discovery messages with IPsec, which we believe is the correct behavior. You can patch the tests by downloading our patches and applying them as follow: 

# cd /usr/local/www/apache22/data/ct-mipv6-mn/mipv6-mn/
# wget http://umip.org/docs/tahi/tn/ct-mipv6-mn/mip6_mn_neighbor.def.patch
# wget http://umip.org/docs/tahi/tn/ct-mipv6-mn/MN-2-2-2-1-027.seq.patch
# patch -p0 < mip6_mn_neighbor.def.patch
# patch -p0 < MN-2-2-2-1-027.seq.patch

Then we can proceed with the tests installation: 

# cd /usr/local/www/apache22/data/ct-mipv6-mn
# make clean && make document

We can now configure the MN test suite. The configuration takes place in the config.txt file that is located in /usr/local/www/apache22/data/ct-mipv6-mn/mipv6-mn/. This file gathers all the configuration items of the tests. We provide ready-to-use configuration files, with and without IPsec:

If you plan to be exhaustive, you should run the TAHI tests with each of these configuration. At the moment, UMIP currently does not support IPsec with Route Optimization, so all the RO-related tests are not performed if IPsec is activated.

If you want to have the NUT rebooted between each tests, you should set the ENV_INITIALIZE parameter to BOOT in the config.txt file (and also configure the serial line between the TN and the NUT). At the moment, it is set to RETURN, which makes the TN emulating a returning home between each test, and perform all the tests in a consecutive manner. This makes the complete test execution time much shorter.

Now we need to get the Home Address and Home Agent address that will be used during the tests. On the TN, execute the MN test suite as followed (don't forget to copy your corresponding nut.def file beforehand): 

# cp /usr/local/v6eval/etc/nut.def.mn /usr/local/v6eval/etc/nut.def 
# cd /usr/local/www/apache22/data/ct-mipv6-mn/mipv6-mn/
# make clean && make test

The test logs should display on your terminal the HoA and HA address. Once they are displayed, you can kill the tests with ctrl+c. They should look like this (but with slightly different addresses): 

HoA address    : 3ffe:501:ffff:100:230:5ff:fe1a:7ffb
ha0 address    : 3ffe:501:ffff:100:200:ff:fe00:a0a0

Save these addresses for later: they will be used to configure the UMIP MN on the NUT.

Configuring the HA Test Suite

This section explains how to configure the HA test suite. Uncompress and install the HA test suite from the previously downloaded software: 

$ tar zxf ct-mipv6-ha-X.X.tar.gz
$ cd ct-mipv6-ha-X.X
# make install
# cp -pR /usr/local/v6eval/ct-mipv6-ha /usr/local/www/apache22/data/ct-mipv6-ha 
# chmod -R +w /usr/local/www/apache22/data/ct-mipv6-ha
# cd /usr/local/www/apache22/data/ct-mipv6-ha
# make clean && make document

We can now configure the HA test suite. The configuration takes place in the config.txt file that is located in /usr/local/www/apache22/data/ct-mipv6-ha/mipv6-ha/. This file gathers all the configuration items of the tests. We provide ready-to-use configuration files, with and without IPsec:

If you want to have the NUT rebooted between each tests, you should set the NEED_REBOOT parameter to 1 in config.txt (and also configure the serial line between the TN and the NUT). At the moment, it is set to 0, which makes the complete test execution time much shorter.

Now we need to get the Home Address and Home Agent address that will be used during the tests. On the TN, execute the HA test suite as followed (don't forget to copy your corresponding nut.def file beforehand): 

# cp /usr/local/v6eval/etc/nut.def.ha /usr/local/v6eval/etc/nut.def 
# cd /usr/local/www/apache22/data/ct-mipv6-ha/mipv6-ha/
# make clean && make test

The test logs should display on your terminal the HoA and HA address. Once they are displayed, you can kill the tests with ctrl+c. They should look like this (but with slightly different addresses): 

HA(inet6): 3ffe:501:ffff:100:230:5ff:fe1a:7ffb
MN HoA(inet6): 3ffe:501:ffff:100:200:ff:fe00:1

Save these addresses for later: they will be used to configure the UMIP HA on the NUT.

Configuring the CN Test Suite

Configuration for the CN test suite is not yet available. We will provide it in the future.

Configuring the NEMO HA Test Suite

Configuration for the NEMO HA test suite is not yet available. We will provide it in the future.

Configuring the NEMO MR Test Suite

Configuration for the NEMO MR test suite is not yet available. We will provide it in the future.

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Node Under Test (NUT)

Linux configuration

The NUT will run UMIP. Install a GNU/Linux system with a mobility-ready kernel and compile the UMIP userland. A detailed documentation to setup a UMIP environment is available here. Do not take care of the UMIP configuration yet and do not run UMIP yet on the NUT. We will discuss these topics a bit later.

If you plan to have the NUT rebooted between each test, you have to configure the serial line on the NUT. Edit the /etc/inittab file and uncomment or add the following line (ttyS0 being your serial device): 

T0:23:respawn:/sbin/getty -L ttyS0 9600 vt100

In the /etc/securetty file, check that the following line exists, otherwise add it: 

ttyS0

Configure the root account on the NUT with the same password that you specified in the nut.def file on the TN. Once the serial connection has been configured between your TN and NUT, you can test it from the TN as explained in the TN section.

If you plan to connect one interface of your NUT to the Internet, you have to configure this interface to use IPv4-only and to not use IPv6 autoconfiguration. Here is an example /etc/network/interfaces file that you can use: 

# /etc/network/interfaces
auto lo
iface lo inet loopback

# Replace 'eth0' with your interface connected to the Internet.
auto eth0
iface eth0 inet dhcp
        # Replace interface names with the one connected to the TN
        up /sbin/ifconfig eth1 up
        up /sbin/ifconfig eth2 up

In addition, in the /etc/sysctl.conf file, add the following line (eth0 being your interface connected to the Internet): 

net.ipv6.conf.eth0.accept_ra=0

Make sure your /etc/resolv.conf file is empty (e.g. do not use dns-* options in your /etc/network/interfaces file). This will prevent the NUT from sending unnecessary packets that could disturb the tests. Similarly, do not run any routing daemon on the NUT.

Configuration of the UMIP MN

This section provides configuration files (for UMIP and setkey) that you can use for a UMIP MN on the NUT. These configurations use the previously saved HoA and HA addresses. You need to replace them with yours, as well as replace the interface names with yours:

Store them in /usr/local/etc/.

Configuration of the UMIP HA

This section provides configuration files (for UMIP and setkey) that you can use for a UMIP HA on the NUT. These configurations use the previously saved HoA and HA addresses. You need to replace them with yours, as well as replace the interface names with yours. Store them in /usr/local/etc/:

You also need to configure radvd, as the Home Agent will send router advertisments on one of the link between the TN and the NUT. You can use this radvd.ha.tahi.conf file (change the address and interface name with yours) and store it in /usr/local/etc/.

Starting UMIP

You can find a sample startup script for UMIP designed for the TAHI tests here: start-umip.sh. You need to modify the Configuration section to match your configuration parameters (interface name, HoA, binary location, etc.). This script will automatically configure the NUT for the TAHI tests (install the proper routes and sysctl parameters), start UMIP in HA (-H option) or MN (-M option) mode, start setkey (if you set the -I option) and start radvd (if the HA mode is used).

This script uses the mip6d init.d script that you can find here and that you should copy in /etc/init.d/ and make executable. You should also set the following parameters into the /etc/default/mip6d file (create the file if needed): 

RUN="yes"
MIP6D=/usr/local/sbin/mip6d
MIP6D_CONF=/usr/local/etc/mip6d.tahi.conf
MIP6D_DEBUG_LOG=/var/log/mip6d.tahi.log

This script also uses the setkey init.d script that is installed by the ipsec-tools package. You should also set the following parameters into the /etc/default/setkey file: 

SETKEY_CONF=/usr/local/etc/setkey.tahi.conf

You can start the MN with IPsec (remove the -I option if you do not want to use IPsec): 

# ./start-umip.sh -M -I

You can start the HA with IPsec (remove the -I option if you do not want to use IPsec): 

# ./start-umip.sh -H -I

Other options are available. Check them by displaying the help with the -h option. Note that if you have set the TN to reboot the NUT between each tests, you have to make sure that UMIP will be automatically started at boot. For that purpose, you can for example call the above script in /etc/rc.local.

You are now ready to launch the TAHI test suite on the TN.

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Running the Tests

Make sure that you have started the UMIP daemon on the NUT, as explained in the previous section.

On the TN side, copy the appropriate nut.def.* file into nut.def. For example for the MN test suite: 

# cp /usr/local/v6eval/etc/nut.def.mn /usr/local/v6eval/etc/nut.def

Tests suite are executed on the TN from the /usr/local/www/apache22/data/ct-mipv6-*/mipv6-*/ directory. You need to set the correct config.txt file according to whether you plan to test UMIP with IPsec or not. For example for the MN, you can run the tests with IPsec with: 

$ cd /usr/local/www/apache22/data/ct-mipv6-mn/mipv6-mn/
# cp config.txt.ipsec config.txt
# make clean && make test

Tests can take between 1.5 hour (with IPsec) and 3 hours (without IPsec) for the MN, 4 hours for the HA (with or without IPsec). You can however follow the results of each test while the test suite is running: using a web browser, you just need to visit http://<IP address of the TN>/.

IMPORTANT NOTE: the root password of the NUT appears in the test results. We advice you to protect the access to the results with an HTTP login/password authentication as described before. If you want to publish the results, you can anonymize them before copying them to another public place. For that purpose, you can execute the following command (replace NUT_ROOT_PASSWORD with your NUT root password): 

$ cd /usr/local/www/apache22/data/
# find . -type f -exec sed -e 's/NUT_ROOT_PASSWORD/xxxxxxxxxx/g' -i "" {} \;
Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

FAQ

Overview   Pre-requisites   TN   NUT   Running the Tests  FAQ   Changelog

Changelog