ipng/nginx-ipng-stats-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs and header comments for the IP_PKTINFO attribution model

Browse Source 
The SO_BINDTODEVICE → IP_PKTINFO switch in the previous commit
was a semantic change: the module no longer touches outgoing
routing at all, and several places in the docs and the module's
top-of-file comment still described the old mechanism.

- README.md and debian/control now describe attribution as
  reading the ingress ifindex per connection from the kernel's
  IP_PKTINFO / IPV6_PKTINFO cmsg, and explicitly call out that
  the DSR / maglev return-path constraint is what makes the
  change necessary.
- docs/design.md FR-1.1 / FR-1.5 / FR-1.6 are rewritten to
  forbid SO_BINDTODEVICE and to describe the cmsg-based lookup.
  NFR-6.1 notes these are ordinary unprivileged socket options.
  The "Components" / "Composes With" sections and the
  "Alternatives Considered" entry are brought in line — and a
  new entry records SO_BINDTODEVICE as a rejected alternative
  with the exact failure mode seen on an IPng production box.
- docs/config-guide.md already carried the new description;
  unchanged here.
- src/ngx_http_ipng_stats_module.c's top-level block comment is
  rewritten to match; the section header above init_module goes
  from "rebind listen sockets with SO_BINDTODEVICE" to "enable
  IP_PKTINFO on listen sockets, resolve ifindexes".

Three SO_BINDTODEVICE mentions deliberately remain in the source
and one in the design doc's alternatives table — all of them
explain that the module *avoids* the option, which is itself
load-bearing documentation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Pim van Pelt
2026-04-18 15:16:10 +02:00
parent 31c2ac2d65
commit 055cf9f830
4 changed files with 65 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
src/ngx_http_ipng_stats_module.c
View File

@@ -8,11 +8,16 @@
* See docs/design.md in the repository for the full design. The short
* version is:
*
* - Attribution is done by the Linux kernel's TCP socket lookup, via
* SO_BINDTODEVICE on per-tunnel listening sockets. Each `listen`
* directive may carry `device=<ifname>` and `ipng_source_tag=<tag>`
* parameter; this module parses them by replacing the stock
* ngx_http_core_module `listen` command handler at preconfig time.
* - Attribution is done by reading the ingress ifindex per TCP
* connection from the kernel's IP_PKTINFO / IPV6_PKTINFO cmsg
* (enabled on every HTTP listening socket at init_module time).
* Listening sockets stay plain wildcards so egress follows the
* normal routing table — no SO_BINDTODEVICE, so DSR / maglev
* setups keep working. Each `listen` directive may carry
* `device=<ifname>` and `ipng_source_tag=<tag>` parameters; this
* module parses them by replacing the stock ngx_http_core_module
* `listen` command handler at preconfig time, and maintains the
* ifindex → source tag lookup table used by the log handler.
*
* - Counters are maintained per-worker in a private table (no locks,
* no atomics on the request path) and flushed into a shared-memory
@@ -1206,7 +1211,7 @@ ngx_http_ipng_stats_init_zone(ngx_shm_zone_t *shm_zone, void *data)
/* ----------------------------------------------------------------- */
/* init_module: rebind listen sockets with SO_BINDTODEVICE */
/* init_module: enable IP_PKTINFO on listen sockets, resolve ifindexes */
/* ----------------------------------------------------------------- */
/* init_module: enable IP_PKTINFO / IPV6_RECVPKTINFO on every HTTP