The Tunnel Setup Protocol (TSP) is a control protocol to establish and maintain static tunnels. The TSP client is used on the host computer to get the tunnel information from the Migration Broker. Once the information is received, it creates a static tunnel on the host operating system.

The TSP client source code is licensed under the GPL. A commercial license is also available.

For a complete description of the TSP client, see the TSP Client Guide.

Executing the TSP client

The TSP client is executed by typing the command tspc which stands for TSP client program. When an IPv6 in UDP in IPv4 tunnel is negotiated, the TSP client program forks itself and runs in the background to carry the keepalive mechanism with the broker. When an IPv6 in IPv4 tunnel is negotiated, the TSP client program exits after setting up the tunnel.

The tspc program has some arguments to the command line, they are described below :

-v
-vv
-vvv

Sets the verbose level and type of debugging information sent to the screen. -vvv gives the most debugging information, such as the TSP XML content.

-i interface_name

Sets the interface name for IPv6 in IPv4 encapsulation.

-u interface_name

Sets the interface name for IPv6 in UDP IPv4 encapsulation.

-s interface_name

Sets the interface name to configure router advertisements of the prefix when the client is a router and has received a prefix.

-f config_filename

Sets the configuration file.

-r number_of_seconds

Sets the retry interval when the TSP connection to the broker is not successful.

-h

Shows the version and list of options.

TSP client configuration

The TSP client is configured using a file called tspc.conf. The configuration file is a text file with comments identified by the “#” character. Each statement has the format variable = value, as in rc.conf files in FreeBSD. The file statements are listed below. Many are optional.

tsp_version

2.0.0

1.0.0
2.0.0

The highest version of the TSP protocol the TSP client supports. The tunnel broker adapts to the protocol version supported by the TSP client. The v6udpv4 and v6anyv4 tunnel encapsulation modes as well as the keepalive mechanism are available in version 2 and higher. The v2 TSP client also adapts to v1.0 brokers.

This value must not be changed by the user.

tsp_dir

Current working directory

string

The TSP client directory which contains the template subdirectory for the shell scripts.

auth_method

any

any
digest-md5
plain
anonymous

The authentication used for the TSP session. Digest-md5 is the most secure, where the passwords are not sent. Plain sends the userid and password. Anonymous sends no userid or password. With any, the TSP client uses the most secure mode based on its capabilities and the broker authentication capabilities. Any is recommended.

client_v4

auto

auto
IPv4 address

The IPv4 address used by the TSP client as its tunnel endpoint source address. When auto is used, the TSP client uses the first IPv4 address given by the operating system.

if_source

string

The interface name on the operating system of the TSP client where the IPv4 address is taken for the IPv4 tunnel endpoint source address.

userid

anonymous

anonymous
string

The user identification string.

passwd

string

The password for the userid.

template

checktunnel
cisco
darwin
freebsd
linux
netbsd
openbsd
solaris
windows

The script file used to create the tunnel. The value is the name of the script file (in the template directory) which will be called by the TSP client at the end of the TSP session, to create the tunnel.

When compiling the TSP client, the template variable is filled in with the correct value for the operating system the client was compiled on.

server

broker.freenet6.net

ip_address
hostname
ip_address:port
hostname:port

The IP address or hostname (full domain name when appropriate) of the broker. A TSP port number can be specified.

retry_delay

0

number

When a TSP connection fails, the number of seconds to wait before retrying to connect to the tunnel broker.

tunnel_mode

v6anyv4

v6v4
v6udpv4
v6anyv4
v4v6

The tunnel encapsulation mode.

if_tunnel_v6v4

string

The tunnel interface on the operating system of the client used for IPv6 in IPv4 encapsulation.

if_tunnel_v4udpv4

string

The tunnel interface on the operating system of the TSP client used for IPv6 in UDP in IPv4 encapsulation.

proxy_client

no

yes
no

When set to yes, the TSP client is not the tunnel endpoint, but is a TSP proxy for the tunnel endpoint. The TSP client is going to remotely configure the tunnel endpoint on the client side.

keepalive

yes

yes
no

When set to yes, the TSP client sends keepalives to keep the tunnel active. This is especially useful to have the Network Address Translation (NAT) keeps its mapping to have a sustainable tunnel over UDP.

keepalive_interval

30

number

This interval in seconds should be smaller than the NAT mapping timeout for UDP. The TSP client sends a keepalive to the broker every keepalive_interval . The broker may force a higher value than the TSP client wants, given a load expected on the broker from a provider.

syslog_facility

string

For a TSP client that supports syslog, specifies the syslog facility.

syslog_level

string

For a TSP client that supports syslog, specifies the syslog level.

host_type

host

host
router

Specifies if the TSP client is a host or a router. In router mode, the TSP client receives a prefix if prefixlen is set.

prefixlen

0

0
48
64

The length of the prefix required by the TSP client.

if_prefix

string

The interface in the operating system of the TSP client used to send router advertisements with the prefix received from the broker.

dns_server

string

The fully qualified domain name of the DNS server for the reverse DNS delegation of the prefix.

The web interface is used to create a script from the information gathered on a form. Most of the information is mandatory, except the prefix fields. A short explanation is given below for each of the fields.

• IPv4 address
  IPv4 address of the client computer. This field is set by default to “auto” and need to be changed only when the address cannot be found automatically. This happens in some very specific cases, the first being when the form is not executed on the tunnel endpoint host (for example when a Cisco router is the endpoint). A second case is for a computer having more than one interface (multihomed) and the detected interface is not the correct one. The last case would be for a single user behind a NAT redirecting protocol 41 to the host. In that case, the public address of the NAT must be used.

• Username
  Default value “anonymous”. Using the default will create an anonymous tunnel, for which the IPv4 is used to identify the user. If the IPv4 address changes, the IPv6 address would change as well. To keep a permanent IPv6 address and prefix, use an username existing on the broker or create a new one.

• Prefix (optional)
  Check this option if an IPv6 prefix is requested. Only /48 prefixes may be delegated using the web interface.

• Prefix interface (optional)
  Name of the interface on which the router advertisements will be sent. Usually, this is an interface facing the internal network. For example, it may be “eth1” or “vr0” in a Linux or BSD environment.

• Operating system
  Operating system of the tunnel endpoint host. This is used to determine which type of script is built.

• Tunnel interface
  Interface name of the tunnel. It is automatically choose according to the operating system, but may be changed for a specific name. This is useful when defining a named interface or when more than one tunnel is configured on the host. For example, the tunnel interface name would default to “sit0” on Linux or “tun1” on a FreeBSD host.

The web interface provides a way to create automatically a new user on the Migration Broker. A confirmation email containing a generated password is sent to the specified email address.

• Username
  Requested user identification string. It must be at least 8 characters long and be composed of alphanumeric characters only. Letters, both lowercase and uppercase, number and dashes (“-”) are allowed. The username is also used to create the DNS entry of the tunnel, using the format “username.tunnelbroker.net”, where the name of the tunnel broker is configured by the administrator.

• Email address
  This must be a valid email address. The account creation confirmation and the password will be sent to that address.