NAME

jool_siit - Interact with SIIT Jool (the kernel module).

DESCRIPTION

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

AVAILABILITY

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

SYNTAX

jool_siit [<argp1>] stats (
display
[--csv]
[--no-headers]
[--all]
[--explain]
| <help>
)

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

jool_siit [<argp1>] eamt (
display
[--csv]
[--no-headers]
| add
<IPv4-prefix> <IPv6-prefix>
[--force]
| remove
<IPv4-prefix> <IPv6-prefix>
| flush
| <help>
)

jool_siit [<argp1>] address (
query [--verbose] <IP-Address>
)

jool_siit [<argp1>] denylist4 (
display
[--csv]
[--no-headers]
| add
<IPv4-prefix>
[--force]
| remove
<IPv4-prefix>
| flush
| <help>
)

jool_siit [<argp1>] file (
handle <JSON-File>
| <help>
)

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

<help> := (--help | --usage | --version)

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.
eamt display: Show the EAM table.
eamt add: Upload an entry to the EAM table.
eamt remove: Drop an entry from the EAM table.
eamt flush: Empty the EAM table.
address query: Print the translated version of the given address using the current configuration.
denylist4 display: Show the denylist.
denylist4 add: Upload an entry to the denylist.
denylist4 remove: Drop an entry from the denylist.
denylist4 flush: Empty the denylist.
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.
--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.
--verbose: Print some details regarding the translation operation.
--force: Apply operation even if certain validations fail.

Other Arguments

<Key> <Value>: Name of the variable you want to edit (see 'Globals' section), and its new value.
<IPv6-prefix>: The format is IPV6_ADDRESS[/PREFIX_LENGTH]. PREFIX_LENGTH defaults to 128.
<IPv4-prefix>: The format is IPV4_ADDRESS[/PREFIX_LENGTH]. PREFIX_LENGTH defaults to 32.
<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.

Globals

manually-enabled <Boolean>: Enable or disable the instance.
pool6 (<IPv6 Prefix> | null): The IPv6 pool's prefix.
The format is 'PREFIX_ADDRESS[/PREFIX_LENGTH]'.
Use null to clear.
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.
amend-udp-checksum-zero <Boolean>: Compute the UDP checksum of IPv4-UDP packets whose value is zero?
Otherwise drop the packet.
eam-hairpin-mode (simple | intrinsic | off): Defines how EAM+hairpinning is handled.
randomize-rfc6791-addresses <Boolean>: Randomize selection of address from the RFC6791 pool?
Otherwise choose the 'Hop Limit'th address.
rfc6791v6-prefix (<IPv6 Prefix> | null): IPv6 prefix to generate RFC6791v6 addresses from.
Use null to clear.
rfc6791v4-prefix (<IPv4 Prefix> | null): IPv4 prefix to generate RFC6791v4 addresses from.
Use null to clear.
trace <Boolean>: Log basic packet fields as they are received?

EXAMPLES

Create a new instance named "Example":
jool_siit instance add Example --iptables

Print the globals:
jool_siit -i Example global display

Change the IPv6 pool prefix:
jool_siit -i Example global update pool6 2001:db8::/96

Print the Explicit Address Mappings Table (EAMT):
jool_siit -i Example eamt display

Add an entry to the EAMT:
jool_siit -i Example eamt add 2001:db8::/120 192.0.2.0/24

Remove an entry from the EAMT:
jool_siit -i Example eamt remove 2001:db8::/120

Add denylist prefix 192.0.2.0/24:
jool_siit -i Example denylist4 add 192.0.2.0/24

Allow translation of 192.0.2.0/24:
jool_siit -i Example denylist4 remove 192.0.2.0/24

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

Our issue tracker is https://github.com/NICMx/Jool/issues. If you want to mail us instead, use jool@nic.mx.

COPYRIGHT

Copyright 2023 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.