1clatd(8)            clatd - a CLAT implementation for Linux           clatd(8)
2
3
4

NAME

6       clatd - a CLAT / SIIT-DC Edge Relay implementation for Linux
7

DESCRIPTION

9       clatd implements the CLAT component of the 464XLAT network architecture
10       specified in RFC 6877. It allows an IPv6-only host to have IPv4
11       connectivity that is translated to IPv6 before being routed to an
12       upstream PLAT (which is typically a Stateful NAT64 operated by the ISP)
13       and there translated back to IPv4 before being routed to the IPv4
14       internet. This is especially useful when local applications on the host
15       requires actual IPv4 connectivity or cannot make use of DNS64 (for
16       example because they use legacy AF_INET socket calls, or if they are
17       simply not using DNS64).
18
19       clatd may also be used to implement an SIIT-DC Edge Relay as described
20       in RFC 7756. In this scenario, the PLAT is in reality a SIIT-DC Border
21       Relay (see RFC 7755) instead of a Stateful NAT64 (see RFC6146). When
22       used as a SIIT-DC Edge Relay, you will probably want to manually
23       configure the settings clat-v4-addr, clat-v6-addr, and plat-prefix to
24       mirror the SIIT-DC Border Relay's configuration.
25
26       It relies on the software package TAYGA by Nathan Lutchansky for the
27       actual translation of packets between IPv4 and IPv6 (RFC 6145) TAYGA
28       may be downloaded from its home page at <http://www.litech.org/tayga/>.
29

SYNOPSIS

31       clatd [options]
32

OPTIONS

34       -q  Quiet mode; suppress normal output. This is the same as setting
35           quiet=1.  Warnings and errors are still outputted, to silence those
36           too, repeat -q.
37
38       -d  Enable debugging output. This is the same as setting debug=1.
39           Repeat for even more debugging output, which is the equivalent of
40           setting debug=2.
41
42       -c conf-file
43           Read configuration settings from conf-file. See section
44           CONFIGURATION below for more info.
45
46       -h, --help
47           Print a brief usage help and exit.
48
49       key=value
50           Set configuration key to value, overriding any setting found in the
51           configuration file. Refer to the section CONFIGURATION below for
52           more info.
53

INVOCATION

55       clatd is meant to be run under a daemonising control process such as
56       systemd, upstart, or similar. It is further meant to be (re)started
57       whenever a network interface goes up/down as this might mean a change
58       in the PLAT availability or which prefixes/addresses needs to be used
59       for the CLAT to work.  It may also be run directly from the command
60       line. It will run until killed with SIGINT (^C) or SIGTERM, at which
61       point it will clean up after itself and exit gracefully.
62
63       See the scripts/ directory in the source distribution for some examples
64       on how to invoke it it.
65

INSTALLATION

67       The following commands will quickly download and install the latest
68       version of clatd and its dependencies:
69
70       git clone https://github.com/toreanderson/clatd
71       sudo make -C clatd install installdeps
72
73       This will install clatd to /usr/sbin, plus install systemd, upstart,
74       and/or NetworkManager scripts if your distribution appears to be using
75       them, and install all the dependencies. Note that TAYGA isn't available
76       in all RPM-based distros (in particular RHEL and its clones). It is
77       however available in EPEL (see <https://fedoraproject.org/wiki/EPEL>).
78

CONFIGURATION

80       clatd is designed to be able to run without any user-supplied
81       configuration in most cases. However, user-specified configuration
82       settings may be added to the configuration file, the path to which may
83       be given on the command line using the -c option, or if it is not, the
84       default location /etc/clatd.conf is used. Configuration settings may
85       also be given directly on the command line when starting clatd, which
86       takes precedence over settings in the configuration file.
87
88       Settings are of the form key=value. A list of recognised keys and their
89       possible values follow below:
90
91       quiet=integer (default: 0)
92           Set this to 1 to suppress normal output from clatd. This is the
93           same as providing the command line option -q. Set it to 2 to
94           additionally suppress warnings and errors. Note that this does not
95           suppress debugging output.
96
97       debug=integer (default: 0)
98           Set this to 1 to get debugging output from clatd, or 2 to get even
99           more of the stuff. These are the equivalent of providing the
100           command line option -d the specified number of times.
101
102       script-up=string (no default)
103           Specify a custom script to be run when clatd is starting up. The
104           invocation of this script is the last thing that happens before
105           TAYGA starts up, so all the preparations have been completed at
106           that point (i.e., the clat-dev exists and has routing/addressing
107           configured, forwarding has been enabled, and so on).
108
109           The script is run by the system shell, so you can do everything you
110           could in an interactive shell: run multiple commands by separating
111           them by semi-colon or double ampersands, use standard if/else
112           statements, use variable substitutions, redirect output to files,
113           set up command pipelines, and so on. However it must all be on one
114           line, so if you want to do complex things or use some other
115           programming language it's probably better to put the script itself
116           in a separate executable file and just make script-up invoke that
117           file instead.
118
119           If the script returns a nonzero exit status, this is considered a
120           fatal error, and clatd will abort. This can be prevented by
121           appending || true at the end of the script.
122
123           All of clatd's configuration settings are available as standard
124           variables in the script's environment (hyphens are replaced with
125           underscores).
126
127           Logging or debug messages from the script may simply be sent to
128           stdout, where it will be picked up by the init system along with
129           clatd's own output. The script may of course consult the $quiet and
130           $debug environment variables in order to determine how much output
131           is appropriate.
132
133           The script should not be enclosed in quotes in the configuration
134           file (even though it contains whitespace). For example:
135
136           script-up=echo `date -Ins`: clatd started on $clat_dev | tee -a
137           ~/clatd.log
138
139           If on the other hand you want to supply a script-up containing
140           whitespace directly clatd's command line, quoting is required in
141           order to prevent the shell from splitting it up and into multiple
142           command line arguments. For example:
143
144           clatd 'script-up=ip route add 192.0.2.0/24 dev $clat_dev || true'
145
146       script-down=string (no default)
147           This works exactly the same as script-up, only that this script is
148           run right after TAYGA has exited, before the clean-up process of
149           restoring any settings that were changed.
150
151           An unsuccessful exit code from script-down will cause clatd to exit
152           unsuccessfully too. Beyond that an unsuccessful exit won't change
153           anything, because script-down is invoked at a point in time where
154           the only thing left for clatd to do is to clean up after itself and
155           exit anyway.
156
157       clat-dev=string (default: clat)
158           The name of the network device used by the CLAT. There should be no
159           reason to change the default, unless you plan on running multiple
160           instances of clatd simultaneously.
161
162       clat-v4-addr=ipv4-address (default: 192.0.0.1)
163           The IPv4 address that will be assigned to the CLAT device. Local
164           applications will bind to this address when communicating with
165           external IPv4 destinations.  In a standard 464XLAT environment with
166           a stateful NAT64 serving as the PLAT, there should be no need to
167           change the default.
168
169           When using clatd as an SIIT-DC Edge Relay (RFC 7756), you will want
170           to set this to the IPv4 Service Address configured in the SIIT-DC
171           Border Relay.  This way, local applications can correctly identify
172           which public address they'll be using on the IPv4 internet, and
173           will be able to provide fully functional references to it in
174           application-level payload, and so on.
175
176           The default address is one from RFC 7335.
177
178       clat-v6-addr=ipv6-address (default: auto-generated)
179           The IPv6 address of the CLAT. Traffic to/from the clat-v4-addr will
180           be translated into this address. When using clatd as an SIIT-DC
181           Edge Relay, you will want to set this to the same IPv6 address in
182           the Explicit Address Mapping configured in the SIIT-DC Border
183           Relay.
184
185           By default, clatd will attempt to figure out which network device
186           will be used for traffic towards the PLAT, see if there is any
187           SLAAC-based globally scoped addresses on it (i.e., a /64 with
188           '0xfffe' in the middle of the Interface ID), and will if so
189           substitute that '0xfffe' value with '0xc1a7' ("clat") to generate a
190           CLAT IPv6 address.
191
192           If only a non-SLAAC global address is found on the PLAT-facing
193           device, clatd will substitute its Interface ID with a random
194           integer and use the result as the CLAT IPv6 address. It will only
195           do so if the prefix length is /120 or smaller, as otherwise the
196           risk of IID collisions is considered to be too high. Note that on
197           most Perl platforms, the rand() function is limited to 48 bits,
198           which means that for longer IIDs, the least significant bits will
199           be all 0.
200
201           If multiple addresses are found in either category, the one that
202           shares the longest common prefix with the PLAT prefix will be
203           preferred when deriving the CLAT IPv6 address according to the
204           algorithm described above.
205
206       dns64-servers=srv1,[srv2,..] (default: use system resolver)
207           Comma-separated list of DNS64 servers to use when discovering the
208           PLAT prefix using the method described in RFC 7050. By default, the
209           system resolver is used, but it might be useful to override this in
210           case your ISP doesn't provide you with a DNS64-enabled name server,
211           and you want to test clatd using any of the public DNS64/NAT64
212           instances on the internet. The first PLAT prefix encountered will
213           be used.
214
215       cmd-ip=path (default: assume in $PATH)
216           Path to the ip binary from the iproute2 package available at
217           <https://www.kernel.org/pub/linux/utils/net/iproute2>. Required.
218
219       cmd-ip6tables=path (default: assume in $PATH)
220           Path to the ip6tables binary from the netfilter package available
221           at <http://netfilter.org>. Only required for adding ip6tables rules
222           (see the ip6tables-enable configuration setting).
223
224       cmd-tayga=path (default: assume in $PATH)
225           Path to the tayga binary from the TAYGA package available at
226           <http://www.litech.org/tayga>. Required.
227
228       forwarding-enable=bool (default: yes)
229           Controls whether or not clatd should enable IPv6 forwarding if
230           necessary.  IPv6 forwarding is necessary for clatd to work
231           correctly. It will also ensure that the accept_ra sysctl is to '2'
232           for all devices have it set to '1', in order to prevent any
233           connectivity loss as a result of enabling forwarding.
234
235           All sysctls that are modified will be restored to their original
236           values when clatd is shutting down.
237
238       ip6tables-enable=bool (default: see below)
239           Controls whether or not clatd should insert ip6tables rules that
240           permit the forwarding of IPv6 traffic between the CLAT and PLAT
241           devices. Such forwarding must be permitted for clatd to work
242           correctly. Any rules added will be removed when clatd is shutting
243           down.
244
245           The default is yes if the ip6tables_filter kernel module is loaded,
246           no if it is not.
247
248       plat-dev (default: auto-detect)
249           Which network device is facing the PLAT (NAT64). By default, this
250           is auto-detected by performing a route table lookup towards the
251           PLAT prefix.  This setting is used when setting up generating the
252           CLAT IPv6 address, and when setting up ip6tables rules and Proxy-ND
253           entries.
254
255       plat-prefix (default: auto-detect)
256           The IPv6 translation prefix into which the PLAT maps the IPv4
257           internet. See RFC 6052 for a closer description. By default, this
258           is auto-detected from DNS64 answers using the method in RFC 7050.
259
260       proxynd-enable (default: yes)
261           Controls whether or not clatd should add a Proxy-ND entry for the
262           CLAT IPv6 address on the network device facing the PLAT. This is
263           probably necessary on Ethernet networks (otherwise the upstream
264           IPv6 router won't know where to send packets to the CLAT's IPv6
265           address), but likely not necessary on point-to-point links like PPP
266           or 3GPP mobile broadband, as in those cases IPv6 ND isn't used.
267           However it doesn't hurt to add Proxy-ND entries in that case,
268           either.
269
270           Any entries added wil be removed when clatd is shutting down.
271
272       tayga-conffile (default: use a temporary file)
273           Where to write the TAYGA configuration file. By default, a
274           temporary file will be created (and also deleted when clatd is
275           shutting down), but you may also specify an explicit configuration
276           file here, which will not be deleted on shutdown.
277
278       tayga-v4-addr (default: 192.0.0.2)
279           The IPv4 address assigned to the TAYGA process. This is used for
280           emitting ICMPv4 errors back to the host (i.e., it will show up as
281           the first hop when tracerouting to IPv4 destinations), and you may
282           also ping it to verify that the TAYGA process is still alive and
283           well.
284
285           The default address is one from RFC 7335.
286
287       v4-conncheck-enable=bool (default: yes)
288           Whether or not to check if the system has IPv4 connectivity before
289           starting the CLAT. If it does, then clatd will simply exit without
290           doing anything.  This is meant so that you can always enable clatd
291           to the system startup scripts or network-up event scripts (such as
292           NetworkManager's dispatcher scripts), but not have clatd
293           interfering with native IPv4 connectivity when this is present.
294
295           If you want to always start the CLAT whenever possible, even though
296           the system has IPv4 connectivity, disable this setting. You may
297           instead use the v4-defaultroute-enable and v4-defaultroute-metric
298           settings to prevent clatd from interfering with native IPv4
299           connectivity.
300
301           Note that enabling v4-defaultroute-replace will override
302           v4-conncheck-enable and unconditionally disable IPv4 connectivity
303           checking.
304
305       v4-conncheck-delay=seconds (default: 10)
306           When performing an IPv4 connectivity check, wait this number of
307           seconds before actually doing anything. This is to avoid a race
308           condition where for example IPv6 SLAAC finshes and triggers a
309           network-up event script to start clatd, while IPv4 DHCPv4 is still
310           running in the background. This is at least a likely scenario when
311           using NetworkManager, as it will start the dispatcher scripts as
312           soon as either IPv4 or IPv6 has completed, and IPv6 SLAAC is
313           typically faster than IPv4 DHCPv4.
314
315           Set it to 0 to perform the check immediately.
316
317       v4-defaultroute-enable=bool (default: yes)
318           Whether or not to add an IPv4 default route pointing to the CLAT.
319           In a typical 464XLAT environment, you want this. However when using
320           clatd in an environment where native IPv4 connectivity is also
321           present, you might want to disable this and instead control
322           manually which IPv4 destinations is reached through the CLAT and
323           which are not.
324
325       v4-defaultroute-replace=bool (default: no)
326           Instructs clatd to remove any pre-existing IPv4 default routes,
327           replacing it with one pointing to the CLAT (assuming
328           v4-defaultroute-enable is yes).  The replacement is temporary, any
329           pre-existing routes that were removed will be restored when clatd
330           is shutting down.
331
332           Note that nothing prevents software like a connection manager or a
333           DHCPv4 client daemon from re-adding any replaced routes while clatd
334           is running.
335
336           If you enable v4-defaultroute-replace while at the same time
337           disabling v4-defaultroute-enable, clatd will remove any pre-
338           existing IPv4 default routes but not add any of its own.
339
340           Setting v4-defaultroute-replace to yes will disable the IPv4
341           connectivity check.
342
343       v4-defaultroute-metric=integer (default: 2048)
344           The metric of the IPv4 default route pointing to the CLAT. The
345           default is chosen because it is higher than that of a native IPv4
346           default route added by NetworkManager, which makes it so that the
347           native IPv4 connectivity is preferred if present.
348
349       v4-defaultroute-mtu=integer (default: 1260)
350           The MTU of the default route pointing to the CLAT. The default is
351           the default IPv6 MTU used by TAYGA (1280, which in turn comes from
352           RFC 6145) minus 20 to compensate for the difference in header size
353           between IPv4 and IPv6. This prevents outbound packets from having
354           to be fragmented by TAYGA, and also makes local applications
355           advertise a TCP MSS to their remote peers that prevent them from
356           sending packets beck to us that would require fragmentation.
357
358           If you know that the IPv6 Path MTU between the host and the PLAT is
359           larger than 1280, you may increase this, but then you should also
360           recompile TAYGA with a larger ipv6_offlink_mtu setting in
361           conffile.c.
362
363       v4-defaultroute-advmss=integer (default: v4-defaultroute-mtu - 40)
364           The "advmss" value assigned to the the default route potining to
365           the CLAT. This controls the advertised TCP MSS value for TCP
366           connections made through the CLAT.
367
368           You should normally not need to set this. By default the value is
369           calculated by taking the value of v4-defaultroute-mtu and
370           substracting 40 (20 bytes for the IPv4 header + 20 bytes for the
371           TCP header). If v4-defaultroute-mtu is unset or 0, there is no
372           default.
373

LIMITATIONS

375       clatd will not be able to acquire an IPv6 address for the CLAT if SLAAC
376       isn't used. RFC 6877 suggests DHCPv6 IA_PD should be attempted in this
377       case, but this isn't currently implemented.
378
379       clatd will not attempt to perform Duplicate Address Detection for the
380       IPv6 address it generates. This is a violation of RFC 6877.
381
382       clatd will not attempt to perform a connectivity check to a discovered
383       PLAT prefix before setting up the CLAT, as RFC 7050 suggest it should.
384

BUGS

386       If you are experiencing any bugs or have any feature requests, head
387       over to <https://github.com/toreanderson/clatd/issues> and submit a new
388       issue (if someone else hasn't already done so). Please make sure to
389       include logs with full debugging output (using -d -d on the command
390       line or debug=2 in the configuration file) when reporting a bug.
391

LICENCE

393       Copyright (c) 2014-2019 Tore Anderson <tore@fud.no>
394
395       Permission is hereby granted, free of charge, to any person obtaining a
396       copy of this software and associated documentation files (the
397       "Software"), to deal in the Software without restriction, including
398       without limitation the rights to use, copy, modify, merge, publish,
399       distribute, sublicense, and/or sell copies of the Software, and to
400       permit persons to whom the Software is furnished to do so, subject to
401       the following conditions:
402
403       The above copyright notice and this permission notice shall be included
404       in all copies or substantial portions of the Software.
405
406       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
407       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
408       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
409       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
410       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
411       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
412       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
413

SEE ALSO

415       ip(8), ip6tables(8), tayga(8), tayga.conf(5)
416
417       RFC 6052, RFC 6145, RFC 6146, RFC 6877, RFC 7050, RFC 7335 RFC 7755,
418       RFC 7756, RFC 7757
419
420
421
422perl v5.36.0                      2023-01-18                          clatd(8)
Impressum