NAME

jool - Interact with NAT64 Jool (the kernel module).

DESCRIPTION

Sends commands and requests to NAT64 Jool.
NAT64 Jool is a kernel module you load into a Linux kernel. It implements RFC 6146.

AVAILABILITY

Linux is the only OS in which this program makes sense.
Kernels 5.15 and up.

SYNTAX

jool [<argp1>] instance (
display
[--csv]
[--no-headers]
| add
[<Instance-Name>]
(--netfilter | --iptables)
--pool6 <IPv6-prefix>
| remove
[<Instance-Name>]
| flush
)

jool [<argp1>] stats (
display
[--csv]
[--no-headers]
[--all]
[--explain]
)

jool [<argp1>] global (
display
[--csv]
[--no-headers]
| update
<Key> <Value>
)

jool [<argp1>] session (
display
[--csv]
[--no-headers]
[--tcp | --udp | --icmp]
[--numeric]
| follow
| proxy
[--net.dev.in=<NETDEVIN>]
[--net.dev.out=<NETDEVOUT>]
[--net.mcast.port=<NETMCASTPORT>]
[--stats.address=<STATSADDR>]
[--stats.port=<STATSPORT>]
[--net.ttl=<NETTTL>]
<NETMCASTADDR>
| advertise
)

jool [<argp1>] file (
handle <JSON-File>
)

<argp1> := (--instance <Name> | --file <File>)

OPTIONS

Modes and Operations

instance display: Show all instances from all namespaces.
instance add: Create a new instance.
instance remove: Drop an existing instance.
instance flush: Drop all instances from the current namespace.
stats display: Show internal counters.
global display: Show the current values of the instance's tweakable internal variables.
global update: Tweak one of the instance's internal variables.
pool4 display: Show one of the tables from the IPv4 transport address pool.
(Each protocol has one table.)
pool4 add: Upload an entry to the IPv4 transport address pool.
pool4 remove: Drop transport addresses from the IPv4 transport address pool.
pool4 flush: Empty the IPv4 transport address pool.
bib display: Show one of the BIB tables.
(Each protocol has one table.)
bib add: Add a static entry to the BIB.
bib remove: Remove an entry (static or otherwise) from the BIB.
session display: Show one of the the session tables.
(Each protocol has one table.)
session follow: Listen to the instance's sessions (whenever they are updated) forever, printing them in standard output.
The instance must have ss-enabled=1.
session proxy: Listen to sessions forever, exchanging them between the instance and other listening proxies.
The -i instance must have ss-enabled=1.
session advertise: Requests the instance to send its entire session table to listening followers and proxies.
file handle: Parse all the configuration from a JSON file.
Create instance if it doesn't exist, update if it does.

Flags

--instance <Name>: Name of the instance you want to interact with.
It's an ASCII string, 15 characters max. Defaults to 'default'.
--file <File>: JSON file which contains the name of the instance you want to interact with.
Same JSON structure as the one from atomic configuration.
--tcp: Apply the operation on the TCP table.
(This is the default table.)
--udp: Apply the operation on the UDP table.
--icmp: Apply the operation on the ICMP table.
--csv: Output in CSV table format.
--no-headers: Do not print table headers. (Nor footer, if applies.)
--netfilter: Sit the instance on top of the Netfilter framework.
--iptables: Sit the instance on top of the iptables framework.
--pool6 <IPv6-prefix>: Contents of the new instance's IPv6 pool.
The format is 'PREFIX_ADDRESS[/PREFIX_LENGTH]'.
--all: Show all the counters.
(Otherwise, only the nonzero ones are printed.)
--explain: Show a description of each counter.
--mark <Mark>: The pool4 entry will only be allowed to mask packets carrying this mark.
It's a 32-bit unsigned integer. Defaults to zero.
--max-iterations (auto | infinity | <Iterations>): Maximum number of times the mask-finding algorithm will be allowed to iterate.
auto computes a recommended default,
infinity removes the iteration cap,
<Iterations> (unsigned 32-bit integer) sets the actual number.
--force: Apply operation even if certain validations fail.
--quick: Do not remove orphaned BIB and session entries.
--numeric: Do not query the DNS.

Other Arguments

<Key> <Value>: Name of the variable you want to edit (see 'Globals' section), and its new value.
<IPv4-Address> <Ports>: Descriptor of the range of transport addresses you want to add or remove from the pool.
<Ports> is a range of ports; it should follow the format '<Min>[-<Max>]'.
The command will add or remove addresses <IPv4-Address>#<Min> to <IPv4-Address>#<Max>.
<IPv6-transport-address>, <IPv4-transport-address>: Transport addresses that shape the BIB entry you want to add or remove.
The format is 'IPV6_ADDRESS#PORT' and 'IPV4_ADDRESS#PORT', respectively.
<Instance-Name>: Name of the instance you want to add or remove.
If --instance or --file were included in <argp1>, then the instance names must match.
<JSON-file>: Path to a JSON file.
<NETMCASTADDR>: Address SS traffic will be sent to and listened from.
<NETMCASTPORT>: UDP port where SS traffic will be sent to and listened from.
<NETDEVIN>: Address or interface to bind the socket in.
If <NETMCASTADDR> is IPv4, this should be one addresses from the interface where the SS traffic is expected to be received. If <NETMCASTADDR> is IPv6, this should be the name of the interface (eg. eth0).
<NETDEVOUT>: If <NETMCASTADDR> is IPv4, this should be one addresses from the interface where the multicast traffic is expected to be sent. If <NETMCASTADDR> is IPv6, this should be the name of the interface (eg. eth0).
<NETTTL>: Same as IP_MULTICAST_TTL, from ip(7).
<STATSADDR>: Address for (optional) statistics server.
<STATSPORT>: Port for the <STATSADDR> server.

Globals

manually-enabled <Boolean>: Enable or disable the instance.
pool6 <IPv6 Prefix>: The IPv6 pool's prefix.
The format is 'PREFIX_ADDRESS[/PREFIX_LENGTH]'.
lowest-ipv6-mtu <Unsigned 32-bit integer>: Smallest reachable IPv6 MTU.
logging-debug <Boolean>: Enable logging of debug messages?
zeroize-traffic-class <Boolean>: Always set the IPv6 header's 'Traffic Class' field as zero?
Otherwise copy from IPv4 header's 'TOS'.
override-tos <Boolean>: Override the IPv4 header's 'TOS' field as --tos?
Otherwise copy from IPv6 header's 'Traffic Class'.
tos <Unsigned 8-bit integer>: Value to override TOS as (only when override-tos is ON)
mtu-plateaus <Comma-separated list of unsigned 16-bit integers>: Set the list of plateaus for ICMPv4 Fragmentation Neededs with MTU unset.
address-dependent-filtering <Boolean>: Behave as (address-)restricted-cone NAT?
Otherwise behave as full-cone NAT.
drop-icmpv6-info <Boolean>: Filter ICMPv6 Informational packets?
drop-externally-initiated-tcp <Boolean>: Drop externally initiated TCP connections?
tcp-est-timeout <HH:MM:SS.mmm>: Set the TCP established session lifetime.
tcp-trans-timeout <HH:MM:SS.mmm>: Set the TCP transitory session lifetime.
udp-timeout <HH:MM:SS.mmm>: Set the UDP session lifetime.
icmp-timeout <HH:MM:SS.mmm>: Set the ICMP session lifetime.
maximum-simultaneous-opens <Unsigned 32-bit integer>: Set the maximum allowable 'simultaneous' Simultaneos Opens of TCP connections.
source-icmpv6-errors-better <Boolean>: Translate source addresses directly on 4-to-6 ICMP errors?
f-args <Unsigned 4-bit integer>: Defines the arguments that will be sent to F().
(F() is defined by algorithm 3 of RFC 6056.)
- First (leftmost) bit is source address.
- Second bit is source port.
- Third bit is destination address.
- Fourth (rightmost) bit is destination port.
handle-rst-during-fin-rcv <Boolean>: Use transitory timer when RST is received during the V6 FIN RCV or V4 FIN RCV states?
logging-bib <Boolean>: Log BIBs as they are created and destroyed?
logging-session <Boolean>: Log sessions as they are created and destroyed?
trace <Boolean>: Log basic packet fields as they are received?
ss-enabled <Boolean>: Enable Session Synchronization?
ss-flush-asap <Boolean>: Try to synchronize sessions as soon as possible?
ss-flush-deadline <Unsigned 32-bit integer>: Inactive milliseconds after which to force a session sync.
ss-capacity <Unsigned 32-bit integer>: Maximim number of queuable entries.
ss-max-payload <Unsigned 32-bit integer>: Maximum amount of bytes joold should send per packet.

EXAMPLES

Create a new instance named "Example":
jool instance add Example --iptables --pool6 64:ff9b::/96

Add addresses 192.0.2.10#1024 to 192.0.2.10#2048 to the IPv4/TCP pool:
jool -i Example pool4 add 192.0.2.10 1024-2048 --tcp

Print the TCP table of the BIB:
jool -i Example bib display

Add an UDP binding to the BIB:
jool -i Example bib add 192.0.2.10#2000 1::1#2000 --tcp

Remove the binding from the BIB:
jool -i Example bib remove 192.0.2.10#2000 --tcp

Print the TCP session table:
jool -i Example session display

Print the global configuration values:
jool -i Example global display

Update some global configuration value:
jool -i Example global update address-dependent-filtering ON

NOTES

TRUE, FALSE, 1, 0, YES, NO, ON and OFF are all valid booleans. You can mix case too.

EXIT STATUS

Zero on success, non-zero on failure.

AUTHOR

NIC Mexico & ITESM

REPORTING BUGS

https://github.com/NICMx/Jool/issues

COPYRIGHT

Copyright 2024 NIC Mexico.
License: GPLv2 (GNU GPL version 2)
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.