Copyright © 2009, 2010 Internet Systems Consortium, Inc. ("ISC")
Table of Contents
Table of Contents
ISC AFTR implements a Dual-Stack Lite (DS-Lite) Address Family
Transition Router (AFTR), as described in
draft-ietf-softwire-dual-stack-lite-06.txt
.
This technology allows end-users with IPv4-only hosts or
IPv4-only applications to communicate with IPv4 peers over an
IPv6-only network.
A DS-Lite deployment includes at least one AFTR in the ISP's network core, and one Basic Bridging BroadBand element (B4) at each customer premises.
DS-Lite is in the process of being standardized by the Softwire working group of the IETF. ISC AFTR actively tracks the current specification, but users should be aware that there may be changes to the specification before it is finalized as an RFC. As such, this should be considered a work in progress, for testing and experimentation only.
Table of Contents
This section provides a "quick start" to using ISC AFTR in the simplest configuration. For full build and configuration details, see chapter 3.
OS: Linux or FreeBSD. Kernel must be built with IPv6 and tun(4).
Linux kernel version must be greater than 2.6.26, to
correct a small-packet-drop problem in
tunnel46_rcv()
.
CPU: No special requirement. Note that performance is bound to the kernel/user context switch latency, so processor speed is the single biggest determiner of performance.
Memory: No special requirement.
Unpack the distribution.
tar zxvpf aftr-1.1.tar.gz
This creates a a directory named aftr-1.1
,
which we refer to as $src_path
hereafter.
cd $src_path
./configure
make
This creates an executable file aftr
,
which is the AFTR daemon program. It is expected to be run
in the same directory as the configuration
file aftr.conf
and the script
file aftr-script
(there is
no make install
step).
An example aftr.conf
file is located in
the conf
directory.
The only required parameters are those in section 1 of the config file, and are briefly described here. The full set of configuration commands is described in section 3.3.
address endpoint 2001::1
This is the IPv6 address of the AFTR. Specifically, it is the endpoint of the IPv6 tunnel between the B4 and the AFTR.
This address is associated with the tunnel interface, but is
not explicitly assigned to it; instead, the
aftr-start()
portion of the script file
creates a covering route to the tunnel interface.
address icmp 192.0.0.1
This is a global IPv4 address used as the source for ICMP errors sent from the AFTR to the Internet. The actual address doesn't matter, as no one should try to respond to an ICMP packet.
acl6 2001::/48
This is an Access Control List for IPv6 traffic from the B4 to the AFTR. It is the IPv6 prefix that encloses the portion of the provider's network that is served by this AFTR. If the AFTR serves customers served by multiple disjoint IPv6 prefixes, there can be multiple acl6 commands.
pool 198.18.200.1
This is a global IPv4 address in the service provider's network, which will be used as the NATted address for packets sent to the Internet.
Multiple pool addresses may be defined, and restrictions may be placed on port ranges to use for NAT bindings.
The aftr executable requires a
startup/shutdown script. When aftr
starts up, it calls the script's start
function to bring up the tunnel interface, and set up routes
to the interface.
When aftr shuts down, it calls the
script's stop
function to bring down
the tunnel interface, and remove all routes to the
interface.
By default, the script file is
named aftr-script
, and resides in the
same directory as the aftr
executable
file.
The conf
directory contains example
aftr-script
files for Linux and FreeBSD.
First, make sure your interfaces are configured correctly, and IPv4 and IPv6 forwarding are enabled. On Linux, you may also want to disable netfilter for performance reasons.
Note: Linux
netfilter tables need to be flushed ('iptables
-F
' and 'ip6tables -F
')
explicitly.
To start AFTR, run the aftr
executable
in the same directory as the aftr.conf
configuration file and the
aftr-script
script file. For other
startup options, see section 3.2.
AFTR normally starts as a daemon process. To access the control interface, telnet to localhost port 1015. AFTR can also be started in foreground mode, which gives immediate access to the control interface. For control commands, see section 3.4.
The B4 is the customer-side DS-Lite tunnel initiator. In the most common use case, it is a home gateway, also referred to as a CPE (Customer Premises Equipment).
For testing and demonstration purposes, we have used home gateways (e.g., Linksys WRT54GL) running OpenWrt, a Linux distribution tailored for home gateways and related devices. B4 functionality can also be built into general-purpose computers, and has been demonstrated in FreeBSD and Ubuntu Linux. In all of these cases, the important thing to keep in mind is that the B4 device is the IPv4 default router for all hosts behind it.
There are no special requirements above what one might expect for a home gateway. The only added functionality that makes it a B4 is to set up an IPv4-in-IPv6 tunnel, and to encapsulate/decapsulate all IPv4 traffic to/from that tunnel; and all home gateways that can run OpenWrt can do that.
Note: More information, and prebuilt images for WRT54G
devices, can be found at
http://www.kangaroo.comcast.net
The following instructions are for building an OpenWrt image from sources.
Get OpenWrt sources from
https://dev.openwrt.org
Copy the contents of the
conf/b4-openwrt
directory to a new
directory named
openwrt/version
/package/dhcp4
Go to the openwrt/version
directory, run make menuconfig, and
make the following selections:
Select 2.6 kernel: Target System > Broadcom BCM947xx/953xx (or your target architecture)
Deselect busybox udhcp client: Base system > busybox > Configuration > Networking Utilities
Select dhcp4-client and dhcpv6: Network > isc-dhcp
Select the non-busybox version of ip: Network > ip
Select ip6-tunnel: Kernel modules > Network Support > kmod-ip6-tunnel
draft-ietf-softwire-dual-stack-lite-06.txt
says:
In order to configure the IPv4-in-IPv6 tunnel, the B4 element needs the IPv6 address of the AFTR element. This IPv6 address can be configured using a variety of methods, ranging from an out-of-band mechanism, manual configuration or a variety of DHCPv6 options.
In order to guarantee interoperability, a B4 element SHOULD implement the DHCPv6 option defined in [I-D.ietf-softwire-ds-lite-tunnel-option].
The DHCP server does not have to run on the same computer as the AFTR, but it must be reachable via normal DHCP request channels from the B4, and it must be configured with the AFTR address.
On the server, add something like the following
to dhcpd6.conf
:
option dhcp6.dslite code 54 = ip6-address;
option dhcp6.dslite 2001::1;
NOTE: For testing, we use an unassigned DHCPv6 option code. DO NOT use this option code in production, as it is likely to change when the draft reaches RFC status.
The IPv6 address must be the same as the
address endpoint
option
in aftr.conf
.
On the B4, dhclient6.conf
contains the
following to request the option:
option dhcp6.dslite code 54 = ip6-address;
also request dhcp6.dslite;
If you are using the supplied OpenWrt dhcp4 package,
dhclient6.conf
already contains these
lines, and dhclient-script
contains a
few extra lines to set up the tunnel and create a default
IPv4 route to it.
draft-ietf-softwire-dual-stack-lite-06.txt
recommends configuring the B4 with a DNS proxy resolver,
which will forward queries to an external recursive server
over IPv6 (this server may be co-located on the AFTR box).
To configure the B4 with an upstream resolver address, add something like the following to dhcpd6.conf:
option dhcp6.name-servers 3ffe:501:ffff:100:200:ff:fe00:3f3e;
Note: if the B4 uses dnsmasq as a DNS proxy, then the used version should be checked. Only recent versions are RFC 5625 compliant; in particular the EDNS0 UDP size can be limited to 1280 bytes instead of the recommended 4096 bytes.
It is easy to fix this last point by configuration:
Add in /etc/config/dhcp
in the
dnsmasq section the line:
option ednspacket_max 4096
If dnsmasq is launched directly, add these arguments:
-P 4096
Table of Contents
Here is the list of configuration flags
(i.e., CFLAGS
):
AFTRCONFIG
: config file path
(default aftr.conf
)
AFTRSCRIPT
: script file path
(default ./aftr-script
)
AFTRDEVICE
: name of the interface/device
(default tun0
)
AFTRPORT
: port for TCP control channels
(default 1015)
AFTRFACILITY
: syslog facility
(default LOG_LOCAL5
)
AFTRLOGOPTION
: openlog option
(default LOG_NDELAY
)
TRACE_NAT
: enable tracing of NAT
entry creation/deletion (default is undef
,
i.e., only tunnels and buckets are traced)
NOPRIVACY
: trace all addresses and ports
in NAT entry tracing (default is undef
)
SIGNSHDR
: define it to add a signature
header in structures (default is undef
)
PCPD_STATE
: define the PCP daemon
state (default is 0
, i.e., disabled)
ENCAP_TO_PCPD
: define the port of
the UDP/IPv4 socket used for aftr to pcpd communication
(default is 10151). Note if it is a privileged port then
pcpd shall be run by root.
ENCAP_TO_AFTR
: define the port of
the UDP/IPv4 socket used for pcpd to aftr communication
(default is 10150).
SIZES
: define it to print sizes of
principal data structures (default is undef
)
USE_TUN_PI
: use the tun_pi struct in tun
interface/device I/O
(required on some platforms, including RedHat and CentOS v5,
for IPv6 support)
notyet
: some unfinished and arguable
features (undef
of course)
Included inline aftr (8)
aftr — Address Family Transition Router
aftr
[-g
] [-t
] [-c
] [config-file
-d
] [device-name
-p
] [port-number
-s
] [script-file
-u
]socket-name
By default the aftr process becomes a daemon,
-g
keeps it in foreground with logging to stderr.
-t
can be used to check a configuration file.
config-file
The aftr daemon requires a configuration file.
By default it is named aftr.conf
, and is
located in $src_path
. The
AFTRCONFIG
environment
variable and the -c
argument give an
alternate path. A sample configuration file is provided in
$src_path/conf/aftr.conf
(OS independent).
device-name
Linux: The aftr process opens /dev/net/tun
and set the name of the interface to the
AFTRDEVICE
environment
variable or the -d
command line argument value
or by default 'tun0'.
FreeBSD: The aftr process opens /dev/tunXXX
from the AFTRDEVICE
environment variable or
the -d
command or by default
/dev/tun0
. The 'auto' value uses the first
free /dev/tunXXX
device.
The tunnel interface/device specification can be a full path
(/dev/...
), a relative name or a number.
port-number
Use the port-number
for TCP control channels. Default is 1015.
script-file
The aftr daemon executes a shell script file
with start
on invocation.
This is named by default aftr-script
and
located in $src_path
. The
AFTRSCRIPT
environment variable and
the -s
argument give
an alternate path. This file could be even empty, but must exist.
The aftr daemon will eventually execute
the shell script file with the stop
argument
before it exits.
The conf
directory provides examples
(including the configuration files used in our
testbeds). aftr-script.freebsd
variant is for a FreeBSD based AFTR.
socket-name
As an alternative to TCP over IPv4 and IPv6 with localhost
control channels, the aftr process can
accept PF_UNIX stream socket control channel on the
socket-name
.
Included inline aftr-conf (5)
aftr.conf
— configuration file for aftr
aftr.conf
The aftr daemon requires a configuration file.
By default it is named aftr.conf
, and is
located in $src_path
.
The AFTRCONFIG
environment
variable and the -c
argument give an alternate path.
Sample configuration files are provided in
$src_path/conf/aftr.conf
(OS independent).
The configuration file consists of a set of one-line configuration commands. Commands are not case sensitive. Any line beginning with '#' or whitespace is ignored as a comment.
Configuration and interactive commands belong to sections:
section zero is for global parameters which must be defined before anything else when they are not kept to their default values, for instance defmtu.
section one is for required parameters, for instance pool.
section two is for reloadable parameters, for instance nat.
interactive only commands are in the section three.
Only the section one commands are required; reasonable defaults are
provided for all other configuration parameters. See
conf/aftr.conf
for an example of a minimal
configuration file.
Alias of default tunnel auto on|off
.
size
Specifies the bucket size. Compile time options are
[TCP|UDP|ICMP]BUCKSZ
,
default values are: TCPBUCKSZ
10,
UDPBUCKSZ
8, ICMPBUCKSZ
3.
Minimum is 0 (excluded) and maximum 255.
decay
Specifies decay values for 1, 5 and 15 mn rates. Compile time
options are DECAY{1,5,15}
, default values are:
DECAY1
exp(-1/60), DECAY5
exp(-1/300), DECAY15
exp(-1/900).
Minimum is 0.0 and maximum 1.0.
Enables or disables equalizing the length of IPv6 fragments. Default is off.
lifetime
Specifies the lifetime of fragments in reassembly queues. Compile
time option is FRAG_LIFETIME
, default value is
30 seconds.
Minimum is 0 (excluded) and maximum 1200.
maxcount
Maximum number of entries in reassembly queues ('in' is IPv4 from
clients to the Internet, 'out' is IPv4 from the Internet to clients).
Compile time options are FRAG{6,IN,OUT}_MAXCNT
,
default values are 1024. Minimum is 0 (included so it is possible to
disable reassembly), maximum is 16535.
lifetime
Specifies the lifetime of expired NAT entries in the hold queue.
Compile time option is HOLD_LIFETIME
, default
value is 120 seconds. Minimum is 0 (included), maximum is 600.
lifetime
Specifies the lifetime of dynamic NAT entries ('closed' is for closed
TCP sessions, 'retrans' is used for response not yet received).
Compile time options are
[TCP|CLOSED_TCP|UDP|ICMP|RETRANS]_LIFETIME
,
default values are TCP (600), closed TCP (120, aka 2*MSL), UDP (300),
ICMP (30), retrans (10). Minimum is 0 (excluded), maximum 36000
(10 hours).
Specified the PCP daemon state. Compile time option is
PCPD_STATE
. Default is disable.
When enable (or encapsulate): the creation of new dynamic
mappings must be enabled by the PCP daemon (using the
dynamic command). In the encapsulate state
the aftr daemon works as a proxy with the PCP daemon
for encapsulated PCP packets.
min
-max
Specifies the default port ranges for PCP port forwarding entries.
Compile time options are [TCP|UDP]_[MIN|MAX]PPCP
,
default values are 0, i.e., this feature is disabled.
Minimum is 0 (1 when not disabled), maximum 63535.
min
-max
Specifies the default port (or id for icmp echo) ranges for pools.
Compile time options are [TCP|UDP]_[MIN|MAX]PORT
,
ICMP_[MIN|MAX]ID
, default values are
TCP_MINPORT
2048, UDP_MINPORT
512, ICMP_MINID
0, TCP_MAXPORT
65535, UDP_MAXPORT
65535,
ICMP_MAXID
65535.
Minimum is 1 (0 for ICMP), maximum 63535.
IPv4_prefix
/prefix_length
Add a private prefix to IPv4 ACLs. The default is RFC 1918 prefixes and the 192.0.0.0/29 from the ds-lite draft.
Enables or disables on-the-fly tunnel creation. Default is on.
This enables or disables TCP MSS patching on packets going from and to tunnels. Can be overridden by per-tunnel configuration. If any tunnels are explicitly configured, this must be specified before them. Default is off.
mtu
Specifies mtu
as the default IPv6 MTU of
tunnels. Can be overridden by per-tunnel configuration.
This specifies the policy for packets from the Internet which are too big (i.e., they don't fit in one IPv6 encapsulating packet) and are marked as “don't fragment”. 'On' means a ICMPv4 packet too big error is returned to the source, 'off' the packet just go through, and 'strict' the packet is dropped with a ICMPv4 error. Default is on (i.e., the packet is encapsulated into some IPv6 fragments and a ICMP error is returned for path MTU determination).
maxcount
Specifies the maximum number of reassembly queue entries per tunnel.
Compile time options are FRAGTN[46]_MAXCNT
,
default values are FRAGTN6_MAXCNT
16,
FRAGTN4_MAXCNT
64. Mininum is 0 (included for
reassembly disable), maximum is 255.
maxcount
Specifies the maximum number of NAT entries per tunnel. Compile time
options are [TCP|UDP|ICMP]_MAXTNATCNT
, default
values are TCP_MAXNATCNT
2000,
UDP_MAXNATCNT
200,
ICMP_MAXNATCNT
50.
Minimum is 0 (included), maximum is 65535.
limit
Specifies the maximum rate of dynamic NAT creation per second.
Compile time options are [TCP|UDP|ICMP]_MAXTNATRT
,
default values are TCP_MAXNATRT
50,
UDP_MAXNATRT
20,
ICMP_MAXNATRT
5.
Minimum is 0 (included), maximum 255.
IPv4_address
This removes the IPv4 private prefix with the IPv4 address. It is an error to have no private prefixes.
Alias of default tunnel mss on|off
.
mtu
Alias of default tunnel mtu
.
mtu
Alias of default tunnel toobig on|off|strict
.
Alias of default fragment equal on|off
.
quantum
Specifies the number of packets dealt with in one main loop round
(i.e., the size of a slice of work). Compile time option is
QUANTUM
, default value is 20. Minimum is
2 (included), maximum is 255.
IPv6_prefix
/prefix_length
This adds an (accept) entry in the IPv6 ACL. Note for a regular IPv6 packet the ACL is checked only when no tunnel was found, and the default is “deny all”, so at least one acl6 entry in the configuration file is required when the auto tunnel option is on.
IPv6_address
IPv6_address
is the AFTR endpoint
address of the Softwire tunnels.
If the DHCPv6 ds-lite option is used, this address must match the
advertised address.
It is a required command: it absolutely must be present in the
aftr.conf
file; the aftr
daemon will not start without it.
IPv4_address
IPv4_address
is a global IPv4 address
used as the source for ICMP errors sent back to the Internet (i.e.,
the ICMPv4 errors will look like returned from an intermediate
router that has this address). It is a required command.
IPv4_address
[tcp|udp|echo min
-max
]This specifies a global IPv4 address that will be used as the source address of NAT'ed packets sent to the Internet. Multiple global addresses can be specified, at least one is required.
The optional part limits the port (or id) range used for the protocol with the global IPv4 address in dynamical bindings (i.e., not static or A+P bindings which can use the reserved ports outside the range).
IPv4_address
tcp|udp min
-max
This is a clone of the previous pool command but specifies the port ranges for port forwarding entries managed by the PCP server. Only possible conflicts with the dynamic port ranges are checked.
IPv6_remote
[IPv4_src
]
This specifies an IPv4-in-IPv6 tunnel configuration.
IPv6_remote
is the remote (ds-lite
client) IPv6 address of the tunnel. Either the tunnel is associated
with a source address in a round robin way or it is associated to
the specified IPv4_src
.
IPv6_remote
tcp|udp IPv4_src
port_src
IPv4_new
port_new
This defines a static binding/NAT entry for the client
behind the tunnel at IPv6_remote
.
*_src
are the source IPv4 address
and port at the tunnel side of the NAT,
*_new
are the source IPv4 address
and port at the Internet side of the NAT.
IPv4_new
should be a reserved source
NAT address, port_new
must not be inside
a dynamic port range.
IPv6_remote
tcp|udp IPv4
port
This defines a Port-Range Router/A+P null NAT entry for the
client behind the tunnel at IPv6_remote
.
IPv4
and port
are the source IPv4 address and port at the tunnel side of the NAT.
They stay unchanged both ways: this entry is used to check
authorization and perform port routing.
IPv6_remote
IPv4
/prefix_length
This defines a No-NAT tunnel for the client behind the tunnel at
IPv6_remote
and the prefix
IPv4
/prefix_length
.
No translation is performed for matching packets.
IPv6_remote
on|off
This enables or disables TCP MSS patching on packets going
from and to the tunnel of IPv6_remote
.
Default is off.
IPv6_remote
mtu
This changes the IPv6 MTU of the tunnel of
IPv6_remote
to
mtu
.
IPv6_remote
on|off|strictPer-tunnel configuration of the too big policy.
level
]Specifies the debug level. Default is 0. If set to non 0, verbose log messages will be dumped to stderr. The higher the level is, the noiser the logs are. At present, the meaningful levels are 1 (log tunnel creation), 3 (log packet reads and writes), and 10 (function entry tracing). If the level is omitted, it is set to 1.
IPv6_remote
[IPv4_src
]
Create when it doesn't already exist an IPv4-in-IPv6 tunnel,
returns in all cases the description of the tunnel entry. This
command should be used by tools managing temporary port forwarding.
IPv6_remote
must be acceptable for IPv6
ACLs.
IPv6_remote
tcp|udp IPv4_src
port_src
IPv4_new
port_new
Create when it doesn't already exist a static binding/NAT entry. This command should be used by tools managing temporary port forwarding. The tunnel must exist.
Included inline aftr-commands (5)
aftr.command
— interactive commands for aftr
aftr.commands
The aftr daemon runs in the background. After it starts, it can be controlled interactively from a control channel (aka. a session).
All of the reloadable configuration commands can be allowed to run from the command line, to add or change configuration. In addition, the following commands can be run interactively.
Call abort(3) to create a core file. Please try to use it only on forked processes.
xxx
Echo the command. This can be used for an external tool to synchronize with the AFTR daemon.
Fork the aftr process. In the parent the current session is closed (so after this command you'll talk only to the child) and other activities, including packet forwarding, are continued. In the child all file descriptors at the exception of the current session are closed.
This command should be used before to execution an expensive and atomic operation like list commands or some debug commands, and of course the abort command.
List available or all commands.
Orderly kill the aftr process.
file
Redirect the input of the current session from the content of the file. This is done in an atomic way (i.e., there is no other activity during the operation) but exists if a command fails.
Obsolete, use session close (for closing the current session) or kill (for killing the process).
Reboot the whole process.
Reload the section two part of the config file. This is sliced with the packet forwarding, but not with session reading (so you can't execute a command until reload is finished).
The reload process uses a generation system: static NAT, PRR/A+P and no-NAT entries in the reloaded file are put in the next generation. If the reload succeeds, global entries in older generations are garbaged collected, if it fails new generation entries are backtracked to the previous generation. Garbage collection and backtracking are sliced with the packet forwarding, another reload command is forbidden until they finish so a reload flushes the input buffer of the current session.
Aliases of debug dropped and debug stat, display dropped packet and general statistics.
Returns LOG: alive
.
Performs some sanity checks on structures. Reserved to expert usage on a forked process (or better core file debugged with gdb). Note it uses recusive deep structure walking so can eat a lot of stack.
Disable per-tunnel debug counters. Optionally clear them.
This displays the dropped packet statistics with reasons.
addr
Enable per-tunnel debug counters for the tunnel with
addr
remote IPv6 address.
Note the counters can be incremented only when the
involved tunnel is known, for instance, only after reassembly.
This displays the list of IPv4 or IPv6 fragments awaiting reassembly.
addr
This displays information about a single fragment or
fragment chain.
add
> is the memory address of the
fragment structure (from a previous debug
fragment command).
This displays some statistics about the various hash tables (fragment, nat, and tunnel).
This displays some information about the nat hash table and entry table.
addr
This displays detailed information about a single nat binding.
addr
is the memory address of the nat
structure (from a previous debug nat command).
This displays the list of no-nat tunnel entries.
This displays the global IPv4 addresses that will be used for NAT mapping.
This displays the control channel session types with the number of active sessions.
This displays some general statistics about packets in and out. If per-tunnel debug counters are enable, displays them.
This displays some information about the tunnel table.
IPv6_remote
This displays some information about a single tunnel.
IPv6_address
This removes the IPv6 ACL entry with the IPv6 address.
IPv6_remote
tcp|udp IPv4
port
This removes a static or dynamic NAT binding.
IPv6_remote
This removes a no-nat tunnel entry.
IPv4_address
Look at zone zero configuration commands.
IPv6_remote
tcp|udp IPv4
port
This removes a Port-Range Router/A+P null NAT binding.
IPv6_remote
This removes a tunnel and all NAT bindings associated with it.
List IPv6 ACLs.
List all the default values which can be set by a 'default'/'global' command.
List the NAT entries in the configuration file format. Default is to list only the configured ('conf') NAT entries. 'global' lists the the configured global (i.e., not by a session) active (i.e., not to be garbaged collected after a reload) NAT entries.
List all the No-NAT tunnel entries in the configuration file format.
List the NATted source addresses with current PCP ranges in the configuration file format.
List the NATted source addresses with current port ranges in the configuration file format.
name
|generation
]
List the static NAT, PRR/A+P and no-NAT entries created by
the current session or the session
with name
or
with generation
(note these
entries will be flushed when the session will be closed so
this command can be used to get them in order to include
them in the config).
List the tunnel entries in the configuration file format, including specific MTU (if different from the default MTU).
These commands deal directly with sessions (aka. control channels).
name
|generation
]Close the current or designed session. Delete all the static NAT, PRR/A+P and no-NAT entries created by the current session and which were not promoted to global/permanent entries by a reload.
Enable/disable the section two configuration commands. By default configuration commands must go to the config file.
Enable/disable the creation of new dynamic mappings. Used by the PCP daemon and default and reset on session close to off.
Log errors or don't for the current session. Default is on.
name
]Display or set the name of the current session. The stdio initial session is statically named 'tty'.
Log tunnel removal or don't to the current session. Default is off.
Table 3.1.
Name | Section | Syntax |
---|---|---|
abort | interactive | |
acl6 | one or two |
IPv6 /prefix_length
|
address | one | endpoint IPv6 |icmp IPv4
|
autotunnel | zero | on|off |
bucket | zero | tcp|udp|icmp size size
|
debug | >= two | set|enable|...|tunnel |
decay | zero | 1|5|15 decay
|
default | zero | fragment|hold|...|tunnel |
defmss | zero | on|off |
defmtu | zero | mtu |
deftoobig | zero | on|off|strict |
delete | == add | acl6|nat|nonat|private|prr|tunnel |
echo | interactive | xxx |
eqfrag | zero | on|off |
fork | interactive | |
help | interactive | [all] |
kill | interactive | |
list | interactive | acl6|default|...|tunnel |
load | interactive | file |
mss | >= two |
IPv6 on|off |
mtu | >= two |
IPv6 mtu
|
nat | two |
IPv6 tcp|udp IPv4_src ... |
nonat | two |
IPv6 IPv4 /prefix_length
|
noop | interactive | |
pcp | one |
IPv4 tcp|udp min -max
|
pool | one |
IPv4 [tcp|udp|echo min -max ] |
prr | two |
IPv6 tcp|udp IPv4 port
|
quantum | zero | quantum |
quit | interactive | |
reboot | interactive | |
reload | interactive | |
session | interactive | close|config|dynamic|log|name|notify |
show | interactive | dropped|stat |
toobig | >= two |
IPv6 on|off|strict |
try | two | tunnel ... | nat IPv6 tcp|udp IPv4_src ... |
tunnel | two |
IPv6 [IPv4 ] |
Table of Contents
Errors, debug messages, traces, etc, are logged through syslog with aftr as the program name.
The default facility is LOG_LOCAL5
(can be
changed at compile time by setting AFTRFACILITY
),
the default openlog()
option is
LOG_NDELAY
(can be changed at compile time by
setting AFTRLOGOPTION
, for instance to add
LOG_PID
). Levels are:
critical errors (i.e., the process must be rebooted)
to LOG_CRIT
error conditions (i.e., bad packets, not critical
memory allocation failures, bad commands, etc) to
LOG_ERR
warnings to LOG_WARNING
informational messages (including I/O logs) to
LOG_INFO
debug messages (cf. debug set xxx) to
LOG_DEBUG
trace messages (see next section) to
LOG_NOTICE
Trace messages are:
tunnel add|del client_IPv6
seconds
bucket
client_IPv6
natted_IPv4
tcp|udp
[#port
]+
If TRACE_NAT was defined at compile time (default is undefined):
if NOPRIVACY is kept undefined:
seconds
nat add|del
client_IPv6
tcp|udp
natted_IPv4
port
if NOPRIVACY is defined:
seconds
nat add|del
client_IPv6
tcp|udp
client_IPv4
client_port
natted_IPv4
natted_port
destination_IPv4
destination_port
The aftr process needs the root privilege to open the tunnel interface/device. The TCP over IPv4/IPv6 control channels are bound to localhost so are limited to the local node. There are many tools which provide a secure connection forwarding, for instance ssh -L. The PF_UNIX control channel relies on standard file system permissions (cf. umask), it should be used for finer control than node access.
The source address of encapsulated IPv4 in IPv6 packets must be a private address. The list of IPv4 private prefixes is initialized to RFC 1918 prefixes and the unpublished I-D, it is manageable by zone zero commands. IPv6 ACLs filter incoming IPv6 packets.
The try commands are protected against not authorized tunnel creation, i.e., both IPv6 and IPv4 ACLs are applied to try command arguments.
Unlimit the core dump size if you'd like to get core file on
crashes or with the abort command. On Linux twist the core
naming to something better than core
(cf. core(5)).
Please keep the binary associated to core files. As
the fork command is fun but eats memory put
enough memory in the aftr box...
When the aftr process is not (yet) crashed but seems no longer to forward packets:
go to an open session (try to keep on in case the alternative fails) or if none open a new one
check if it is responsive using the noop
(answer LOG: alive
), if not
try to get a core file (attach in gdb and use
gcore), kill it
(another way to get a core file with ^\ /
kill)
and relaunch it
if not in a hurry try to understand the issue with show stat and show dropped
open a second session, send fork to get a child process where you can use extensive debug, including gdb, on it. If you don't know or you can't understand, abort the child process to get a core file.
update the config file if needed, reboot the parent/main process (it will lose all the state and restart from the beginning)
Summary for the busy operator:
noop -> nothing: go to the shell to kill and relaunch it
noop -> expected message: open another session, send fork, wait for the child pid message, send abort on this new session. On the previous session (where you sent noop), send reboot
Table of Contents
The "XML interface" is a way for service providers to programmatically manage static port mappings on behalf of their customers.
For instance, the service provider might have a web portal, tied into the provisioning system, through which a customer could request a small number of static port mappings. The provisioning system would send an XML-encoded request to the AFTR that is serving that customer, and the AFTR would send back an XML-encoded reply.
The xml
subdirectory contains a
specification for the remote configuration protocol, together
with a server that runs on the AFTR box, and an example client
that runs on the provisioning system.
The server and client communicate over either HTTP or a
plain TCP socket. By default, they use HTTP. To change to
TCP socket, you must edit both xmlconf.py
and
xmlclient.py
, commenting out the
line TRANSPORT = 'http'
, and
uncommenting the line TRANSPORT = 'socket'
.
Included inline xmlconf (8)
xmlconf.py — remote configuration daemon for aftr
xmlconf.py
[-l
] [listening-addr
-p
] [listening-port
-r
] [remote-addr
-c
] [config-file
-v
]
listening-addr
This specifies a local address on which to listen. If not specified, it listens on all local addresses.
listening-port
This specifies a local port on which to listen. Defaults to port 4148 for HTTP transport, or port 4146 for socket transport.
remote-addr
This specifies a single address that the server will listen to. The server should only get configuration requests from the provisioning system, at a known address, so this is a simple form of access control. Use of this option is not required, but it is recommended.
config-file
This specifies the name and location of
the aftr configuration file. For
obvious reasons, this option MUST specify the same file
that is used to configure the running
aftr daemon. Default is
./aftr.conf
.
This enables run-time debugging messages. It should not be used in production, but it can help to debug or monitor interactions between xmlconf.py and the aftr daemon.
Included inline xmlclient (8)
xmlclient.py — remote configuration client for aftr
xmlclient.py
aftr-addr
[command
]
user-ipv6
protocol
src-ipv4
src-port
nat-ipv4
nat-port
This requests the aftr to create a port mapping.
user-ipv6
nat-ipv4
This requests the aftr to create a tunnel entry,
using nat-ipv4
as the natted
IPv4 address for all future port mappings on this tunnel
(dynamic as well as static).
user-ipv6
protocol
src-ipv4
src-port
nat-ipv4
nat-port
user-ipv6
protocol
src-ipv4
src-port
protocol
nat-ipv4
nat-port
These three forms of the delete
command all request the aftr to delete a port mapping.
The mapping can be fully specified (first form), but a
mapping can also be uniquely identifed by either internal
parameters (second form) or external parameters (third
form).
user-ipv6
This requests the aftr to delete all port mappings (dynamic as well as static) and other state associated with the given tunnel address. This is often done prior to moving the customer to a new natted IPv4 address.
This requests the aftr to remove all static port mappings and configured tunnel entries. Note that this is a very drastic action, and should only be undertaken if (for example) the aftr configuration is seriously out of sync with the provisioning system.
user-ipv6
This requests the aftr to report all static port mappings associated with the given tunnel address.
This requests the aftr to report all static port mappings, and all configured tunnels without static port mappings.
If no commands are given on the command line, xmlclient.py will read commands from stdin. This allows the provisioning system to accumulate changes for a given AFTR, and send them all at once.
In general, it is probably easier for the provisioning system to send requests immediately, and get replies immediately. However, some operators may prefer to batch up requests, and this method sends multiple requests over an open connection, without having to establish a connection for each request.
Example:
xmlclient.py 2001::500 <script
where script
contains:
create 2001::525a:8c5a:30d4:e36e tcp 192.168.0.88 6265 198.18.200.174 5005
create 2001::835c:1eff:8d66:22fc tcp 192.168.1.138 3877 198.18.200.121 5572
create 2001::e3:9a2f:8abf:40de:2d87 udp 192.168.0.92 7356 198.18.200.149 5547
Table of Contents
In a world where IPv4 address sharing is the norm, one might imagine that some customers would be willing to pay a little more for a full, non-shared global IPv4 prefix or address (i.e., a /32 prefix).
In this case, the customer would perform the NAT function in his own CPE, but he would still have to tunnel IPv4 traffic through the provider's IPv6-only network to the AFTR.
As yet, there is no defined signalling for the client to request a non-shared IPv4 prefix, or for the server to establish a non-natted tunnel. All configuration must be done manually, on both the B4 and the AFTR.
On the B4, the tunnel will still have to be set up, and all IPv4 traffic will have to be routed to the tunnel, but only after the local NAT function is performed.
On the AFTR, a nonat command will have
to be entered in aftr.conf
, and a
route to the customer's IPv4 prefix will have to be
created in
aftr-script
.
A+P is a different approach to IPv4 address sharing, described
in draft-ymbk-aplusp-05.txt
. In this
scenario, each customer is provisioned with a global IPv4
address, but only a restricted range of ports he can use
within that address.
Similar to the no-nat case above, the customer would perform the NAT function within his own CPE (ensuring that all port mappings are within the provisioned range), but he would still have to tunnel IPv4 traffic through the provider's IPv6-only network to the AFTR.
As yet, there is no defined signalling for the client to request an A+P assignment, or for the server to establish a non-natted tunnel. All configuration must be done manually, on both the B4 and the AFTR.
On the B4, the tunnel will still have to be set up, and all IPv4 traffic will have to be routed to the tunnel, but only after the local NAT function is performed.
On the AFTR, a prr command will have to
be entered in aftr.conf
, and a route
to the customer's IPv4 address will have to be created in
aftr-script
.
In production use, an AFTR will have a pool of global IPv4 addresses that are used exclusively for natted port mappings.
However, for testing or demonstration purposes, you may want to deploy AFTR on a box with only one IPv4 address:
This address is used for standard services of the box.
This address is used by application proxies etc., in particular the DNS caching server.
This address is used to NAT traffic, i.e., for the AFTR function.
The address can be dynamic (provisioned by DHCP), but must not change during an AFTR process run.
The AFTR box is configured to use the eth0 interface on the WAN side, the eth1 on the LAN side. The AFTR process itself is configured as usual, but it uses a pseudo-public address (i.e., an address which is not recognized as private but in fact is a reserved public address, the first to avoid confusion, the second to avoid a collision with a real public address).
Netfilter/iptables is used to map the pseudo-public address to the real public address. Port forwarding is a bit more complex, as the port range used for port forwarding must be port-forwarded (destination natted in netfilter/iptables terms) as-is (i.e., not changing ports) to the pseudo-public address. Of course there is nothing which can be done for no-NATs or for A+P/PRR as the first router/NAT of the Internet connection has no reason to support it.
Note that this creates a double-NAT situation within the AFTR box: customer traffic is natted once in the AFTR itself, to the pseudo-public address, then a second time in netfilter, to the real public address. This is obviously not ideal from a performance perspective, but this scenario is only for testing and demonstration purposes.
For the AFTR box itself configuration should be:
Use the standard setup for eth0 (i.e., plain DHCP).
Use the standard setup for the AFTR function, only the script needs to be special.
IPv4 forwarding must be enabled.
Don't forget to flush iptables and ip6tables.
Use or adapt the example aftr.conf
and
aftr-script
files from the
conf/shareone
directory. (They use
198.18.200.111 as the pseudo-public address and 5000-59999 TCP
and UDP port ranges for dynamic NAT bindings.)
If the kernel supports it (see iptables
SNAT section) it can be useful to add
--random
to the SNAT rule in order to
get back port randomization.
$PUBLIC
is the shared real public
address, it is taken from the eth0 configuration.
The flush in stop
and at the
beginning of start
is for cleaning
NAT rules.
The SNAT rule just creates a new conntrack NAT entry for the first packet of a flow to the Internet coming from the AFTR. It adds no constraint on the protocol or the natted source port (but the AFTR has itself such constraints, protocols are tcp/udp/icmp-echo and the source port will be in the range declared in the pool so the natted port should be in one of the ranges decribed in iptables SNAT section).
The first DNAT rule remaps traffic to a matching port to the pseudo public address without changing the destination port. It is used for port forwarding.
Destination ports are protocol specific so the rules have to be duplicated from TCP to UDP.
Locally generated traffic doesn't go through PREROUTING, so the rules have to be duplicated from PREROUTING to OUTPUT.
Don't forget that with conntrack a NAT entry matches the both ways, so what matters is the processing of the first packet of a flow. Further packets are recognized by conntrack to belong to the same flow, including in the "reverse" way, and the NAT rule is applied (the symmetrical rule for reverse way packets). And conntrack is also used to recognize local traffic.
Bug reports should be sent to: <aftr-bugs@isc.org>
General questions or feedback (e.g., about configuration,
operation, or use cases) should be sent to:
<aftr-users@isc.org>