Re: Documentation question

[Duncan Roe <duncan_roe@optusnet.com.au>]

On Mon, Jul 05, 2021 at 10:56:10AM +0200, Pablo Neira Ayuso wrote:
> On Mon, Jul 05, 2021 at 09:45:56AM +1000, Duncan Roe wrote:
> > Hi Pablo,
> >
> > Did you follow the email thread
> > https://www.spinics.net/lists/netfilter/msg60278.html?
> >
> > In summary, OP asked:
> > > Good morning! I am using the nf-queue.c example from
> > > libnetfilter_queue repo. In the queue_cb() function, I am trying to
> > > get the conntrack info but this condition is always false.
> > >
> > > if(attr[NFQA_CT])
> > >
> > > I can see the flow in conntrack -L output. Anyone know what I am
> > > missing? Appreciate your help!
> >
> > and Florian replied:
> > > IIRC you need to set NFQA_CFG_F_CONNTRACK in NFQA_CFG_FLAGS when setting
> > > up the queue.  The example only sets F_GSO, so no conntrack info is
> > > added.
> >
> > My question is, where should all this have been documented?
> >
> > `man nfq_set_queue_flags` documents NFQA_CFG_F_CONNTRACK, but
> > nfq_set_queue_flags() is deprecated and OP was not using it.
> >
> > The modern approach is to code
> > > mnl_attr_put_u32(nlh, NFQA_CFG_MASK, htonl(NFQA_CFG_F_GSO));
> >
> > NFQA_CFG_MASK is supplied by a libnetfilter_queue header, while
> > mnl_attr_put_u32() is a libmnl function. What to do?
>
> NFQA_CFG_MASK is supplied by linux/netfilter/nfnetlink_queue.h
>
> The UAPI header is the main reference, it provides the kernel
> definitions for the netlink attributes.
>
> libnetfilter_queue provides a "cache copy" of this header too, that
> is: libnetfilter_queue/linux_nfnetlink_queue.h

Are you saying that the UAPI headers are adequate as documentation of how to use
the system?

If not, where should extra documentation go?

In any case, do we tell the users to use header files in linux/ or
libnetfilter_queue/ (i.e. in the yet-to-be-written SYNOPSIS in man pages)?

Cheers ... Duncan.