From 8d2edffe40fc9ebcb558e88e66662ee813e00b5c Mon Sep 17 00:00:00 2001 From: Alberto Leiva Popper Date: Sat, 22 Jun 2024 17:48:31 -0600 Subject: [PATCH] Protocolary updates for release 4.1.12 --- configure.ac | 2 +- docs/_config.yml | 2 +- docs/en/config-joold.md | 35 +++++++++++++++++-- docs/en/download.md | 5 +-- docs/en/index.md | 20 ++++------- docs/en/intro-jool.md | 5 ++- src/common/xlat.h | 4 +-- src/usr/joold/joold.8 | 75 +++++++++++++++++++++++++++++++++------- src/usr/nat64/jool.8 | 6 ++-- src/usr/siit/jool_siit.8 | 6 ++-- test/graybox/README.md | 2 ++ 11 files changed, 119 insertions(+), 43 deletions(-) diff --git a/configure.ac b/configure.ac index 79f806a37..a2dd366e4 100644 --- a/configure.ac +++ b/configure.ac @@ -2,7 +2,7 @@ # Process this file with autoconf to produce a configure script. AC_PREREQ([2.68]) -AC_INIT([Jool], [4.1.11], [ydahhrk@gmail.com]) +AC_INIT([Jool], [4.1.12], [ydahhrk@gmail.com]) AC_CONFIG_SRCDIR([src/common/xlat.h]) AM_INIT_AUTOMAKE([subdir-objects]) LT_PREREQ([2.4.6]) diff --git a/docs/_config.yml b/docs/_config.yml index 45e11196d..25c19ec14 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,7 +1,7 @@ markdown: kramdown baseurl: /Jool repository-url: https://github.com/NICMx/Jool -latest-version: 4.1.11 +latest-version: 4.1.12 rfc-siit: https://tools.ietf.org/html/rfc7915 draft-siit-eam: https://tools.ietf.org/html/rfc7757 diff --git a/docs/en/config-joold.md b/docs/en/config-joold.md index 1520b48af..db9c78d31 100644 --- a/docs/en/config-joold.md +++ b/docs/en/config-joold.md @@ -19,14 +19,17 @@ title: Daemon Configuration Options 4. [`out interface`](#out-interface) 5. [`reuseaddr`](#reuseaddr) 6. [`ttl`](#ttl) +3. [Module Socket Configuration File](#module-socket-configuration-file) + 1. [`instance`](#instance) +4. [Stats Server Port](#stats-server-port) ## Introduction `joold` (Jool's userspace daemon binary) is part of the [Session Synchronization](session-synchronization.html) gimmic. Follow the link for context. -It expects two optional files as program arguments: +It expects two files and one port number as optionl program arguments: - $ joold [/path/to/netsocket/config] [/path/to/modsocket/config] + $ joold [/path/to/netsocket/config] [/path/to/modsocket/config] [UDP stats server port] The "net socket" file name defaults to `netsocket.json`, and the "module socket" file name defaults to `modsocket.json`. (They are both expected to be found in the same directory the command is executed in.) @@ -164,3 +167,31 @@ Name of the instance the daemon is supposed to synchronize. It's the one you des The instance is expected to exist within the same network namespace the daemon is running in. +## Stats Server Port + +A port number joold will use to serve stats via UDP. If absent, the server will not be started. + +Start joold with a third argument representing the port number: + +```bash +$ joold netsocket.json modsocket.json 45678 +``` + +It's rudimentary. Query using a simple UDP request: + +```bash +$ 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 +``` + +- `KERNEL_SENT_PKTS`: Packets sent to the kernel module. (It should match the local instance's `JSTAT_JOOLD_PKT_RCVD` stat.) +- `KERNEL_SENT_BYTES`: Session bytes sent to the kernel module. (It should match the local instance's `JSTAT_JOOLD_SSS_RCVD` multiplied by the session size.) +- `NET_RCVD_PKTS`: Packets received from the network. (It should match the remote instance's `JSTAT_JOOLD_PKT_SENT`.) +- `NET_RCVD_BYTES`: Session bytes received from the network. (It should match the remote instance's `JSTAT_JOOLD_SSS_SENT` multiplied by the session size.) +- `NET_SENT_PKTS`: Packets sent to the network. (It should match the remote joold's `NET_RCVD_PKTS`.) +- `NET_SENT_BYTES`: Session bytes sent to the network. (It should match the remote joold's `NET_RCVD_BYTES`.) diff --git a/docs/en/download.md b/docs/en/download.md index 1f25259ee..b7611903f 100644 --- a/docs/en/download.md +++ b/docs/en/download.md @@ -27,11 +27,12 @@ Jool 4.2 is a compliant SIIT, Stateful NAT64 and MAP-T. Jool 4.1 is a [compliant SIIT and Stateful NAT64](intro-jool.html#compliance). -Currently, 4.1.11 is the most mature version of Jool. +Currently, 4.1.12 is the most mature version of Jool. | Release Date | Version | .tar.gz | .tar.gz Signature | Git commit | .deb | |--------------|---------|---------|-------------------|------------|------| -| 2023-12-22 | **4.1.11** | [Download]({{ page.url-dl }}/v4.1.11/jool-4.1.11.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.11/jool-4.1.11.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.11/jool-dkms_4.1.11-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.11/jool-tools_4.1.11-1_amd64.deb) (amd64 only) | +| 2024-06-22 | **4.1.12** | [Download]({{ page.url-dl }}/v4.1.12/jool-4.1.12.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.12/jool-4.1.12.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.12/jool-dkms_4.1.12-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.12/jool-tools_4.1.12-1_amd64.deb) (amd64 only) | +| 2023-12-22 | 4.1.11 | [Download]({{ page.url-dl }}/v4.1.11/jool-4.1.11.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.11/jool-4.1.11.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.11/jool-dkms_4.1.11-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.11/jool-tools_4.1.11-1_amd64.deb) (amd64 only) | | 2023-06-11 | 4.1.10 | [Download]({{ page.url-dl }}/v4.1.10/jool-4.1.10.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.10/jool-4.1.10.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.10/jool-dkms_4.1.10-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.10/jool-tools_4.1.10-1_amd64.deb) (amd64 only) | | 2023-01-25 | 4.1.9 | [Download]({{ page.url-dl }}/v4.1.9/jool-4.1.9.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.9/jool-4.1.9.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.9/jool-dkms_4.1.9-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.9/jool-tools_4.1.9-1_amd64.deb) (amd64 only) | | 2022-03-20 | 4.1.8 | [Download]({{ page.url-dl }}/v4.1.8/jool-4.1.8.tar.gz) | [Signature]({{ page.url-dl }}/v4.1.8/jool-4.1.8.tar.gz.asc) | Link | [Kernel modules]({{ page.url-dl }}/v4.1.8/jool-dkms_4.1.8-1_all.deb)
[Userspace tools]({{ page.url-dl }}/v4.1.8/jool-tools_4.1.8-1_amd64.deb) (amd64 only) | diff --git a/docs/en/index.md b/docs/en/index.md index 563754ee9..534ca2de1 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -22,7 +22,7 @@ Jool is an Open Source [SIIT and NAT64](intro-xlat.html) for Linux. > ![Warning](../images/warning.svg) The project's development has slowed down to essential maintenance. Bugfixing and support will remain active, but there will be no new features in the foreseeable future. -- The most mature version is [4.1.11](download.html#41x). +- The most mature version is [4.1.12](download.html#41x). - The second release candidate for version [4.2.0](download.html#42x) is also available now. - **jool.mx is no longer maintained. Please use https://nicmx.github.io/Jool instead.** @@ -30,18 +30,10 @@ Jool is an Open Source [SIIT and NAT64](intro-xlat.html) for Linux. ## Latest News -### 2023-12-23 +### 2024-06-22 -Version 4.1.11 has been released. Bugfixes: +Version 4.1.12 has been released. Bugfixes: -- [#407](https://github.com/NICMx/Jool/issues/407): Patch compilation in some environments. -- [#409](https://github.com/NICMx/Jool/issues/409): Move the Debian systemd service to After=network-pre.target, to prevent deadlock during boot in some environments. -- [750909d](https://github.com/NICMx/Jool/commit/750909dd3f0df8771883121b1820f7e10010ff31): When running into an untranslatable address, print it clearly in the logs. -- [#413](https://github.com/NICMx/Jool/issues/413): Enhance validations of pool4, BIB and session userspace requests. -- [#415](https://github.com/NICMx/Jool/issues/415), [Debian#1057445](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1057445): Add support for kernel 6.4, 6.5, 6.6 and 6.7-rc6. -- [#417](https://github.com/NICMx/Jool/issues/417): Add support for RHEL 9.2 and 9.3. -- [Debian#1046037](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1046037): Add the "distclean" target to the kernel module Makefiles. -- [Debian#1057703](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1057703): Remove mime-support from build dependencies. -- [Debian#1041856](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1041856): Remove all links to jool.mx in the Debian package. - -There have also been several patches [in](https://github.com/NICMx/Jool/commit/4eb5b3e3ec9d671067e571f6eee08d95a4a34091) [the](https://github.com/NICMx/Jool/commit/8c78ed47c51f2ee10cc63058014212887c340122) [joold](https://github.com/NICMx/Jool/commit/07e6fd9a4eb93cc27f271ef1cd526b155edc66a4) [code](https://github.com/NICMx/Jool/commit/4fcfe184d9444ef25d3e5ab5995a06c8bed8b9d2), but this is still an [ongoing effort](https://github.com/NICMx/Jool/issues/410). You might want to abstain from using joold at the moment. +- [#410](https://github.com/NICMx/Jool/issues/410): Fix several joold bugs. Also, add [joold stats](config-joold.html#stats-server-port). +- Add [support](intro-jool.html#compatibility) for kernels 6.8, 6.9, 6.10(-rc4), RHEL 8.10 and 9.4. (No changes needed.) +- Patch some rust in the ["graybox" testing framework](https://github.com/NICMx/Jool/tree/main/test/graybox). diff --git a/docs/en/intro-jool.md b/docs/en/intro-jool.md index 6721dae29..5baa4bc90 100644 --- a/docs/en/intro-jool.md +++ b/docs/en/intro-jool.md @@ -46,11 +46,10 @@ Please [let us know]({{ site.repository-url }}/issues) if you find additional co ## Compatibility - - | Jool version | Supported Linux kernels (mainline) | Supported Linux kernels (RHEL) | |-------------------------------------|--------------------------------------|--------------------------------| -| [main]({{ site.repository-url }}),
[4.1.11](download.html#41x) | 4.18 - 4.20,
5.0 - 5.19,
6.0 - 6.7 | RHEL 8.6 - 8.9,
RHEL 9.0 - 9.3 | +| [main]({{ site.repository-url }}),
[4.1.12](download.html#41x) | 4.19 - 4.20,
5.0 - 5.19,
6.0 - 6.10(-rc4) | RHEL 8.9 - 8.10,
RHEL 9.0 - 9.4 | +| [4.1.11](download.html#41x) | 4.18 - 4.20,
5.0 - 5.19,
6.0 - 6.7 | RHEL 8.6 - 8.9,
RHEL 9.0 - 9.3 | | [4.1.10](download.html#41x) | 4.14 - 4.20,
5.0 - 5.19,
6.0 - 6.3 | RHEL 8.6 - 8.7,
RHEL 9.0 - 9.3 | | [4.1.9](download.html#41x) | 4.9 - 4.20,
5.0 - 5.19,
6.0 - 6.1 | RHEL 8.6 - 8.7,
RHEL 9.0 - 9.1 | | [4.1.8](download.html#41x) | 4.9 - 4.20,
5.0 - 5.16 | RHEL 8.5 | diff --git a/src/common/xlat.h b/src/common/xlat.h index d6cc51f9a..fcc76fda4 100644 --- a/src/common/xlat.h +++ b/src/common/xlat.h @@ -9,8 +9,8 @@ */ #define JOOL_VERSION_MAJOR 4 #define JOOL_VERSION_MINOR 1 -#define JOOL_VERSION_REV 11 -#define JOOL_VERSION_DEV 1 +#define JOOL_VERSION_REV 12 +#define JOOL_VERSION_DEV 0 /** See http://stackoverflow.com/questions/195975 */ #define STR_VALUE(arg) #arg diff --git a/src/usr/joold/joold.8 b/src/usr/joold/joold.8 index 8ec14e3c5..eeba769e3 100644 --- a/src/usr/joold/joold.8 +++ b/src/usr/joold/joold.8 @@ -1,6 +1,6 @@ .\" Manpage for jool's session synchronization daemon. -.TH joold 8 2023-12-22 v4.1.11 "NAT64 Jool's Session Synchronization Daemon" +.TH joold 8 2024-06-22 v4.1.12 "NAT64 Jool's Session Synchronization Daemon" .SH NAME joold - Userspace Session Synchronization (SS) daemon for NAT64 Jool. @@ -17,18 +17,24 @@ Running the daemons is not enough to have successful session synchronization; SS .SH AVAILABILITY Linux is the only OS in which this program makes sense. .br -Kernels 4.14 and up. +Kernels 4.19 and up. .SH SYNTAX -.RI "joold [" FILE "]" +.RI "joold [" NETSOCKET "] [" MODSOCKET "] [PORT]" .SH OPTIONS -.IP FILE +.IP NETSOCKET Path to JSON file containing the network socket's configuration. .br Defaults to "netsocket.json". + +.IP MODSOCKET +Path to JSON file containing the Netlink socket's configuration. .br -(The Netlink socket currently does not need configuration.) +Defaults to "modsocket.json". + +.IP PORT +If present, starts an UDP server bound to port PORT, where the daemon serves stat counters. .SH NETWORK SOCKET CONFIGURATION The file is a JSON-formatted collection of keyvalues. @@ -63,6 +69,17 @@ Please always include and enable this. .IP ttl= Time-to-live of packets sent out by this socket. +.SH NETLINK SOCKET CONFIGURATION +The file is a JSON-formatted collection of keyvalues. + +.IP instance= +Name of the instance the daemon is supposed to synchronize. It's the one you designate during +.B jool instance add. +.br +The instance is expected to exist within the same network namespace the daemon is running in. +.br +As usual, it defaults to "default". + .SH EXAMPLES IPv6 version: .P @@ -84,7 +101,7 @@ IPv6 version: .br $ cat ipv6-netsocket.json .br - { + { .br "multicast address": "ff08::db8:64:64", .br @@ -98,9 +115,17 @@ IPv6 version: .br "ttl": 3 .br - } + } .br - $ joold ipv6-netsocket.json & + $ +.br + $ cat modsocket.json +.br + { "instance": "default" } +.br + $ +.br + $ joold ipv6-netsocket.json modsocket.json 45678 & .P IPv4 version: .P @@ -122,7 +147,7 @@ IPv4 version: .br $ cat ipv4-netsocket.json .br - { + { .br "multicast address": "233.252.0.64", .br @@ -136,9 +161,33 @@ IPv4 version: .br "ttl": 3 .br - } + } +.br + $ .br - $ joold ipv4-netsocket.json & + $ cat modsocket.json +.br + { "instance": "default" } +.br + $ +.br + $ joold ipv4-netsocket.json modsocket.json 45678 & +.P +Request stats: +.P + $ echo "" | nc -u 127.0.0.1 45678 +.br + KERNEL_SENT_PKTS,4 +.br + KERNEL_SENT_BYTES,208 +.br + NET_RCVD_PKTS,0 +.br + NET_RCVD_BYTES,0 +.br + NET_SENT_PKTS,4 +.br + NET_SENT_BYTES,208 .SH EXIT STATUS Zero on success, non-zero on failure. @@ -157,7 +206,7 @@ https://github.com/NICMx/Jool/issues 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. .SH COPYRIGHT -Copyright 2023 NIC Mexico. +Copyright 2024 NIC Mexico. .br License: GPLv2 (GNU GPL version 2) .br @@ -166,6 +215,8 @@ There is NO WARRANTY, to the extent permitted by law. .SH SEE ALSO https://nicmx.github.io/Jool/en/session-synchronization.html +.br https://nicmx.github.io/Jool/en/config-joold.html +.br https://nicmx.github.io/Jool/en/usr-flags-joold.html diff --git a/src/usr/nat64/jool.8 b/src/usr/nat64/jool.8 index 2ba03a888..99391435e 100644 --- a/src/usr/nat64/jool.8 +++ b/src/usr/nat64/jool.8 @@ -1,6 +1,6 @@ .\" Manpage for jool's userspace app. -.TH jool 8 2023-12-22 v4.1.11 "NAT64 Jool's Userspace Client" +.TH jool 8 2024-06-22 v4.1.12 "NAT64 Jool's Userspace Client" .SH NAME jool - Interact with NAT64 Jool (the kernel module). @@ -13,7 +13,7 @@ NAT64 Jool is a kernel module you load into a Linux kernel. It implements RFC 61 .SH AVAILABILITY Linux is the only OS in which this program makes sense. .br -Kernels 4.14 and up. +Kernels 4.19 and up. .SH SYNTAX .RI "jool [" "] instance (" @@ -413,7 +413,7 @@ NIC Mexico & ITESM https://github.com/NICMx/Jool/issues .SH COPYRIGHT -Copyright 2023 NIC Mexico. +Copyright 2024 NIC Mexico. .br License: GPLv2 (GNU GPL version 2) .br diff --git a/src/usr/siit/jool_siit.8 b/src/usr/siit/jool_siit.8 index 06fbed326..490905031 100644 --- a/src/usr/siit/jool_siit.8 +++ b/src/usr/siit/jool_siit.8 @@ -1,6 +1,6 @@ .\" Manpage for jool's userspace app. -.TH jool_siit 8 2023-12-22 v4.1.11 "SIIT Jool's Userspace Client" +.TH jool_siit 8 2024-06-22 v4.1.12 "SIIT Jool's Userspace Client" .SH NAME jool_siit - Interact with SIIT Jool (the kernel module). @@ -13,7 +13,7 @@ SIIT Jool is a kernel module you load into a Linux kernel. It implements RFC 791 .SH AVAILABILITY Linux is the only OS in which this program makes sense. .br -Kernels 4.14 and up. +Kernels 4.19 and up. .SH SYNTAX .RI "jool_siit [" "] instance (" @@ -319,7 +319,7 @@ NIC Mexico & ITESM https://github.com/NICMx/Jool/issues .SH COPYRIGHT -Copyright 2023 NIC Mexico. +Copyright 2024 NIC Mexico. .br License: GPLv2 (GNU GPL version 2) .br diff --git a/test/graybox/README.md b/test/graybox/README.md index 646b95eef..994d0fee9 100644 --- a/test/graybox/README.md +++ b/test/graybox/README.md @@ -2,6 +2,8 @@ The "graybox" tests are the logical step after the unit tests. They are a bunch of packet exchanges between a custom IPv6/v4 raw packet sender and validator (named `graybox`) and an actual Jool binary. +The name used to stem from "Gray Box Testing," but it quickly became an additional white box. + ## Compiling the test binaries Install libnl-genl-3-dev, then