tayga.conf.5

.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "TAYGA.CONF" "5" "March 2026" "TAYGA dev" ""
.SH NAME
tayga.conf \- configuration file of the \f[B]tayga\f[R] stateless NAT64
daemon
.SH DESCRIPTION
This file contains the configuration parameters for the \f[B]tayga\f[R]
stateless NAT64 daemon.
It must exist and contain the mandatory configuration items or
\f[B]tayga\f[R] will refuse to run.
.PP
The configuration directives are listed below.
With the exception of the \f[B]map\f[R] directive, only one instance of
each directive may appear in tayga.conf.
.TP
\f[B]tun\-device\f[R] \f[I]device\f[R]
Name of the network interface that will be created by the kernel TUN
module for \f[B]tayga\f[R] to exchange IPv4 and IPv6 packets with the
in\-kernel TCP/IP stack.
If \f[I]device\f[R] does not already exist as a persistent interface
(created by the \f[B]\-\-mktun\f[R] flag to tayga(8), for example), it
will be created automatically when the \f[B]tayga\f[R] daemon starts and
destroyed when the daemon exits.
.RS
.PP
Note that \f[B]tayga\f[R] does not configure the host\-side parameters
of \f[I]device\f[R].
This must be done by the system administrator using the ifconfig(8),
route(8), and/or ip(8) commands.
.PP
This configuration directive is mandatory.
.RE
.TP
\f[B]ipv4\-addr\f[R] \f[I]ipv4_address\f[R]
IPv4 address that \f[B]tayga\f[R] will use as the source address for
ICMPv4 errors generated by the translation process.
\f[B]tayga\f[R] will also respond to ICMP echo requests (pings) at this
address.
.RS
.PP
\f[I]ipv4_address\f[R] is permitted to overlap with the prefix specified
in the \f[B]dynamic\-pool\f[R] directive, in which case
\f[I]ipv4_address\f[R] will be removed from the pool of available
addresses.
.PP
This configuration directive is mandatory.
.RE
.TP
\f[B]ipv6\-addr\f[R] \f[I]ipv6_address\f[R]
IPv6 address that \f[B]tayga\f[R] will use as the source address for
ICMPv6 errors generated by the translation process.
\f[B]tayga\f[R] will also respond to ICMPv6 echo requests (pings) at
this address.
.RS
.PP
This configuration directive is mandatory unless the NAT64 prefix is
specified with the \f[B]prefix\f[R] directive, in which case
\f[B]tayga\f[R] will generate its IPv6 address by mapping the address
specified in \f[B]ipv4\-addr\f[R] into the NAT64 prefix.
.RE
.TP
\f[B]prefix\f[R] \f[I]ipv6_address/length\f[R]
NAT64 prefix for mapping IPv4 addresses into the IPv6 address space.
\f[B]tayga\f[R] performs address translation as specified in RFC 6052,
and only prefix lengths allowed in that document will be permitted in
the \f[B]prefix\f[R] directive.
.RS
.PP
The use of either a Network\-Specific Prefix or the Well\-Known Prefix
(64:ff9b::/96) is allowed, \f[B]however,\f[R] as required by RFC 6052,
\f[B]tayga\f[R] will refuse to translate packets with a source or
destination address composed of the Well\-Known Prefix and a non\-global
IPv4 address (10.x.x.x, 192.168.x.x, etc), unless the
\f[B]wkpf\-strict\f[R] option is set to no.
.PP
Use of the \f[B]prefix\f[R] directive is optional.
If it is not specified, all addresses to be translated must be listed
individually with the \f[B]map\f[R] directive.
.RE
.TP
\f[B]wkpf\-strict\f[R] \f[I]yes|no\f[R]
Enable or disable strict RFC 6052 compliance.
If enabled, Tayga will refuse with a source or destination address
composed of the Well\-Known Prefix and a non\-global IPv4 address
(10.x.x.x, 192.168.x.x, etc).
.RS
.PP
Enabled by default
.RE
.TP
\f[B]map\f[R] \f[I]ipv4_address[/length] ipv6_address[/length]\f[R]
Creates a static mapping between RFC 7577 compliant hosts or subnets
\f[I]ipv4_address[/length]\f[R] and \f[I]ipv6_address[/length]\f[R] to
be used when translating IPv4 packets to IPv6 or IPv6 packets to IPv4.
If \f[I]/length\f[R] is not present, the \f[I]/length\f[R] after
\f[I]ipv4_address\f[R] is treated as \[lq]/32\[rq] and that of
\f[I]ipv6_address\f[R] as \[lq]/128\[rq].
Multiple \f[B]map\f[R] directives are permitted in the tayga.conf file.
.RS
.PP
\f[I]ipv4_address\f[R] is permitted to overlap with the prefix specified
in the \f[B]dynamic\-pool\f[R] directive, in which case
\f[I]ipv4_address\f[R] will be removed from the pool of available
addresses.
.PP
\f[I]ipv6_address\f[R] \f[B]must not\f[R] overlap with the prefix
specified in the \f[B]prefix\f[R] directive.
.RE
.TP
\f[B]dynamic\-pool\f[R] \f[I]ipv4_address/length\f[R]
Address prefix containing addresses available to be assigned to IPv6
hosts.
\f[I]length\f[R] must be 31 or less, as the lowest\-numbered address in
the prefix is considered reserved and will not be used for dynamic
assignment.
.RS
.PP
If \f[B]tayga\f[R] receives an IPv6 packet to be translated with an IPv6
source address that does not match any existing mapping rules (as
specified by the \f[B]map\f[R] directive or the \f[B]prefix\f[R]
directive), \f[B]tayga\f[R] will create a dynamic mapping between the
IPv6 address and an IPv4 address drawn from the prefix specified by the
\f[B]dynamic\-pool\f[R] directive.
This mapping will be valid for two hours and four minutes after the last
packet matching the mapping is translated.
.PP
The \f[B]dynamic\-pool\f[R] directive is optional.
If it is not specified, all IPv6 addresses appearing in packets passing
through \f[B]tayga\f[R] must match the NAT64 prefix or a static mapping
rule.
.RE
.TP
\f[B]data\-dir\f[R] \f[I]path\f[R]
The absolute path of a directory where \f[B]tayga\f[R] should store its
data files.
Presently the only data file that \f[B]tayga\f[R] will store is the
\f[I]dynamic.map\f[R] file, which tracks dynamic address assignments
made from the dynamic pool.
.RS
.PP
\f[I]path\f[R] is also the directory that will be used as a chroot(2)
\[lq]jail\[rq] if the \f[B]\-\-chroot\f[R] command\-line option is
specified to the \f[B]tayga\f[R] daemon.
.PP
The \f[B]tayga\f[R] daemon must have full permissions (rwx) to
\f[I]path\f[R] after it has dropped superuser privileges.
Generally this means that the owner of \f[I]path\f[R] should be the user
specified in the \f[B]\-\-user\f[R] command\-line option.
.PP
The \f[B]data\-dir\f[R] directive is optional.
If not configured, \f[B]tayga\f[R] will check the environment variable
\f[B]STATE_DIRECTORY\f[R].
If neither is provided, dynamic mappings will be lost when the
\f[B]tayga\f[R] daemon is stopped.
Also, use of the \f[B]\-\-chroot\f[R] command\-line option will not be
possible.
.PP
If the \f[I]map\-file\f[R] directive is used, it may be relative to
\f[B]data\-dir\f[R]
.RE
.TP
\f[B]map\-file\f[R] \f[I]path\f[R]
The path to a file which contains reloadable map entries.
As with the \f[B]tayga.conf\f[R] file, this file may contain multiple
\f[I]map\f[R] entries.
The contents of this file will be loaded on startup, and reloaded when
Tayga receives SIGHUP.
.RS
.PP
Mapping entries loaded from the \f[B]map\-file\f[R] cannot modify
mapping entries created from \f[B]tayga.conf\f[R], or non\-static map
types.
.PP
\f[B]map\-file\f[R] reload is guaranteed to not affect packet processing
for entries which are not modified and do not conflict with each other.
.PP
\f[B]map\-file\f[R] must be an absolute path or relative to
\f[B]data\-dir\f[R].
You must ensure that Tayga has sufficient permissions to read this file
after it has dropped permissions using \f[I]user\f[R] and
\f[I]chroot\f[R].
.RE
.TP
\f[B]udp\-cksum\-mode\f[R] \f[I]drop|fwd|calc\f[R]
Handling of UDP packets with zero checksum.
Per RFC7915, we can either \f[B][drop]\f[R] the packet, or calculating
\f[B][calc]\f[R] a new checksum.
Additionally, Tayga also allows the option of forwarding \f[B][fwd]\f[R]
the packet anyway
.TP
\f[B]log\f[R] \f[I]drop|reject|self\f[R]
Configure logging of packets.
By default, Tayga only logs errors within Tayga itself.
To log errors in packet translation, list one or more log option.
.RS
.PP
\f[I]drop\f[R] \- Log packets which were dropped.
.PP
\f[I]reject\f[R] \- Log packets which were rejected (ICMP returned)
.PP
\f[I]icmp\f[R] \- Log packets which returned an ICMP for any reason,
including packets which are part of `normal' internet traffic (i.e.
Packet Too Big or Time Exceeded)
.PP
\f[I]self\f[R] \- Log packets which were destined for Tayga itself
.PP
No packet logging is enabled by default
.RE
.TP
\f[B]offlink\-mtu\f[R] \f[I]bytes\f[R]
Tayga will fragment IPv4\->IPv6 packets which are larger than this size,
unless the Don\[cq]t Fragment bit is set.
.RS
.PP
IPv6 guarantees delivery of packets which are 1280 bytes or less.
This behavior ensures that IPv4 packets will be delivered regardless of
the MTU on subsequent links.
IPv6 routers do not fragment packets which are too large, and IPv4 does
not require Path MTU Discovery be used.
.PP
Increasing this limit will allow Tayga to translate packets which are
larger than 1280 bytes, which may increase performance if you can
guarantee that your network can transport packets up to this MTU end to
end.
.PP
\f[B]Incorrectly setting this parameter may cause IPv4\-translated
packets to be dropped by IPv6 routers, in violation of expected IPv4
behavior.\f[R]
.RE
.TP
\f[B]tun\-up\f[R] \f[I]yes|no\f[R]
Configure whether Tayga should bring up the TUN interface itself upon
startup.
If set to \[lq]no\[rq], the administrator is responsible for bringing up
the interface and configuring its parameters (addresses, routes, etc)
manually.
Only supported on Linux.
.TP
\f[B]tun\-ip\f[R] \f[I]ip_address/prefix\f[R]
Configure an IP address and prefix for the TUN interface.
May be specified multiple times.
Only supported on Linux.
.TP
\f[B]tun\-route\f[R] \f[I]destination/prefix\f[R]
Configure a route for the TUN interface.
May be specified multiple times.
Only supported on Linux.
.SH SEE ALSO
\f[B]tayga\f[R](8)
.PP
\c
.UR https://github.com/apalrd/tayga/
.UE \c