jool(8)

📦
version 4.1.15 · 6 versions
, in nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ NAME ✨

jool — jool(8), NAT64 Jool's Userspace Client. Your way to interact with NAT64 Jool (the kernel module). You send commands, you send requests, you get things done. no cap. 💖

💖 DESCRIPTION 💖

Okay so listen. jool is the userspace client that sends commands and requests to NAT64 Jool. And NAT64 Jool? It's a kernel module — you load it into a Linux kernel. It implements RFC 6146. That's the whole thing. It's giving networking royalty. 👑

🌈 AVAILABILITY 🌈

Linux is literally the only OS where this program makes sense. Like, don't try this on anything else, bestie. 🐧

Kernels 5.15 and up. Periodt.

🎀 SYNTAX 🎀

Here's the whole syntax tree, bestie. The pipes (|) mean "or", the brackets mean optional, and the nested stuff is just doing its little dance. 💃

       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>] pool4 (
            display
                 [--csv]
                 [--no-headers]
                 [--tcp | --udp | --icmp]
            | add
                 <IPv4-Address> <Ports>
                 [--tcp | --udp | --icmp]
                 [--mark <Mark>]
                 [--max-iterations (auto | infinity | <Iterations>)]
                 [--force]
            | remove
                 <IPv4-Address> <Ports>
                 [--tcp | --udp | --icmp]
                 [--mark <Mark>]
                 [--quick]
            | flush
                 [--quick]
       )

       jool [<argp1>] bib (
            display
                 [--csv]
                 [--no-headers]
                 [--tcp | --udp | --icmp]
                 [--numeric]
            | add
                 <IPv6-Transport-Address>
                 <IPv4-Transport-Address>
                 [--tcp | --udp | --icmp]
            | remove
                 [<IPv6-Transport-Address>]
                 [<IPv4-Transport-Address>]
                 [--tcp | --udp | --icmp]
       )

       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

okay bestie, this is the fun part — these are literally the verbs you're telling jool to do. pick one, stack it with the flags below, and go off 💅

  • instance display — shows you every instance from every namespace. all of them. the whole squad. 👑
  • instance add — makes a brand new instance. baby's first NAT64, so cute 🍼
  • instance remove — yeets an existing instance into the void. bye bestie 👋
  • instance flush — drops all instances from the current namespace. it's giving "clear the group chat" energy 💀
  • stats display — shows the internal counters. the receipts, basically 📊
  • global display — shows you what the instance's tweakable internal variables are currently set to. the current vibe, quantified ✨
  • global update — changes one of those internal variables. glow-up time 🌸
  • pool4 display — shows you one of the tables from the IPv4 transport address pool. (every protocol gets its own table, jsyk)
  • pool4 add — uploads an entry to the IPv4 transport address pool 📥
  • pool4 remove — drops transport addresses out of the IPv4 transport address pool
  • pool4 flush — empties the IPv4 transport address pool entirely. total reset 🧹
  • bib display — shows you one of the BIB tables. (again, one table per protocol)
  • bib add — adds a static entry to the BIB
  • bib remove — removes an entry from the BIB, static or not, doesn't matter
  • session display — shows you one of the session tables. (you guessed it, one per protocol)
  • session follow — listens to the instance's sessions forever, printing them to standard output whenever they get updated. the way it just keeps watching 👀 the instance needs ss-enabled=1 for this to work.
  • session proxy — listens to sessions forever and exchanges them between the instance and other listening proxies. the -i instance needs ss-enabled=1 here too.
  • session advertise — asks the instance to send its whole entire session table to all the listening followers and proxies. "hey everyone, look at my sessions" 📢
  • file handle — parses all the config out of a JSON file. if the instance doesn't exist it creates it, if it does exist it updates it. lowkey the most useful one ngl

🌈 Flags

  • --instance <Name> — the name of the instance you wanna interact with. it's an ASCII string, 15 characters max. defaults to 'default'.
  • --file <File> — a JSON file containing 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, so if you're a TCP girlie you can just vibe)
  • --udp — apply the operation on the UDP table.
  • --icmp — apply the operation on the ICMP table.
  • --csv — output in CSV table format. spreadsheet girlies rise 🫶
  • --no-headers — don't print the table headers. (nor the footer, if one applies.)
  • --netfilter — sit the instance on top of the Netfilter framework.
  • --iptables — sit the instance on top of the iptables framework.
  • --pool6 <IPv6-prefix> — the 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 get printed.)
  • --explain — show a description of each counter. it explains itself, iconic 💅
  • --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>) — the maximum number of times the mask-finding algorithm is allowed to iterate. auto computes a recommended default, infinity removes the iteration cap entirely (yolo), and <Iterations> (an unsigned 32-bit integer) sets the actual number.
  • --force — apply the operation even if certain validations fail. chaotic but valid 🔥
  • --quick — don't remove orphaned BIB and session entries.
  • --numeric — don't query the DNS.

🦋 Other Arguments

  • <Key> <Value> — the name of the variable you want to edit (check the Globals section below bestie) and its new value.
  • <IPv4-Address> <Ports> — a descriptor of the range of transport addresses you want to add to or remove from the pool. <Ports> is a range of ports and it should follow the format '<Min>[-<Max>]'. the command will add or remove addresses <IPv4-Address>#<Min> through <IPv4-Address>#<Max>.
  • <IPv6-transport-address>, <IPv4-transport-address> — the 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> — the name of the instance you want to add or remove. if --instance or --file were included in <argp1>, then the instance names have to match.
  • <JSON-file> — path to a JSON file.
  • <NETMCASTADDR> — the address SS traffic will be sent to and listened from.
  • <NETMCASTPORT> — the UDP port where SS traffic will be sent to and listened from.
  • <NETDEVIN> — the address or interface to bind the socket in. if <NETMCASTADDR> is IPv4, this should be one address 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 address 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 the (optional) statistics server.
  • <STATSPORT> — port for the <STATSADDR> server.

💜 Globals

these are the variables you can poke with global display and global update. get to know them, they're your new besties 💖

  • 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> — the 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 it copies from the IPv4 header's 'TOS'.
  • override-tos <Boolean> — override the IPv4 header's 'TOS' field as --tos? otherwise it copies from the IPv6 header's 'Traffic Class'.
  • tos <Unsigned 8-bit integer> — the 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 the 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 🌸

okay here's where it gets fun, copy-paste these and you're basically a network engineer 💅

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, so go wild bestie 💖

💀 EXIT STATUS 💀

Zero on success, non-zero on failure. simple as, fr fr.

👑 AUTHOR 👑

NIC Mexico & ITESM

🐛 REPORTING BUGS 🐛

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

Copyright 2011 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. (bestie. they mean it. no takebacks 😭)

🦋 SEE ALSO 🦋

and that's the whole page, bestie!! 🎀 this version is v4.1.15, dated 2026-01-26, and it lives in section jool(8) — go forth and translate some addresses, you absolute icon 💅✨

📦 where this page comes from