Documentation > Userspace Clients > Atomic Configuration
Atomic Configuration
Index
Introduction
“Atomic Configuration” is a means to set up more than one of Jool’s parameters at once (using a single jool/jool_siit call). Either all or none of the new configuration will be applied, so you don’t have to worry about rolling back.
You can also think of it as “file configuration mode,” since JSON files are the means through which Atomic Configuration is retrieved.
Syntax
jool_siit [-i <instance name>] file handle <path to json file> [--force]jool [-i <instance name>] file handle <path to json file> [--force]--force silences warnings. (If you don’t silence them, sometimes they will cause operation abortion; eg. overlapping EAM entries.)
Semantics
The file describes one Jool instance. If the instance does not exist, it will be created. If it does exist, it will be updated. It will be an ordinary instance; you can subsequently apply any non-atomic operations on it, and delete it using instance remove as usual.
Most of the options are the same as their userspace client counterparts, so see Examples for a couple of full JSON files with embedded links to the relevant client documentation.
On the top level, the mandatory fields are the instance name (either through the -i client argument or the instance JSON tag) and the framework tag (which must be set to either netfilter or iptables).
Aside from vital fields from individual entries, everything else is optional, and will be initialized (or reinitialized) to default values (NOT “old” values!) on omission.
Unrecognized tags will trigger errors, but any amount of comments are allowed (and ignored) on all object contexts.
Examples
SIIT
{
"comment": {
"description": "Sample full SIIT configuration.",
"notes": [
"192.0.2/24, 198.51.100/24 and 2001:db8::/32 are",
"documentation blocks (RFC 5737 and RFC 3849), and you",
"WILL need to change or remove them for your setup."
],
"last update": "2022-02-09"
},
"instance": "sample-siit",
"framework": "netfilter",
"global": {
"manually-enabled": true,
"pool6": "2001:db8:0::/96",
"lowest-ipv6-mtu": 1280,
"logging-debug": false,
"zeroize-traffic-class": false,
"override-tos": false,
"tos": 0,
"mtu-plateaus": [
65535, 32000, 17914, 8166,
4352, 2002, 1492, 1006,
508, 296, 68
],
"amend-udp-checksum-zero": false,
"eam-hairpin-mode": "intrinsic",
"randomize-rfc6791-addresses": true,
"rfc6791v6-prefix": null,
"rfc6791v4-prefix": null
},
"eamt": [
{
"comment": "Comments allowed here too.",
"ipv6 prefix": "2001:db8:1::/128",
"ipv4 prefix": "192.0.2.0"
}, {
"ipv6 prefix": "2001:db8:2::",
"ipv4 prefix": "192.0.2.1/32"
}, {
"ipv6 prefix": "2001:db8:3::/124",
"ipv4 prefix": "192.0.2.16/28"
}
],
"comment": "This comment is relevant to denylist4 maybe.",
"denylist4": [
"198.51.100.0",
"198.51.100.2/32",
"198.51.100.32/27"
]
}Conceptually, updating an SIIT instance through atomic configuration is the same as dropping it and creating it anew. In practice, the former prevents the small window of time in which no translator exists.
Minimal SIIT configuration:
{
"instance": "siit-minimal",
"framework": "netfilter"
}NAT64
There is one major caveat here: The current implementation of BIB/session is not suitable to guarantee the atomicity of simultaneous modifications to a running database. Therefore, the bib tag below is only handled if the JSON file is being used to create a new instance. It will be silently ignored on updates.
Sorry. This does not necessarily mean that atomic updating of static BIB entries will never be implemented, but there are no plans for now.
Also, pool6 is mandatory and immutable (as normal). It must be set during instance creation and retain the same value on subsequent updates.
{
"comment": {
"description": "Sample full NAT64 configuration.",
"notes": [
"192.0.2/24 and 2001:db8::/32 are documentation blocks",
"(RFC 5737 and RFC 3849), and you WILL need to change or",
"remove them for your setup."
],
"last update": "2022-02-09"
},
"instance": "sample-nat64",
"framework": "netfilter",
"global": {
"manually-enabled": true,
"pool6": "64:ff9b::/96",
"lowest-ipv6-mtu": 1280,
"logging-debug": false,
"zeroize-traffic-class": false,
"override-tos": false,
"tos": 0,
"mtu-plateaus": [
65535, 32000, 17914, 8166,
4352, 2002, 1492, 1006,
508, 296, 68
],
"address-dependent-filtering": false,
"drop-externally-initiated-tcp": false,
"drop-icmpv6-info": false,
"source-icmpv6-errors-better": true,
"f-args": 11,
"handle-rst-during-fin-rcv": false,
"tcp-est-timeout": "2:00:00",
"tcp-trans-timeout": "0:04:00",
"udp-timeout": "0:05:00",
"icmp-timeout": "0:01:00",
"logging-bib": false,
"logging-session": false,
"maximum-simultaneous-opens": 10,
"ss-enabled": false,
"ss-flush-asap": true,
"ss-flush-deadline": 2000,
"ss-capacity": 512,
"ss-max-payload": 1452,
"ss-max-sessions-per-packet": 10
},
"pool4": [
{
"comment": "mark, port range and max-iterations are optional.",
"protocol": "TCP",
"prefix": "192.0.2.1/32"
}, {
"protocol": "TCP",
"prefix": "192.0.2.1/32",
"port range": "80"
}, {
"mark": 0,
"protocol": "UDP",
"prefix": "192.0.2.1/32",
"port range": "61001-62000",
"max-iterations": 1500
}, {
"mark": 0,
"protocol": "ICMP",
"prefix": "192.0.2.1/32",
"port range": "1000-2000"
}
],
"bib": [
{
"protocol": "TCP",
"ipv6 address": "2001:db8::1#80",
"ipv4 address": "192.0.2.1#80"
}, {
"protocol": "UDP",
"ipv6 address": "2001:db8::2#10000",
"ipv4 address": "192.0.2.1#61500"
}, {
"protocol": "ICMP",
"ipv6 address": "2001:db8:AAAA::1#44",
"ipv4 address": "192.0.2.1#1044"
}
]
}Updating a NAT64 instance through atomic configuration is not the same as dropping the instance and then creating another one in its place. Aside from skipping the translatorless time window through the former, you get to keep the BIB/session database.
Minimal NAT64 configuration:
{
"instance": "nat64-minimal",
"framework": "netfilter",
"global": {
"pool6": "64:ff9b::/96"
}
}
