clatd - a CLAT implementation for Linux
clatd implements the CLAT component of the 464XLAT network architecture specified in RFC 6877. It allows an IPv6-only host to have IPv4 connectivity that is translated to IPv6 before being routed to an upstream PLAT (which is typically a Stateful NAT64 operated by the ISP) and there translated back to IPv4 before being routed to the IPv4 internet. This is especially useful when local applications on the host requires actual IPv4 connectivity or cannot make use of DNS64 (for example because they use legacy AF_INET socket calls, or if they are simply not using DNS64).
It may also be used in combination with a stateless PLAT as defined by I-D.anderson-siit-dc to give the otherwise IPv6-only host a public IPv4 address with connectivity to the IPv4 internet. This may be useful in a server environment that are using legacy IPv4-only applications as described above.
It relies on the software package TAYGA by Nathan Lutchansky for the actual translation of packets between IPv4 and IPv6 (RFC 6145) TAYGA may be downloaded from its home page at http://www.litech.org/tayga/.
clatd [options]
- -q
-
Quiet mode; suppress normal output This is the same as setting quiet=1. Warnings and errors are still outputted, to silence those too, repeat -q.
- -d
-
Enable debugging output. This is the same as setting debug=1. Repeat for even more debugging output, which is the equivalent of setting debug=2.
- -c conf-file
-
Read configuration settings from conf-file. See section CONFIGURATION below for more info.
- -h, --help
-
Print a brief usage help and exit.
- key=value
-
Set configuration key to value, overriding any setting found in the configuration file. Refer to the section CONFIGURATION below for more info.
clatd is meant to be run under a daemonising control process such as systemd, upstart, or similar. It is further meant to be (re)started whenever a network interface goes up/down as this might mean a change in the PLAT availability or which prefixes/addresses needs to be used for the CLAT to work. It may also be run directly from the command line. It will run until killed with SIGINT (^C) or SIGTERM, at which point it will clean up after itself and exit gracefully.
See the scripts/ directory in the source distribution for some examples on how to invoke it it.
The following commands will quickly download and install the latest version of clatd and its dependencies:
- git clone https://github.com/toreanderson/clatd
- sudo make -C clatd install installdeps
This will install clatd to /usr/sbin, plus install systemd, upstart, and/or NetworkManager scripts if your distribution appears to be using them, and install all the dependencies. Note that TAYGA isn't available in RPM format, so on RedHat/Fedora the installdeps target will install gcc and attempt to compile TAYGA from source.
clatd is designed to be able to run without any user-supplied configuration in most cases. However, user-specified onfiguration settings may be added to the configuration file, the path to which may be given on the command line using the -c option, or if it is not, the default location /etc/clatd.conf is used. Configuration settings may also be given directly on the command line when starting A626 clatd, which takes precedence over settings in the configuration file.
Settings are of the form key=value. A list of recogniced keys and their possible values follow below:
- quiet=integer (default: 0)
-
Set this to 1 to suppress normal output from clatd. This is the same as providing the command line option -q. Set it to 2 to additionally suppress warnings and errors. Note that this does not suppress debugging output.
- debug=integer (default: 0)
-
Set this to 1 to get debugging output from clatd, or 2 to get even more of the stuff. These are the equivalent of providing the command line option -d the specified number of times.
- clat-dev=string (default: clat)
-
The name of the network device used by the CLAT. There should be no reason to change the default, unless you plan on running multiple instances of clatd simultaneously.
- clat-v4-addr=ipv4-address (default: 192.0.0.1)
-
The IPv4 address that will be assigned to the CLAT device. Local applications will bind to this address when communicating with external IPv4 destinations. In a standard 464XLAT environment with a stateful NAT64 serving as the PLAT, there should be no need to change the default, but if the PLAT is a stateless translator (a la I-D.draft-anderson-siit-dc), you might want to set this to the true external address used externally, so the the local applications can correctly identify which public address they'll be using on the IPv4 internet.
The default address is one from I-D.draft-byrne-v6ops-clatip.
- clat-v6-addr=ipv6-address (default: auto-generated)
-
The IPv6 address of the CLAT. Traffic to/from the clat-v4-addr will be translated into this address. By default, clatd will attempt to figure out which network device will be used for traffic towards the PLAT, see if there is any SLAAC-configured addresses on it, and if so substitute the '0xfffe' value in the middle of the Interface ID for '0xc1a7' to generate a new address for the CLAT. If you're not using SLAAC you will have to set this manually.
- dns64-servers=srv1,[srv2,..] (default: use system resolver)
-
Comma-separated list of DNS64 servers to use when discovering the PLAT prefix using the method described in RFC 7050. By default, the system resolver is used, but it might be useful to override this in case your ISP doesn't provide you with a DNS64-enabled name server, and you want to test clatd using any of the public DNS64/NAT64 instances on the internet. The first PLAT prefix encountered will be used.
- cmd-ip=path (default: assume in $PATH)
-
Path to the ip binary from the iproute2 package available at https://www.kernel.org/pub/linux/utils/net/iproute2. Required.
- cmd-ip6tables=path (default: assume in $PATH)
-
Path to the ip6tables binary from the netfilter package available at http://netfilter.org. Only required for adding ip6tables rules (see the ip6tables-enable configuration setting).
- cmd-tayga=path (default: assume in $PATH)
-
Path to the tayga binary from the TAYGA package available at http://www.litech.org/tayga. Required.
- forwarding-enable=bool (default: yes)
-
Controls whether or not clatd should enable IPv6 forwarding if necessary. IPv6 forwarding is necessary for clatd to work correctly. It will also ensure that the accept_ra sysctl is to '2' for all devices have it set to '1', in order to prevent any connectivity loss as a result of enabling forwarding.
All sysctls that are modified will be restored to their original values when clatd is shutting down.
- ip6tables-enable=bool (default: see below)
-
Controls whether or not clatd should insert ip6tables rules that permit the forwarding of IPv6 traffic between the CLAT and PLAT devices. Such forwarding must be permitted for clatd to work correctly. Any rules added will be removed when clatd is shutting down.
The default is yes if the ip6tables_filter kernel module is loaded, no if it is not.
- plat-dev (default: auto-detect)
-
Which network device is facing the PLAT (NAT64). By default, this is auto-detecting by performing a route table lookup towards the PLAT prefix. This setting is used when setting up generating the CLAT IPv6 address, and when setting up ip6tables rules and Proxy-ND entries.
- plat-prefix (default: auto-detect)
-
The IPv6 translation prefix into which the PLAT maps the IPv4 internet. See RFC 6052 for a closer description. By default, this is auto-detected from DNS64 answers using the method in RFC 7050.
- proxynd-enable (default: yes)
-
Controls whether or not clatd should add a Proxy-ND entry for the CLAT IPv6 address on the network device facing the PLAT. This is probably necessary on Ethernet networks (otherwise the upstream IPv6 router won't know where to send packets to the CLAT's IPv6 adderss), but likely not necessary on point-to-point links like PPP or 3GPP mobile broadband, as in those cases IPv6 ND isn't used. However it doesn't hurt to add Proxy-ND entries in that case, either.
Any entries added wil be removed when clatd is shutting down.
- tayga-conffile (default: use a temporary file)
-
Where to write the TAYGA configuration file. By default, a temporary file will be created (and also deleted when clatd is shutting down), but you may also specify an explicit configuration file here, which will not be deleted on shutdown.
- tayga-v4-addr (default: 192.0.0.2)
-
The IPv4 address assigned to the TAYGA process. This is used for emitting ICMPv4 errors back to the host (i.e., it will show up as the first hop when tracerouting to IPv4 destinations), and you may also ping it to verify that the TAYGA process is still alive and well.
The default address is one from I-D.draft-byrne-v6ops-clatip.
- v4-conncheck-enable=bool (default: yes)
-
Whether or not to check if the system has IPv4 connectivity before starting the CLAT. If it does, then clatd will simply exit without doing anything. This is meant so that you can always enable clatd to the system startup scripts or network-up event scripts (such as NetworkManager's dispatcher scripts), but not have clatd interfering with native IPv4 connectivity when this is present.
If you want to always start the CLAT whenever possible, even though the system has IPv4 connectivity, disable this setting. You may instead use the v4-defaultroute-enable and v4-defaultroute-metric settings to prevent clatd from interfering with native IPv4 connectivity.
- v4-conncheck-delay=seconds (default: 10)
-
When performing an IPv4 connectivity check, wait this number of seconds before actually doing anything. This is to avoid a race condition where for example IPv6 SLAAC finshes and triggers a network-up event script to start clatd, while IPv4 DHCPv4 is still running in the background. This is at least a likely scenario when using NetworkManager, as it will start the dispatcher scripts as soon as either IPv4 or IPv6 has completed, and IPv6 SLAAC is typically faster than IPv4 DHCPv4.
Set it to 0 to perform the check immediately.
- v4-defaultroute-enable=bool (default: yes)
-
Whether or not to add an IPv4 default route pointing to the CLAT. In a typical 464XLAT environment, you want this. However when using clatd in an environment where native IPv4 connectivity is also present, you might want to disable this and instead control manually which IPv4 destinations is reached through the CLAT and which are not.
- v4-defaultroute-metric=integer (default: 2048)
-
The metric of the IPv4 default route pointing to the CLAT. The default is chosen because it is higher than that of a native IPv4 default route added by NetworkManager, which makes it so that the native IPv4 connectivity is preferred if present.
- v4-defaultroute-mtu=integer (default: 1260)
-
The MTU of the default route pointing to the CLAT. The default is the default IPv6 MTU used by TAYGA (1280, which in turn comes from RFC 6145) minus 20 to compensate for the difference in header size between IPv4 and IPv6. This prevents outbound packets from having to be fragmented by TAYGA, and also makes local applications advertise a TCP MSS to their remote peers that prevent them from sending packets beck to us that would require fragmentation.
If you know that the IPv6 Path MTU between the host and the PLAT is larger than 1280, you may increase this, but then you should also recompile TAYGA with a larger ipv6_offlink_mtu setting in conffile.c.
clatd will not be able to acquire an IPv6 address for the CLAT if SLAAC isn't used. RFC 6877 suggests DHCPv6 IA_PD should be attempted in this case, but this isn't currently implemented.
clatd will not attempt to perform Duplicate Address Detection for the IPv6 address it generates. This is a violation of RFC 6877.
clatd will not attempt to perform a connectivity check to a discovered PLAT prefix before setting up the CLAT, as RFC 7050 suggest it should.
If you are experiencing any bugs or have any feature requests, head over to https://github.com/toreanderson/clatd/issues and submit a new issue (if someone else hasn't already done so). Please make sure to include logs with full debugging output (using -d -d on the command line or debug=2 in the configuration file) when reporting a bug.
Copyright (c) 2014 Tore Anderson <tore@fud.no>
As long as you retain this notice, you may use this piece of software as you wish. If you like it, and we happen to meet one day, you can buy me a beer in return. If you really like it, make it an IPA.
ip(8), ip6tables(8), tayga(8), tayga.conf(5)
RFC 6052, RFC 6145, RFC 6146, RFC 6877, RFC 7050
I-D.anderson-siit-dc, I-D.byrne-v6ops-clatip