Merge pull request #375 from nuclearcat/doc-updates

Doc updates

9 files changed, 302 insertions, 131 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f6bdeec..af27812c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,8 +9,104 @@
   please object at https://github.com/accel-ppp/accel-ppp/issues, otherwise it
   will be deleted.
 
+### Compatibility
+- PPTP: removed the obsolete out-of-tree kernel driver and the
+  `BUILD_PPTP_DRIVER` option. The userspace PPTP module remains available;
+  use the Linux kernel's PPTP PPPoX support (`CONFIG_PPTP`).
+- IP pools: IPv4 and IPv6 pools now use bitmap allocators. Each range is
+  limited to 2^24 allocation units (IPv4 addresses or net30 blocks, or IPv6
+  prefixes); larger ranges are skipped with an error. The legacy IPv4
+  `gw=` range option is deprecated and ignored; use `gw-ip-address` for
+  the local PPP address.
+- Module API: statistics are exposed through snapshot/getter functions
+  instead of writable exported counters, and the Triton reload callback
+  signature has changed. External modules using those interfaces need
+  adaptation and rebuilding.
+
 ### Features
-- New `metrics` module: HTTP endpoint exposing the same numbers as `accel-cmd show stat` at `/metrics`, in either Prometheus exposition or JSON format. Configurable listen address and optional IPv4 CIDR allow-list.
+- Metrics: new HTTP `/metrics` endpoint with Prometheus and JSON output,
+  an IPv4 CIDR allow-list, read timeouts, and a client limit. Optional
+  `sessions=1` adds per-session details to JSON output and is disabled by
+  default. Enable `metrics` in `[modules]` and configure `[metrics]` to use it.
+- IP pools: reload IPv4 and IPv6 pools without restarting the daemon.
+  `reload-orphan=keep|disconnect` controls sessions whose address or prefix
+  leaves the configured pools; the default is `keep`.
+- SSTP: optional PPPoSEQ kernel transport avoids userspace HDLC framing.
+  Build and install it with `BUILD_PPPOSEQ_DRIVER=TRUE`. At startup,
+  `[sstp] ppp-mode=auto` selects it when available and otherwise uses async
+  PPP; `seqpacket` and `async` select the transport explicitly.
+- IPv6: per-session DNS servers from RADIUS `DNS-Server-IPv6-Address`
+  attributes (RFC 6911), used by Router Advertisements and DHCPv6.
+  Assigned servers replace `[ipv6-dns]` defaults for that session.
+  Removed the three-server configuration limit; advertised lists remain
+  bounded by packet capacity.
+- CLI: IPv6 support for TCP and Telnet listeners.
+- RADIUS: optional `framed-route-strict=1` rejects IPv4 routes with host
+  bits set in the destination prefix. The default remains permissive.
+- IPoE: bulk cleanup of stale session interfaces after daemon restarts,
+  with a fallback for older kernel modules, and support for removing
+  session interfaces with `ip link del`.
+
+### Fixes
+- RADIUS: verify response authenticators against the request and secret
+  actually sent before delivering replies or updating server health.
+  Fix outbound Message-Authenticator calculation on retransmission and
+  accounting request signing, including Accounting-On/Off.
+- RADIUS: fix request/socket leaks, accounting-stop cleanup, secret reloads,
+  route parsing, attribute bounds, and VRF name validation for Access-Accept
+  and CoA. Only the literal CoA value `0` removes a VRF; names beginning
+  with `0` are treated as interface names.
+- PPP: validate control-packet lengths and option boundaries, avoid
+  unaligned accesses, and clear reused packet buffers. Fix unit descriptor
+  cleanup races and unit-cache locking.
+- PPP: keep optional IPv6 termination from ending the whole session;
+  defer IPCP/IPV6CP acknowledgements while CCP negotiates instead of
+  sending premature TermAck responses. Correct default IPv6 interface-ID
+  byte order on little-endian hosts.
+- PPPoE: validate discovery tag lengths, duplicate Service-Name tags,
+  and missing Service-Name handling. Fix tag-copy bounds, discovery
+  buffer allocation and movement, and MAC-filter reload use-after-free.
+- DHCPv6 / IPv6: validate option sizes, Rapid-Commit and AFTR-Name semantics,
+  relay nesting, and reply capacity. Fix configuration parsing, IPv6
+  host-bit masks, and Router Advertisement prefix buffer bounds.
+- IPoE: fix DHCPv4 option and classless-route decoding, prefix/netmask
+  validation, relay/username leaks, stale-session enumeration, driver
+  locking, and operation with IPv6 disabled.
+- SSTP: fix async PPP escape/FCS buffer bounds, drain queued PPP writes,
+  flush output on disconnect, validate packet header sizes, and send
+  standard HTTP error responses without a body.
+- PPTP: fix partial control writes, short-message handling, peer call-ID
+  byte order, socket error cleanup, and bind validation. Make
+  `echo-failure=0` explicitly disable failure-based termination.
+- L2TP: validate decrypted hidden AVP lengths and use alignment-safe
+  attribute access.
+- Logging / core: bound log lines and PostgreSQL log headers, avoid an
+  unwanted general file target, preserve the CHAP challenge name on reload,
+  and reject concurrent configuration reloads. Fix unaligned accesses in
+  memory debugging and session backup restoration.
+- Net-SNMP: fix ASN_INTEGER scalar sizes. Fix VRF netlink handle leaks and
+  VLAN monitoring packet-handler registration on Linux 6.6 and newer.
+- Build / install: install kernel modules from their actual build
+  directories, honor `DESTDIR`, and propagate installation failures.
+
+### Docs
+- Refreshed the README and synchronized the sample configuration and man
+  page, including metrics, pool reloads, SSTP transport, and IPv6 DNS.
+- Added contribution guidelines and a safeguard integration review.
+- Corrected RADIUS option examples, shaper units and directions, kernel
+  module requirements, metrics freshness guidance, and the accel-cmd
+  timeout synopsis. Updated test setup instructions and documented the
+  current DHCPv6 safeguard fixture limitation.
+
+### Tests / CI
+- Added focused suites for DHCPv6, RADIUS, VRF, LCP, memory pools, logging,
+  L2TP, IPv6 DNS, and bitmap allocation. See `tests/README.md` for the
+  current standalone safeguard runner limitation.
+- Added metrics, IPoE stale-interface cleanup and link deletion, PPPoE
+  negotiation, and kernel-module installation regression coverage.
+- Added Ubuntu 26.04 coverage and removed Debian 11 jobs. Continue testing
+  32-bit and big-endian platforms and ASan/UBSan builds. Fix test-interface
+  MAC races, big-endian VM setup flakes, and coverage counter handling.
 
 ## 1.14.0 - 2026-01-24
 
diff --git a/README.md b/README.md
index 919373bd..af678b9e 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@ Building the daemon requires:
 * OpenSSL development files
 * PCRE2 development files
 
-Kernel headers are also required when building the optional PPTP, IPoE, or VLAN
+Kernel headers are also required when building the optional PPPoSEQ, IPoE, or VLAN
 monitoring kernel modules. Optional features require their corresponding
 development libraries:
 
@@ -87,6 +87,12 @@ kernel:
       -DKDIR="/usr/src/linux-headers-$(uname -r)"
     cmake --build build
 
+For SSTP's optional PPPoSEQ transport, also set BUILD_PPPOSEQ_DRIVER=TRUE
+and install the ppposeq kernel module. SSTP tries to load it at startup;
+ppp-mode=auto uses it if available and otherwise selects async PPP.
+Changing [sstp] ppp-mode or switching from async to PPPoSEQ requires a daemon
+restart. See "man 5 accel-ppp.conf" for the transport options.
+
 
 Configuration
 =============
diff --git a/accel-cmd/accel-cmd.1 b/accel-cmd/accel-cmd.1
index 9f2f56b3..94ac9202 100644
--- a/accel-cmd/accel-cmd.1
+++ b/accel-cmd/accel-cmd.1
@@ -4,7 +4,7 @@ accel-cmd \- send commands to accel-ppp
 .SH SYNOPSIS
 .B accel-cmd
 .RB [ -n "] [" -4 "] [" -6 "] [" -f " \fIFAMILY\fR] [" -H " \fIHOST\fR]"
-.RB [ -p " \fIPORT\fR] [" -i " \fITIMEOUT\fR]"
+.RB [ -p " \fIPORT\fR] [" -t " \fITIMEOUT\fR]"
 .RI "[--] [" COMMAND "]"
 .SH DESCRIPTION
 .BR accel-cmd " is a client for accel-ppp's " cli " module. It sends"
diff --git a/accel-pppd/accel-ppp.conf b/accel-pppd/accel-ppp.conf
index fe124392..8dd0fa57 100644
--- a/accel-pppd/accel-ppp.conf
+++ b/accel-pppd/accel-ppp.conf
@@ -398,7 +398,7 @@ timeout=60
 # effect with format=prometheus. Disabled by default because usernames and
 # station IDs may be sensitive: restrict allowed_ips before enabling it.
 # Traffic counters are the ones last sampled by accounting, so their freshness
-# follows radius interim-interval / idle-timeout.
+# follows RADIUS acct-interim-interval (or Acct-Interim-Interval) / idle-timeout.
 #sessions=0
 
 [ipv6-pool]
diff --git a/accel-pppd/accel-ppp.conf.5 b/accel-pppd/accel-ppp.conf.5
index b6e8528c..3f7beeb3 100644
--- a/accel-pppd/accel-ppp.conf.5
+++ b/accel-pppd/accel-ppp.conf.5
@@ -1023,6 +1023,14 @@ HDLC framing is done in userspace.
 - use seqpacket if the module is available, otherwise async.
 .br
 Default is auto.
+.br
+The transport is selected at daemon startup. For auto or seqpacket, accel-ppp
+tries to load the ppposeq kernel module if it is not already available.
+Build and install that module with BUILD_PPPOSEQ_DRIVER=TRUE to enable it.
+The seqpacket mode requires the module; only auto falls back to async when
+it is unavailable. Changing ppp-mode, or making ppposeq available after auto
+has selected async, requires a daemon restart; configuration reload does not
+reselect the transport.
 .TP
 .BI "accept=" ssl,proxy
 Specifies incoming connection acceptance mode.
@@ -1449,16 +1457,36 @@ avoid breaking existing configuration files.
 .BI "tunnel=" range
 Specifies range of remote address of ppp interfaces if form:
 .br
-.B x.x.x.x/mask[,name=pool_name][,next=next_pool_name]
+.B x.x.x.x/mask
+.br
+.B x.x.x.x-y
 .br
-.B x.x.x.x-y[,name=pool_name][,next=next_pool_name]
+Both forms accept the modifiers [,name=pool_name], [,allocator=p2p|net30],
+and [,next=next_pool_name].
 .TP
-.BI "x.x.x.x/mask[,name=pool_name][,next=next_pool_name] or x.x.x.x-y[,name=pool_name][,next=next_pool_name]"
+.BI "x.x.x.x/mask or x.x.x.x-y"
 Also specifies range of remote address of ppp interfaces.
+The same name, allocator, and next modifiers as for tunnel= are accepted.
 .br
 You may also omit the "name=" key and use a shorthand pool name after the comma, e.g.
 .br
 .B 10.0.0.0/24,pool1
+.PP
+The allocator modifier selects how a range is divided. The default
+.B p2p
+allocator supplies one client address per allocation. The
+.B net30
+allocator divides the range into four-address blocks and supplies the
+address at offset 2 in each block; any incomplete trailing block is ignored.
+The local PPP address still comes from
+.BR gw-ip-address .
+For example:
+.br
+.B 192.0.2.0/24,name=pool1,allocator=net30
+.PP
+Each range is limited to 16777216 (2^24) allocation units: one address for
+p2p or one four-address block for net30. Larger ranges are skipped and an
+error is logged. Check existing ranges against this limit when upgrading.
 .TP
 .BI "attr=" attribute
 Specifies which Radius attribute contains pool name.
@@ -1644,7 +1672,8 @@ permits, which is every peer when that option is unset. And the traffic
 counters are the ones last sampled by accounting rather than a fresh
 read of the interface, so they are only as current as the
 .B radius
-.B interim-interval
+.B acct-interim-interval
+(or the RADIUS Acct-Interim-Interval attribute)
 or the session
 .B idle-timeout
 makes them.
diff --git a/docs/ipoe_radius.md b/docs/ipoe_radius.md
index 9bd0aecb..56c28052 100644
--- a/docs/ipoe_radius.md
+++ b/docs/ipoe_radius.md
@@ -1,98 +1,91 @@
 # Supplying DHCP Options via RADIUS for IPoE Sessions
 
-accel-ppp supports dynamically providing various DHCP options to IPoE clients by configuring corresponding RADIUS attributes. This allows for flexible and centralized management of DHCP parameters delivered to clients.
-
-## Mechanism
-
-The `ipoe` module processes RADIUS Access-Accept packets to extract DHCP options that need to be delivered to the client. This is achieved by mapping specific RADIUS Vendor-Specific Attributes (VSAs) to DHCP options. Whether you're sending a standard DHCP option (like DNS servers) or the DHCP-specific "Vendor-Specific Information" option (Option 43), the mechanism uses this common VSA structure:
-
-*   **RADIUS Vendor ID:** `54`
-    *   This ID is internally designated by accel-ppp (and commonly in FreeRADIUS dictionaries) as the "DHCP" vendor.
-*   **RADIUS Attribute ID:** This directly corresponds to the **DHCP Option Code** you wish to send (e.g., `6` for DNS Servers, `43` for Vendor-Specific Information).
-*   **RADIUS Attribute Value:** This is the raw binary payload (octets) of the DHCP option. accel-ppp will encapsulate this value into the DHCP option's data field.
-
-When accel-ppp receives an Access-Accept packet containing attributes structured in this way, it extracts the DHCP Option Code and its value, then constructs the appropriate DHCP option and includes it in the DHCP Offer or DHCP ACK packet sent back to the IPoE client.
-
-## Configuration
-
-### accel-ppp Side
-
-The functionality is inherent to the `ipoe` module; no special configuration options are required in `accel-ppp.conf` to enable this mapping. Ensure the `ipoe` module is loaded.
-
-### RADIUS Server Side
-
-To leverage this feature, your RADIUS server must be configured to send attributes using the Vendor ID `54` (DHCP) and the desired DHCP Option Code as the Attribute ID.
-
-**FreeRADIUS Example:**
-
-1. **Ensure Dictionary Definitions:**
-    Your FreeRADIUS installation should have dictionary files that define Vendor 54 as "DHCP" and the relevant DHCP Option Codes as attributes within that vendor space. The `accel-ppp` project often provides a `dictionary.dhcp` file (e.g., in `accel-pppd/radius/dict/`) with these definitions:
-
-    ```text
-    VENDOR      DHCP        54
-    ATTRIBUTE   DHCP-Vendor 43  octets
-    # ... other DHCP option definitions
-    ```
-
-2. **Configure Reply Attributes in `users` file (or equivalent policy):**
-    The format for specifying these attributes is generally `Attr-<Vendor-ID>-<Attribute-ID> = <value>`.
-
-    *   **Generic DHCP Option (e.g., Option 224, private use, with string "Hello"):**
-        ```text
-        User-Name == "test_user"
-            Attr-54-224 = "Hello"
-        ```
-
-    *   **Option 6 (DNS Servers):**
-        To send a list of DNS server IP addresses (e.g., `8.8.8.8` and `8.8.4.4`). The value is the concatenation of the 4-byte IP addresses in hexadecimal.
-        ```text
-        User-Name == "test_user"
-            Attr-54-6 = 0x0808080808080404
-        ```
-
-    *   **Option 15 (Domain Name):**
-        To send a domain name string (e.g., `example.com`).
-        ```text
-        User-Name == "test_user"
-            Attr-54-15 = "example.com"
-        ```
-
-    *   **Option 26 (Interface MTU):**
-        To send a specific MTU size (e.g., `1450`). The value is a 16-bit integer (2 bytes) in hexadecimal.
-        ```text
-        User-Name == "test_user"
-            Attr-54-26 = 0x05AA # 1450 in hex is 0x05AA
-        ```
-
-    *   **Option 43 (Vendor-Specific Information):**
-        This option typically contains sub-options encoded in a TLV (Type-Length-Value) format. The entire TLV structure for Option 43 needs to be provided as the attribute's hexadecimal value.
-
-        *Example: Sending sub-option `1` with value `"ABC"`*
-        *   Sub-option Type: `1` (0x01)
-        *   Sub-option Length: `3` (0x03)
-        *   Sub-option Value: `"ABC"` (0x414243)
-        *   Combined Hex Value: `0103414243`
-
-        ```text
-        User-Name == "test_user"
-            Attr-54-43 = 0x0103414243
-        ```
-
-    *   **Option 121 (Classless Static Route):**
-        To send static routes. The format for the value is a sequence of `(Mask Width, Significant Octets of Destination, Router IP)`.
-
-        *Example: Route `10.0.0.0/8` via `192.168.1.1`*
-        *   Mask Width: `8` (0x08)
-        *   Significant Octets of Destination: `10` (0x0a) - only 1 byte for a /8 network
-        *   Router IP: `192.168.1.1` (0xc0a80101)
-        *   Combined Hex Value: `080ac0a80101`
-
-        ```text
-        User-Name == "test_user"
-            Attr-54-121 = 0x080ac0a80101
-        ```
+The `ipoe` module can copy DHCP options from RADIUS Access-Accept attributes
+into DHCP Offer and ACK packets. Load both `ipoe` and `radius` in `[modules]`.
+No additional option mapping is needed for the DHCP vendor described below.
+
+## Attribute encoding
+
+* Vendor ID: **54**, named `DHCP` in the shipped dictionary.
+* Vendor format: **2,1** (a two-byte attribute type and a one-byte length).
+* Attribute IDs below 256 identify DHCP option codes, such as 6 for DNS
+  servers and 43 for Vendor-Specific Information.
+* The attribute value is the DHCP option payload. accel-ppp adds the DHCP
+  option code and length itself.
+
+Both the RADIUS server and accel-ppp must have matching dictionary definitions.
+The shipped definitions are in
+[`accel-pppd/radius/dict/dictionary.dhcp`](../accel-pppd/radius/dict/dictionary.dhcp),
+which the default RADIUS dictionary includes. A vendor declaration without
+`format=2,1` uses a different wire encoding and will not match this dictionary.
+
+Use named attributes from the dictionary in RADIUS policies. Numeric attribute
+names alone do not supply accel-ppp with a dictionary definition: unknown
+attributes are skipped.
+
+## Dictionary definitions
+
+Reuse existing definitions where available. This fragment shows the vendor
+format, scope, and types used by the examples; do not duplicate definitions
+already loaded by the RADIUS server:
+
+```text
+VENDOR DHCP 54 format=2,1
+BEGIN-VENDOR DHCP
+ATTRIBUTE DHCP-Domain-Name-Server 6 ipaddr array
+ATTRIBUTE DHCP-Domain-Name 15 string
+ATTRIBUTE DHCP-Interface-MTU-Size 26 short
+ATTRIBUTE DHCP-Vendor 43 octets
+ATTRIBUTE DHCP-Classless-Static-Route 121 octets
+END-VENDOR DHCP
+```
+
+For a private-use option such as 224, add a definition on **both** sides.
+For example, insert this inside the DHCP vendor block in each local dictionary:
+
+```text
+ATTRIBUTE DHCP-Private-224 224 octets
+```
+
+## FreeRADIUS 3 example
+
+Add reply attributes to the user's entry in the `files` module's users file.
+For example, for a test account:
+
+```text
+test_user Cleartext-Password := "test_password"
+	DHCP-Domain-Name-Server := 8.8.8.8,
+	DHCP-Domain-Name-Server += 8.8.4.4,
+	DHCP-Domain-Name := "example.com",
+	DHCP-Interface-MTU-Size := 1450,
+	DHCP-Vendor := 0x0103414243,
+	DHCP-Classless-Static-Route := 0x080ac0a80101,
+	DHCP-Private-224 := 0x48656c6c6f
+```
+
+The named `ipaddr`, `string`, and `short` attributes let FreeRADIUS encode
+their payloads from readable values. The `octets` attributes use hexadecimal
+payloads:
+
+| DHCP option | Payload in this example |
+| --- | --- |
+| 6, DNS servers | `8.8.8.8` and `8.8.4.4`; repeated array values are combined into one DHCP option. |
+| 15, domain name | The string `example.com`. |
+| 26, interface MTU | `1450`, encoded as the two bytes `05aa`. |
+| 43, vendor information | Sub-option 1, length 3, value `ABC`: `01 03 41 42 43`. |
+| 121, classless route | `10.0.0.0/8` via `192.168.1.1`: width `08`, destination `0a`, router `c0a80101`. |
+| 224, private use | The string `Hello`, encoded as `48 65 6c 6c 6f`; requires the custom definition above. |
+
+See the [FreeRADIUS users-file reference](https://www.freeradius.org/radiusd/man/users.html)
+for entry matching and reply-list syntax. Integrate these reply attributes with
+the authentication policy used by your deployment.
 
 ## Notes
 
-*   The RADIUS attribute value must strictly be the raw payload of the DHCP option. accel-ppp automatically handles inserting the DHCP Option Code and Length fields into the final DHCP packet.
-*   For complex DHCP options like Option 43 (Vendor-Specific Information) and Option 121 (Classless Static Route), you must manually construct the internal structure (e.g., TLVs for Option 43) as part of the RADIUS attribute value.
+* Preserve `format=2,1` when defining the DHCP vendor on the RADIUS server.
+* Construct the internal payload of complex options, such as 43 and 121,
+  before supplying the hexadecimal value. Do not include the outer DHCP
+  option code and length.
+* The DHCP vendor also defines IDs above 255 for packet header fields, such
+  as `DHCP-Your-IP-Address`. These are handled separately and are not copied
+  as DHCP options.
diff --git a/docs/ng40-safeguards-review.md b/docs/ng40-safeguards-review.md
index 592869c6..8dfbe32e 100644
--- a/docs/ng40-safeguards-review.md
+++ b/docs/ng40-safeguards-review.md
@@ -95,7 +95,8 @@ fixes and this integration are by **Denys Fedoryshchenko**.
 
 ## Validation
 
-Run from the repository root:
+The following commands and results record validation when these safeguards
+were integrated. Run the commands from the repository root at that revision:
 
 ```sh
 cmake -S . -B /tmp/accel-ppp-ng40-build -DCMAKE_BUILD_TYPE=Debug \
@@ -105,6 +106,12 @@ sh tests/unit/run_safeguards.sh /tmp/accel-ppp-ng40-build
 git diff --check
 ```
 
+For current checkouts, see the [focused unit test instructions](../tests/README.md#focused-unit-tests).
+The later IPv6 DNS storage refactor removed `conf_dns_count`, which the
+DHCPv6 fixture still references, and the runner needs to link `ipv6_dns.c`.
+The full command above therefore does not currently compile on master. The
+historical results below do not establish that the current full suite passes.
+
 Build, the existing IPv6 DNS selection test, and five standalone suites passed. Tests compile production code with
 small external-service stubs. DHCPv6, RADIUS, VRF, and pool tests use ASan,
 UBSan, and LeakSanitizer; the LCP test uses UBSan (ASan's global registration
diff --git a/docs/pppoe_radius.md b/docs/pppoe_radius.md
index cc3f3461..ba22426f 100644
--- a/docs/pppoe_radius.md
+++ b/docs/pppoe_radius.md
@@ -39,6 +39,12 @@ These attributes control the IPv6 configuration negotiated via IPv6CP and DHCPv6
     *   Adds a route to the client session for the specified IPv6 prefix.
     *   Format: `2001:db8::/32 gateway metric`
 
+*   **DNS-Server-IPv6-Address** (169, RFC 6911)
+    *   Assigns an IPv6 DNS server to this session. Repeat the attribute for multiple servers.
+    *   Assigned servers replace the `[ipv6-dns]` defaults for the session. Sessions without assigned servers use those defaults.
+    *   Enable `ipv6_nd` to advertise the servers through RDNSS, `ipv6_dhcp` to return them through DHCPv6 DNS_SERVERS, or both as needed.
+    *   The list is not limited to three servers; each reply includes as many as fit in its packet buffer and logs a warning if servers are omitted.
+
 ## Routing
 
 *   **Framed-Route** (22)
@@ -65,12 +71,13 @@ The `shaper` module can be configured to listen for specific RADIUS attributes t
 
 *   **Filter-Id** (11)
     *   Used to specify upload/download limits.
-    *   **Simple Format:** `speed` (bits/sec) or `speed/burst`. 
-        *   Example: `10000` (10 Mbps)
-    *   **Cisco Format:** `rate-limit output access-group 1 8000000 1500000 3000000` (downstream) / `rate-limit input ...` (upstream).
+    *   **Simple Format:** `speed` or `downstream/upstream`, in Kbit/s with the default `rate-multiplier=1`.
+        *   Example: `10000` sets both directions to 10 Mbps; `10000/2000` sets downstream to 10 Mbps and upstream to 2 Mbps.
+        *   The slash separates rates. Configure bursts with `[shaper] down-burst-factor` and `up-burst-factor`.
+    *   **Cisco Format:** Set `vendor=Cisco` and `attr=Cisco-AVPair` in `[shaper]`. Values such as `lcp:interface-config#1=rate-limit output 8000000 1500000 3000000 conform-action transmit exceed-action drop` control downstream; `rate-limit input ...` controls upstream. Cisco rates are in bits/sec and bursts are in bytes. See the [README shaper examples](../README.md#built-in-shaper) for time ranges and complete examples.
     
 *   **Mikrotik-Rate-Limit** (Vendor: Mikrotik, ID: 8)
-    *   Supported if the attribute is present.
+    *   Set `vendor=Mikrotik` and `attr=Mikrotik-Rate-Limit` in `[shaper]` to select this attribute. Its first rate is upstream and its second rate is downstream, the reverse of the simple Filter-Id order.
     
 Note: The attribute ID and Vendor ID for the shaper are configurable in the `[shaper]` section of `accel-ppp.conf`.
 
@@ -79,4 +86,4 @@ Note: The attribute ID and Vendor ID for the shaper are configurable in the `[sh
 PPPoE discovery tags (like Service-Name) are generally handled by the server configuration, but TR-101 (Broadband Forum) tags can be processed if `tr101` support is enabled.
 
 *   **TR-101 Attributes** (Vendor: ADSL-Forum)
-    *   accel-ppp can parse Agent-Circuit-Id and Agent-Remote-Id from PADO/PADR packets if they are present in Vendor-Specific tags, and these can be used for authentication or accounting logging.
+    *   With `[pppoe] tr101=1`, accel-ppp extracts Agent-Circuit-Id and Agent-Remote-Id from TR-101 Vendor-Specific tags in client PADR packets and includes them in RADIUS authentication and accounting requests. PADO is a server response, not the source of these client tags.
diff --git a/tests/README.md b/tests/README.md
index 01a015d8..870cf8c8 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -15,6 +15,22 @@ sh tests/unit/run_safeguards.sh build log_line
 These tests do not require installed kernel modules or root privileges. The
 sanitizer runtime needs an environment that permits its process inspection.
 
+The runner has six suites: `dhcpv6`, `radius`, `vrf`, `lcp`, `mempool`, and
+`log_line`. With no names it attempts all six. The DHCPv6 fixture currently
+refers to the removed `conf_dns_count` variable, and the runner does not link
+the `ipv6_dns.c` implementation now used by the reply builder. That fixture
+and its build command must be updated before a full run can pass.
+
+The other five suites can be run explicitly while that regression is being fixed:
+
+```bash
+sh tests/unit/run_safeguards.sh build radius vrf lcp mempool log_line
+```
+
+A successful subset run does not validate the DHCPv6 safeguards. The
+[integration validation record](../docs/ng40-safeguards-review.md#validation)
+describes results from the revision at which those safeguards were introduced.
+
 ## Kernel module installation test
 
 The kernel module installation regression test is rootless and does not need
@@ -36,36 +52,54 @@ sh tests/kernel-module-install/test.sh cmake
 
 ## Preparations
 
-Install pytest
+Install pytest and its plugins from the distribution packages:
 
-Using apt: `sudo apt install python3-pytest python3-pytest-dependency python3-pytest-order` or using pip: `sudo pip3 install pytest pytest-dependency pytest-order`.
+```bash
+sudo apt install python3-pytest python3-pytest-dependency python3-pytest-order
+```
 
 pytest-dependency version must be >= 0.5 (with 'scope' support)
 
----
-Note: tests will be run under sudo. If you prefer install python modules using pip, then do it under sudo as described above.
-
----
+The network/session tests run under sudo, so the plugins must be available to
+the system Python interpreter used by `sudo python3`.
 
 Install additional tools required for tests:
 ```bash
 sudo apt install iproute2 ppp pppoe isc-dhcp-client
 ```
 
-Then build accel-ppp in 'build' directory (as usual)
+Install the build dependencies described in the project README, including
+kernel headers and Lua development files for the options below. Run these
+commands from the repository root.
 
 Install accel-pppd (make install or use distro package). Do not run accel-pppd using systemd or other supervisors
 ```bash
-mkdir build && cd build
-cmake -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE -DCMAKE_INSTALL_PREFIX=/usr  -DKDIR=/usr/src/linux-headers-`uname -r`  -DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE -DCPACK_TYPE=Ubuntu20 ..
-make
-sudo make install # or 
-# cpack -G DEB && dpkg -i accel-ppp.deb
+cmake -S . -B build \
+  -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE \
+  -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_SYSCONFDIR=/etc \
+  -DCMAKE_INSTALL_LOCALSTATEDIR=/var \
+  -DKDIR="/usr/src/linux-headers-$(uname -r)" \
+  -DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE
+cmake --build build
+sudo cmake --install build
 ```
 
-If you prefer make install, then it is required to insert kernel modules:
+For a package-based installation on Ubuntu 24.04, configure the matching
+package dependencies before building the DEB:
+
+```bash
+cmake -S . -B build -DCPACK_TYPE=Ubuntu24
+cpack --config build/CPackConfig.cmake -G DEB -B build
+sudo dpkg -i build/accel-ppp.deb
+```
+
+Use `Ubuntu22`, `Debian12`, or `Debian13` when building for those releases.
+Do not use `Ubuntu20` for a newer distribution: it declares dependencies on
+older libraries, including `libssl1.1`.
+
+Load the kernel modules from the repository root after either installation method:
+
 ```bash
-# form root dir
 sudo insmod build/drivers/vlan_mon/driver/vlan_mon.ko
 sudo insmod build/drivers/ipoe/driver/ipoe.ko
 ```
@@ -95,18 +129,17 @@ Using apt:
 sudo apt install gcovr
 ```
 
-Using pip
-```bash
-sudo pip3 install gcovr
-```
-
 ```bash
 # from root dir
-rm -rf build && mkdir build && cd build
-cmake -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE -DCMAKE_INSTALL_PREFIX=/usr  -DKDIR=/usr/src/linux-headers-`uname -r`  -DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE -DCPACK_TYPE=Ubuntu20 -DCMAKE_C_FLAGS="--coverage -O0" ..
-make
-sudo make install # or 
-# cpack -G DEB && dpkg -i accel-ppp.deb
+cmake -S . -B build \
+  -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE \
+  -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_SYSCONFDIR=/etc \
+  -DCMAKE_INSTALL_LOCALSTATEDIR=/var \
+  -DKDIR="/usr/src/linux-headers-$(uname -r)" \
+  -DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE \
+  -DCMAKE_C_FLAGS="--coverage -O0"
+cmake --build build
+sudo cmake --install build
 ```
 
 Then insert kernel modules (ipoe.ko and vlan-mon.ko)