========================================================================

	    NETWORKING REQUIREMENTS FOR X-XBONE PLATFORMS

			    May 26, 2003


1. INTRODUCTION

The X-Bone system depends on a number of basic and advanced networking
capabilities. This document lists such REQUIRED and OPTIONAL 
capabilities. It also describes a test case for each capability, and 
can thus serve as a checklist to determine whether a given platform can 
support X-Bone deployment.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [1].

Note all the examples and commands shown in this document are based on 
FreeBSD.


2. KERNEL REQUIREMENTS

To enable IP-IP tunneling, add the following line to your kernel config 
file:

pseudo-device gif 128 # Freebsd 3.x, 4.0 - 4.3
pseudo-device gif #Freebsd 4.4 or above 

To add IPsec support to your kernel, add the following lines to your 
kernel config file:

options IPSEC   #IP Security
options IPSEC_ESP  #IP security (crypto)
options IPSEC_DEBUG   #debug for IP security

Recompile and install the new kernel.


3. CORE CAPABILITIES

This section describes networking capabilities to fully support X-Bone
deployment. Most features in this section are REQUIRED; if a platform
does not support one or more such features, it cannot support X-Bone
deployment.


3.1 IP TUNNELING

A system MUST support IP tunnels [2] to support the X-Bone. 
Additionally, it MUST allow assignment of multiple IP addresses to
each tunnel interface (IP aliasing).

step 1: Configure an IP tunnel pair between hosts A and B as shown in
        Figure 2. The tunnel endpoints have the IP addresses T1 (on A)
        and T2 (on B). The tunnel on A will encapsulate packets with
        another IP header with source address I1 and destination
        address I2 (or I1->I2 for short). The tunnel on B will
        encapsulate with another IP header I2->I1.


		    +---------+        +---------+
		    |    A    |        |    B    |
		    |       I1----------I2     I3-...
		    |     T1  |        |  T2     |
		    +------|--+        +--|------+
		           |              |
		           +--------------+

		 FIGURE 1: IP tunnel between A and B

For example, if the IP addresses for I1 and I2 are as follows: 

	128.9.160.31; 128.9.160.211

and we assign following IP addresses to the tunnel endpoints T1
and T2:

	10.1.0.1; 10.1.1.1 

Assuming the tunnel interfaces on host A and host B are gif0 and gif1 
respectively, we can use the following commands to configure the
above IP tunnel pair: 
	
on host A,

	ifconfig gif0 create 10.1.0.1 10.1.1.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.31 128.9.160.211 

on host B,

 	ifconfig gif1 create 10.1.1.1 10.1.0.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.211 128.9.160.31

Step 2: Test connectivity over the tunnel by generating ICMP ping
	requests [REF?] packets on host A destined for the tunnel
        endpoint T2 on host B. It is MANDATORY that ICMP echo 
        replies from B are recived in respones to the ping requests.

we can use the following commands to test the connectivity:

on host A,
	ping 10.1.1.1

on host B,
	ping 10.1.0.1

if the IP tunnel has been set up sucessfully, you can get the ICMP 
echo replies as:

on host A,
	64 bytes from 10.1.1.1: icmp_seq=0 ttl=64 time=0.485 ms
	64 bytes from 10.1.1.1: icmp_seq=1 ttl=64 time=0.440 ms

on host B,
	64 bytes from 10.1.0.1: icmp_seq=0 ttl=64 time=1.604 ms
	64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=0.431 ms

Step 3: Verify the well-formedness of the tunneled IP packets by
        capturing a packet trace on the I1-I2 link while testing
        connectivity as described in the previous step. It is
        MANDATORY that the packets conform to the templates shown in
	  Figure 2.

		    +--------+--------+---------+
		    | I1->I2 | T1->T2 | Payload |
		    +--------+--------+---------+
		    +--------+--------+---------+
		    | I2->I1 | T2->T1 | Payload |
		    +--------+--------+---------+

     FIGURE 2: Packet format over the IP tunnel between A and B.

Commands:
	
	on host A, run:
 	tcpdump -i em0 | grep 10.1.1.1 # if the ethernet interface is em0

	at the same time, on host B, run:
	ping 10.1.0.1

check the packets caputred on host A. Their format should conform to the
template shown in FIGURE 2. For example, the output on host A should 
like:

	23:31:09.058473 tlc.isi.edu > mul.isi.edu: 10.1.0.1 > 10.1.1.1: 
	icmp: echo reply (ipip-proto-4)
	23:31:10.068483 mul.isi.edu > tlc.isi.edu: 10.1.1.1 > 10.1.0.1: 
	icmp: echo request (ipip-proto-4)

Step 4: Repeat the previous two steps, but use I3 instead of I2 in
        the encapsulation header configuration. Check for
        well-formedness. While not REQUIRED, substituting I3 for I2 in
        the steps above SHOULD NOT disrupt connectivity. Disruption of
        communication due to this change MAY be indicative of issues
        in the network stack of one of the test machines that could
        impede X-Bone deployment.


		    +---------+        +---------+
		    |    A    |        |    B    |
		    |       I1----------I2     I3-...
		    |   T1/A1 |        | T2/A2   |
		    +------|--+        +--|------+
			   |              |
			   +--------------+

	   FIGURE 3: IP tunnel between A and B with aliases

Step 5: Starting with the tunnel configuration set up during step 1
        above, assign additional IP addresses (aliases) to the tunnel
        pair. Add A1 as an alias to T1, and A2 as an alias to T2 as
        depicted in Figure 4. Then repeat step 3 using the tunnel
        aliases, and check for packet well-formedness.


3.2 RECURSIVE IP TUNNELING

Recursive tunneling describes the capability of nesting one IP tunnel
inside another IP tunnel. At least one level of such recursion is
REQUIRED, more levels are RECOMMENDED.

For example, we can create one level of such recursion based on the 
tunnel pair we configured at 3.1:  

		    +---------+        +---------+
		    |    A    |        |    B    |
		    |       I1----------I2     I3-...
		    |     T1  |        |  T2     |
		    +------|--+        +--|------+
		    |      +--------------+      |
		    |         |        |         | 
		    |     T3  |        |  T4     |
		    +------|--+        +--|------+
                           |              |      
	       	           +--------------+      

	 FIGURE 4: one level recursive IP tunnel between A and B

Assume the IP addresses for T3 and T4 are 10.2.0.1 and 10.2.1.1 on 
host A and B respectively, and the tunnel interfaces for T3 and T4 
are all gif2.

Run the following commands on host A:

ifconfig gif2 create 10.2.0.1 10.2.1.1 netmask 255.255.255.192 \
	 tunnel 10.1.0.1 10.1.1.1

on host B, run:

ifconfig gif2 create 10.2.1.1 10.2.0.1 netmask 255.255.255.192 \
	 tunnel 10.1.1.1 10.1.0.1

then, use the following commands to check connectivity over the new 
created tunnel:

on host A,
	ping 10.2.1.1

on host B,
	ping 10.2.0.1

ICMP echo replies should be received in respones to the ping requests.
 
next, check well-formedness of the 1-level recursive tunneled IP 
packets, whose format should comform to the templates shown below: 

	    +--------+--------+---------+---------+
	    | I1->I2 | T1->T2 | T3->T4  | Payload |
	    +--------+--------+---------+---------+
	    +--------+--------+---------+---------+
	    | I2->I1 | T2->T1 | T4->T3  | Payload |
	    +--------+--------+---------+---------+

  FIGURE 5: Packet format over the recursive IP tunnel between A and B.

Commands:
	
	on host A, run:
 	tcpdump -i em0 | grep 10.2.1.1 #if the ethernet interface is em0

	at the same time, on host B, run:
	ping 10.2.0.1

the output on host A should be something like this:
	23:59:28.582425 tlc.isi.edu > mul.isi.edu: 10.1.0.1 > 10.1.1.1: 
10.2.0.1 > 10.2.1.1: icmp: echo reply (ipip-proto-4) (ipip-proto-4)
	23:59:29.592406 mul.isi.edu > tlc.isi.edu: 10.1.1.1 > 10.1.0.1: 
10.2.1.1 > 10.2.0.1: icmp: echo request (ipip-proto-4) (ipip-proto-4)


3.3 TUNNEL ROUTING

The X-Bone configures a virtual topology by stringing together network
paths out of IP tunnels and routes. Thus, a platform MUST support IP
routing over IP tunnel interfaces. At least static IP routing is
REQUIRED, support for dynamic routing protocols is RECOMMENDED (see
section 4.2 for more details).


3.4 SECURE CONFIGURATION

Since the X-Bone performs remote system reconfiguration, a node MUST
support a secure and authenticated channel over which it receives
configuration commands.

At this time, the RECOMMENDED secure configuration channel is based on
the secure socket layer (SSL) [REF?]. Similar substitutes, such as
secure shell (SSH) [REF?] or IPsec [3] MAY be used instead. X-Bone
configuration commands MUST NOT be transmitted unsecured or
unauthenticated over the public Internet.


4. TEST TOPOLOGY

To test whether a given platform can be used as an X-Bone node, test
cases are described for each of the capabilities below. A line
topology of four connected hosts must be set up for these tests as
shown in Figure 6.


+---------+        +---------+        +---------+        +---------+
|    A    |        |    B    |        |    C    |        |    D    |
|       V1---------V2        V3-------V4        V5--- ---V6        |
|         |        |         |        |         |        |         |
+---------+        +---------+        +---------+        +---------+

	    FIGURE 6: Topology used in conformance tests.


Letters labels hosts in this diagram, while letter/number pairs are 
virtual IP addresses assigned to interfaces. Links are uniquely 
identified through their connecting interfaces. For example, host B 
has two separate interfaces with IP addresses V2 and V3, while host 
D has a single interface with IP address V6. A packet sent from B to 
D would first traverse the V3-V4 link, then the V5-V6 link.

Note that some of the tests below do not require the full four-node 
line. Further diagrams may omit parts of the full topology where 
appropriate.

For example, if the four hosts' public IP addresses in the order of A
B C D are

	128.9.160.31 128.9.160.211 128.9.160.215 128.9.112.67

and we can assign following IP addresses to the above IP tunnel 
interfaces:

	10.1.0.1 ==> V1; 10.1.1.1 ==> V2; 10.1.1.2 ==> V3; 
	10.1.2.1 ==> V4; 10.1.2.2 ==> V5; 10.1.3.1 ==> V6;

Here are the basic commands to set up the test topology:

on host A,
	
	ifconfig gif0 create 10.1.0.1 10.1.1.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.31 128.9.160.211

on host B,
	
	ifconfig gif1 create 10.1.1.1 10.1.0.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.211 128.9.160.31
	ifconfig gif0 create 10.1.1.2 10.1.2.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.211 128.9.160.215

on host C,

	ifconfig gif1 create 10.1.2.1 10.1.1.2 netmask 255.255.255.192 \
		 tunnelf 128.9.160.215 128.9.160.211
	ifconfig gif0 create 10.1.2.2 10.1.3.1 netmask 255.255.255.192 \
		 tunnel 128.9.160.215 128.9.112.67

on host D,
	
	ifconfig gif1 create 10.1.3.1 10.1.2.2 netmask 255.255.255.192 \
		 tunnel 128.9.112.67 128.9.160.215 

Use "ping" from all nodes to all addresses of the "test topology" to 
check the connectivity.


4.1 TEST TOPOLOGY FORWARDING

Generally, a system SHOULD support IP forwarding to fully participate in 
the X-Bone. At this time, the X-Bone architecture permits nodes that do 
not support IP forwarding to participate in overlays in a limited fashion 
(as end hosts, i.e packet sources and sinks). However, future versions of 
the X-Bone architecture may eliminate this special case, and IP 
forwarding MAY become REQUIRED.

If your system does not support IP forwarding, it can only participate as 
an end host in the X-Bone. In the above test topology, such systems MUST 
be placed at the end of the four node line (i.e. nodes A and D).  You MUST 
find two other X-Bone compliant machines for the remaining nodes in the 
test topology to check whether the platform in question supports other 
networking capabilities REQUIRED for the X-Bone.

Before continuing with the remainder of the tests described in this
document, IP forwarding MUST be configured on the test topology, such
that all nodes can communicate with one another:

Step 1: Enable IP forwarding on nodes B and C.

Run the following commands on host B and C:
	sysctl -w net.inet.ip.forwarding = 1

Step 2: On host A, add three routes that forward packet to B, C
	and D over link I1-I2.

Run the following commands on host A:
 	route add -net 10.1.1.0 -gateway 10.1.1.1 -netmask 255.255.255.192
	route add -net 10.1.2.0 -gateway 10.1.1.1 -netmask 255.255.255.192
	route add -net 10.1.3.0 -gateway 10.1.1.1 -netmask 255.255.255.192

Step 3: On host B, add one route that forwards packets to A over link
	I1-I2, and two routes that forward packet to C and D over link
	I3-I4.

Run the following commands on host B:
	route add -net 10.1.0.0 -gateway 10.1.0.1 -netmask 255.255.255.192
	route add -net 10.1.2.0 -gateway 10.1.2.1 -netmask 255.255.255.192
	route add -net 10.1.3.0 -gateway 10.1.2.1 -netmask 255.255.255.192 

Step 4: On host C, add two routes that forward packets to A and B over
	link I3-I4, and one route that forwards packets to D over link
	I5-I6.

commands :
	route add -net 10.1.0.0 -gateway 10.1.1.2 -netmask 255.255.255.192
	route add -net 10.1.1.0 -gateway 10.1.1.2 -netmask 255.255.255.192
	route add -net 10.1.3.0 -gateway 10.1.3.1 -netmask 255.255.255.192

Step 5: On host D, add three routes that forward packet to A, B and C
	over link I5-I6.

commmands:
	route add -net 10.1.0.0 -gateway 10.1.2.2 -netmask 255.255.255.192
	route add -net 10.1.1.0 -gateway 10.1.2.2 -netmask 255.255.255.192
	route add -net 10.1.2.0 -gateway 10.1.2.2 -netmask 255.255.255.192

If you have set up the "test topology" by using the commands list above, you 
can use the following command to check tunnel routing:

on host A, run the following command:
 
	traceroute 10.1.3.1

the result should show the packet travels the correct path. For the 
above command, the result should like this:
traceroute to 10.1.3.1 (10.1.3.1), 64 hops max, 44 byte packets
 1  10.1.1.1 (10.1.1.1)  1.174 ms  0.585 ms  0.558 ms
 2  10.1.2.1 (10.1.2.1)  0.714 ms  0.635 ms  0.644 ms
 3  10.1.3.1 (10.1.2.1)  1.134 ms  0.618 ms  0.558 ms

check the result of "traceroute" from all nodes to all addresses of the
"test topology" created in 4 and 4.1.


5. EXTENDED CAPABILITIES

The networking capabilities in this section are all OPTIONAL; none are
core X-Bone requirements.


5.1 DYNAMIC TUNNEL ROUTING

Static IP routing over IP tunnel interfaces is already REQUIRED above.
The OPTIONAL capability of running dynamic routing protocols (e.g. RIP
[REF?], BGP [REF?]) over IP tunnels is RECOMMENDED, to support complex
virtual topologies and dynamic recovery from link failures.


5.2 IP SECURITY

Another OPTIONAL capability is support for the IPsec security
architecture [3], to secure and authenticate overlay topologies. To
support this OPTIONAL feature of the X-Bone, a platform MUST allow
IPsec transport mode security associations over IP tunnels.

For example, for the platform shown in FIGURE 4, we can set up the 
ESP protocol using des-cbc encription algothm and AH protocol using
hamc-sha1 authenication algorithm to enable IPsec in the middle layer.

Here are the commands to set up IPsec on the first layer IP tunnel 
shown in FIGURE 4:

on both hosts, run
	setkey -F
	setkey -FP

	setkey -c
	add 10.1.0.1 10.1.1.1 esp 1000 -m transport -E des-cbc 
	"12345678" ;
	add 10.1.1.1 10.1.0.1 esp 2000 -m transport -E des-cbc
	"87654321" ;
	add 10.1.0.1 10.1.1.1 ah  3000 -m transport -A hmac-sha1
	"12341234123412341234" ;
	add 10.1.1.1 10.1.0.1 ah  4000 -m transport -A hmac-sha1
	"43214321432143214321" ;
	^D

then on host A, run
	setkey -c
	spdadd 10.1.0.1 10.1.1.1 any -P out ipsec esp/transport/
	10.1.0.1-10.1.1.1/require ah/transport/10.1.0.1-10.1.1.1
	/require; 

on host B, run
	setkey -c
	spdadd 10.1.1.1 10.1.0.1 any -P out ipsec esp/transport/
	10.1.1.1-10.1.0.1/require ah/transport/10.1.1.1-10.1.0.1
	/require; 
	
Next use the commands list in 3.1 to capture the packets transfered
between host A and B, whose format should comform to the templates 
shown below:

	    +--------+--------+---------+---------+
	    | I1->I2 | T1->T2 | AH (...)|ESP(....)|
	    +--------+--------+---------+---------+
	    +--------+--------+---------+---------+
	    | I2->I1 | T2->T1 | AH (...)|ESP(....)|
	    +--------+--------+---------+---------+
          
	FIGURE 6 Packet format over the IPsec'd tunnel between A and B.

For example, run the following commands on host A:
	tcpdump -i em0 |grep 10.1.1.1 # if the ethernet interface is em0
at the same time, on host B, run:
	ping 10.2.0.1

The output on host A should like:
	00:22:12.503543 mul.isi.edu > tlc.isi.edu: 10.1.1.1 > 10.1.0.1: 
AH(spi=0x00000fa0,seq=0x39): ESP(spi=0x000007d0,seq=0x39) (ipip-proto-4)
	00:22:12.503706 tlc.isi.edu > mul.isi.edu: 10.1.0.1 > 10.1.1.1: 
AH(spi=0x00000bb8,seq=0x39): ESP(spi=0x000003e8,seq=0x39) (ipip-proto-4)


5.3 TRAFFIC SHAPING

The X-Bone can impose artificial per-link loss probabilities, queue
length limits and transmission delays on platforms that support it.
This capability is strictly OPTIONAL.



REFERENCES

[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Level", BCP 14, RFC 2119, Mar. 1997.

[2] Perkins, C., "IP Encapsulation within IP," RFC 2003, Oct. 1996.

[3] Kent, S., Atkinson, R., "Security Architecture for the Internet
Protocol," RFC 2401, Nov. 1998.
	  	             
