Protocolary updates for release 4.1.12

NICMx · Jun 23, 2024 · 8d2edff · 8d2edff
1 parent b073d34
commit 8d2edff
Show file tree

Hide file tree

Showing 11 changed files with 119 additions and 43 deletions.
diff --git 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], [[email protected]])
+AC_INIT([Jool], [4.1.12], [[email protected]])
 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
@@ -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
@@ -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
@@ -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) | <a href="{{ site.repository-url }}/tree/v4.1.11" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.11/jool-dkms_4.1.11-1_all.deb)<br />[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) | <a href="{{ site.repository-url }}/tree/v4.1.12" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.12/jool-dkms_4.1.12-1_all.deb)<br />[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) | <a href="{{ site.repository-url }}/tree/v4.1.11" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.11/jool-dkms_4.1.11-1_all.deb)<br />[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) | <a href="{{ site.repository-url }}/tree/v4.1.10" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.10/jool-dkms_4.1.10-1_all.deb)<br />[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) | <a href="{{ site.repository-url }}/tree/v4.1.9" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.9/jool-dkms_4.1.9-1_all.deb)<br />[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) | <a href="{{ site.repository-url }}/tree/v4.1.8" target="_blank">Link</a> | [Kernel modules]({{ page.url-dl }}/v4.1.8/jool-dkms_4.1.8-1_all.deb)<br />[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
@@ -22,26 +22,18 @@ 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.**
 
 -------------------
 
 ## 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
@@ -46,11 +46,10 @@ Please [let us know]({{ site.repository-url }}/issues) if you find additional co
 
 ## Compatibility
 
-<!-- Remember: The man pages mention the lowest supported kernel. -->
-
 | Jool version                        | Supported Linux kernels (mainline)   | Supported Linux kernels (RHEL) |
 |-------------------------------------|--------------------------------------|--------------------------------|
-| [main]({{ site.repository-url }}),<br />[4.1.11](download.html#41x) | 4.18 - 4.20,<br />5.0 - 5.19,<br />6.0 - 6.7 | RHEL 8.6 - 8.9,<br />RHEL 9.0 - 9.3 |
+| [main]({{ site.repository-url }}),<br />[4.1.12](download.html#41x) | 4.19 - 4.20,<br />5.0 - 5.19,<br />6.0 - 6.10(-rc4) | RHEL 8.9 - 8.10,<br />RHEL 9.0 - 9.4 |
+| [4.1.11](download.html#41x) | 4.18 - 4.20,<br />5.0 - 5.19,<br />6.0 - 6.7 | RHEL 8.6 - 8.9,<br />RHEL 9.0 - 9.3 |
 | [4.1.10](download.html#41x) | 4.14 - 4.20,<br />5.0 - 5.19,<br />6.0 - 6.3 | RHEL 8.6 - 8.7,<br />RHEL 9.0 - 9.3 |
 | [4.1.9](download.html#41x) | 4.9 - 4.20,<br />5.0 - 5.19,<br />6.0 - 6.1 | RHEL 8.6 - 8.7,<br />RHEL 9.0 - 9.1 |
 | [4.1.8](download.html#41x) | 4.9 - 4.20,<br />5.0 - 5.16 | RHEL 8.5 |

diff --git 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
@@ -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=<INT>
 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=<String>
+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
@@ -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 [" <argp1> "] 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
@@ -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 [" <argp1> "] 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
@@ -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