oracular (8) joold.8.gz

Provided by: jool-tools_4.1.12-1_amd64 bug

NAME

       joold - Userspace Session Synchronization (SS) daemon for NAT64 Jool.

DESCRIPTION

       Opens  two sockets: A Netlink socket to the current namespace's NAT64 Jool instance, and a
       network TCP socket to other/remote joold instances.  Exchanges  sessions  indiscriminately
       between them.

       The  intent  is  to  keep  the NAT64 session databases synchronized for the sake of having
       backup fallback NAT64s.

       The setup is strongly recommended  to  be  Active/Passive;  Active/Active  is  technically
       allowed, but not very reliable.

       Running  the daemons is not enough to have successful session synchronization; SS needs to
       be enabled in the kernel instances as well. (See the --ss-* flags described in jool(8).)

AVAILABILITY

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

SYNTAX

       joold [NETSOCKET] [MODSOCKET] [PORT]

OPTIONS

       NETSOCKET
              Path to JSON file containing the network socket's configuration.
              Defaults to "netsocket.json".

       MODSOCKET
              Path to JSON file containing the Netlink socket's configuration.
              Defaults to "modsocket.json".

       PORT   If present, starts an UDP server bound to port PORT, where the daemon  serves  stat
              counters.

NETWORK SOCKET CONFIGURATION

       The file is a JSON-formatted collection of keyvalues.

       multicast address=<IPv6-or-IPv4-address>
              IP Address the SS traffic will be sent to and listened from.
              Mandatory; has no default.

       multicast port=<port-or-service-name>
              TCP port where the SS traffic will be sent to and listened from.
              Mandatory; has no default.

       in interface=<String>
              If multicast address is IPv4, this should be one addresses from the interface where
              the SS traffic is expected to be received.  If  multicast  address  is  IPv6,  this
              should be the name of the interface (eg. "eth0").
              Optional. Defaults to be automatically assigned by the kernel.
              It is strongly recommended that you define this value to ensure the SS traffic does
              not leak through other interfaces.

       out interface=<String>
              If multicast address is IPv4, this should be one addresses from the interface where
              the  multicast  traffic  is expected to be sent. If multicast address is IPv6, this
              should be the name of the interface (eg. "eth0").
              Optional. Defaults to be automatically assigned by the kernel.
              It is strongly recommended that you define this value to ensure the SS traffic does
              not leak through other interfaces.

       reuseaddr=<INT>
              Please always include and enable this.

       ttl=<INT>
              Time-to-live of packets sent out by this socket.

       The file is a JSON-formatted collection of keyvalues.

       instance=<String>
              Name  of  the  instance  the  daemon  is  supposed to synchronize. It's the one you
              designate during jool instance add.
              The instance is expected to exist within the same network namespace the  daemon  is
              running in.
              As usual, it defaults to "default".

EXAMPLES

       IPv6 version:

            $ # All Jool instances should have the basic configuration.
            $ jool --file same-config-as-everyone-else.json
            $
            $ # Configure the SS interface
            $ ip addr add 2001:db8:ff08::4/96 dev eth0
            $ ip link set eth0 up
            $
            $ # joold
            $ cat ipv6-netsocket.json
              {
                 "multicast address": "ff08::db8:64:64",
                 "multicast port": "6464",
                 "in interface": "eth0",
                 "out interface": "eth0",
                 "reuseaddr": 1,
                 "ttl": 3
              }
            $
            $ cat modsocket.json
              { "instance": "default" }
            $
            $ joold ipv6-netsocket.json modsocket.json 45678 &

       IPv4 version:

            $ # All Jool instances should have the basic configuration.
            $ jool --file same-config-as-everyone-else.json
            $
            $ # Configure the SS interface
            $ ip addr add 192.0.2.1/24 dev eth0
            $ ip link set eth0 up
            $
            $ # joold
            $ cat ipv4-netsocket.json
              {
                 "multicast address": "233.252.0.64",
                 "multicast port": "6464",
                 "in interface": "192.0.2.1",
                 "out interface": "192.0.2.1",
                 "reuseaddr": 1,
                 "ttl": 3
              }
            $
            $ cat modsocket.json
              { "instance": "default" }
            $
            $ joold ipv4-netsocket.json modsocket.json 45678 &

       Request stats:

            $ echo "" | nc -u 127.0.0.1 45678
            KERNEL_SENT_PKTS,4
            KERNEL_SENT_BYTES,208
            NET_RCVD_PKTS,0
            NET_RCVD_BYTES,0
            NET_SENT_PKTS,4
            NET_SENT_BYTES,208

EXIT STATUS

       Zero on success, non-zero on failure.

AUTHOR

       NIC Mexico & ITESM

REPORTING BUGS

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

KNOWN BUGS

       1. reuseaddr should probably default to 1...
       2. Maybe the daemon should be able to automatically enable SS on the kernel module.

       To  be  perfectly  honest,  the  main reason why fixing this isn't in the radar is because
       joold is giving me the impression that nobody is using it.

       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.

SEE ALSO

       https://nicmx.github.io/Jool/en/session-synchronization.html
       https://nicmx.github.io/Jool/en/config-joold.html
       https://nicmx.github.io/Jool/en/usr-flags-joold.html