Update docs and header comments for the IP_PKTINFO attribution model

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:
2026-04-18 15:16:10 +02:00
parent 31c2ac2d65
commit 055cf9f830
4 changed files with 65 additions and 41 deletions

9
debian/control vendored
View File

@@ -27,11 +27,12 @@ Description: nginx dynamic module for per-VIP, per-device traffic counters
request to the interface it arrived on. Counters are exposed as
Prometheus text and JSON from a single scrape endpoint.
.
Attribution is done by the Linux kernel's TCP socket lookup, using
SO_BINDTODEVICE on per-interface listening sockets. The module adds
Attribution is done by reading the ingress ifindex per connection
from the kernel's IP_PKTINFO / IPV6_PKTINFO cmsg; listening sockets
stay plain wildcards so outgoing packets follow the normal routing
table (which matters for DSR / maglev setups). The module adds
device= and ipng_source_tag= parameters to the nginx listen
directive; the kernel routes each incoming connection to the
correct listener by ingress interface.
directive, mapping interface names to source tags.
.
Typical use cases include GRE tunnel fleets, VLAN trunks, or any
deployment where traffic arrives on distinct interfaces and