RFC: nft.8 review

RFC: nft.8 review

[Phil Sutter]

Hi,

I skimmed through nft man page and noted down problems I discovered.
While doing so, I got the idea to restructure the whole document for
better organization and comprehensibility but wanted to hear your
thoughts first before creating a ticket in netfilter BZ:


* Use BNF in synopses

This is rudimentally used in the SYNOPSIS section already, but just
lists _cmd_ without explanation - although the fun is only about to
start at this point. :)

What I really don't like is the syntax used in e.g. CHAINS section: it
is not only imprecise (nothing says you have to use 'priority <prio>'
but may not use 'table <table>', but also plain wrong when it comes to
the mandatory braces around the chain_block.


* Organize entity descriptions BNF-style

In my opinion the order of (sub-)sections is a bit chaotic at times.
E.g. RULES section synopsis tries to explain how a rule is made up from
statements, but these are not explained before five sections later (not
counting the bogus BLA section ;).

The idea here is to go from most generic to most specific, like things
are defined in yacc - just not as explicit, since if I want to know the
relation between concat_rhs_expr and shift_rhs_expr, I can just as well
read the code itself.


* What about sub-pages?

Looking at some expressions' descriptions, it seems like these might
grow exponentially with the documentation improving. So maybe it makes
sense to follow iptables' advice and have 'nft-extensions.8'? I would
have called it 'nft-statements.8' or 'nft-expressions.8' but the two are
too much intertwined to keep them separate.

OK, maybe this can wait until nft.8 really has become awfully long.


Comments, flame, donations highly appreciated, of course!

Cheers, Phil

Re: RFC: nft.8 review

[Pablo Neira Ayuso]

Hi Phil,

On Sat, Dec 10, 2016 at 11:27:16AM +0100, Phil Sutter wrote:
> Hi,
> 
> I skimmed through nft man page and noted down problems I discovered.
> While doing so, I got the idea to restructure the whole document for
> better organization and comprehensibility but wanted to hear your
> thoughts first before creating a ticket in netfilter BZ:
> 
> 
> * Use BNF in synopses
> 
> This is rudimentally used in the SYNOPSIS section already, but just
> lists _cmd_ without explanation - although the fun is only about to
> start at this point. :)
> 
> What I really don't like is the syntax used in e.g. CHAINS section: it
> is not only imprecise (nothing says you have to use 'priority <prio>'
> but may not use 'table <table>', but also plain wrong when it comes to
> the mandatory braces around the chain_block.

Right, that needs a fix.

> * Organize entity descriptions BNF-style
> 
> In my opinion the order of (sub-)sections is a bit chaotic at times.
> E.g. RULES section synopsis tries to explain how a rule is made up from
> statements, but these are not explained before five sections later (not
> counting the bogus BLA section ;).
> 
> The idea here is to go from most generic to most specific, like things
> are defined in yacc - just not as explicit, since if I want to know the
> relation between concat_rhs_expr and shift_rhs_expr, I can just as well
> read the code itself.
>
> * What about sub-pages?
> 
> Looking at some expressions' descriptions, it seems like these might
> grow exponentially with the documentation improving. So maybe it makes
> sense to follow iptables' advice and have 'nft-extensions.8'? I would
> have called it 'nft-statements.8' or 'nft-expressions.8' but the two are
> too much intertwined to keep them separate.
> 
> OK, maybe this can wait until nft.8 really has become awfully long.

Yes, let's wait a bit for the split.

> Comments, flame, donations highly appreciated, of course!

Patches are very welcome!

Re: RFC: nft.8 review

[mark diener]

Will the V8 NFT have byte level protocol compatibility with current
linux kernel versions?

I am deployed on kernel  4.4.0-53-generic and would like to know when
structural defines like RTM_NEWADDR,NLM_F_REQUEST, etc become updated
or obsoleted.

As you can likely tell, I am not using libmnl or libnft but using
direct NETFILTER kernel calls.

What a challenge to scan the code and reverse-engineer the byte
sequences and understand the way the NFT virtual machine works in the
kernel.
















On Mon, Dec 19, 2016 at 5:53 PM, Pablo Neira Ayuso <pablo@netfilter.org> wrote:
> Hi Phil,
>
> On Sat, Dec 10, 2016 at 11:27:16AM +0100, Phil Sutter wrote:
>> Hi,
>>
>> I skimmed through nft man page and noted down problems I discovered.
>> While doing so, I got the idea to restructure the whole document for
>> better organization and comprehensibility but wanted to hear your
>> thoughts first before creating a ticket in netfilter BZ:
>>
>>
>> * Use BNF in synopses
>>
>> This is rudimentally used in the SYNOPSIS section already, but just
>> lists _cmd_ without explanation - although the fun is only about to
>> start at this point. :)
>>
>> What I really don't like is the syntax used in e.g. CHAINS section: it
>> is not only imprecise (nothing says you have to use 'priority <prio>'
>> but may not use 'table <table>', but also plain wrong when it comes to
>> the mandatory braces around the chain_block.
>
> Right, that needs a fix.
>
>> * Organize entity descriptions BNF-style
>>
>> In my opinion the order of (sub-)sections is a bit chaotic at times.
>> E.g. RULES section synopsis tries to explain how a rule is made up from
>> statements, but these are not explained before five sections later (not
>> counting the bogus BLA section ;).
>>
>> The idea here is to go from most generic to most specific, like things
>> are defined in yacc - just not as explicit, since if I want to know the
>> relation between concat_rhs_expr and shift_rhs_expr, I can just as well
>> read the code itself.
>>
>> * What about sub-pages?
>>
>> Looking at some expressions' descriptions, it seems like these might
>> grow exponentially with the documentation improving. So maybe it makes
>> sense to follow iptables' advice and have 'nft-extensions.8'? I would
>> have called it 'nft-statements.8' or 'nft-expressions.8' but the two are
>> too much intertwined to keep them separate.
>>
>> OK, maybe this can wait until nft.8 really has become awfully long.
>
> Yes, let's wait a bit for the split.
>
>> Comments, flame, donations highly appreciated, of course!
>
> Patches are very welcome!
> --
> To unsubscribe from this list: send the line "unsubscribe netfilter-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: RFC: nft.8 review

[Phil Sutter]

Hi Mark,

On Tue, Dec 20, 2016 at 10:27:45AM -0600, mark diener wrote:
> Will the V8 NFT have byte level protocol compatibility with current
> linux kernel versions?

We were talking about nft manpage (which happens to live in section 8,
hence why I referred to it as 'nft.8'), not some version 8 (which would
still take a while to come as we're only at version 0.6 ATM).

> I am deployed on kernel  4.4.0-53-generic and would like to know when
> structural defines like RTM_NEWADDR,NLM_F_REQUEST, etc become updated
> or obsoleted.

Not sure I understand you correctly, but why should userspace exported
constants like RTM_NEWADDR or NLM_F_REQUEST become obsolete? This would
break backwards compatibility, which is generally frowned upon.

> As you can likely tell, I am not using libmnl or libnft but using
> direct NETFILTER kernel calls.
> 
> What a challenge to scan the code and reverse-engineer the byte
> sequences and understand the way the NFT virtual machine works in the
> kernel.

Sounds like you're baking your own cake here. I'd say if you decide to
reinvent the wheel, well, then you have to invent a wheel. No? ;)

Cheers, Phil

Re: RFC: nft.8 review

[mark diener]

Phil:

Yes, I certainly hope that the netfilter interface is byte level
backwards compatible from the netfilter calls upwards, but there is a
chance that compatibility
is only from userspace libmnl and upwards.

If that is the case, what kernel version release can I expect the
current netfilter message packing structures to be changed
where the current version 4.x kernel based libmnl would no longer work?

It would be lovely if the kernel netfilter team documented the byte
level interface that libmnl is written, but I don't have sponsorship
dollars.

Merry Christmas,

Marco







On Tue, Dec 20, 2016 at 11:21 AM, Phil Sutter <phil@nwl.cc> wrote:
> Hi Mark,
>
> On Tue, Dec 20, 2016 at 10:27:45AM -0600, mark diener wrote:
>> Will the V8 NFT have byte level protocol compatibility with current
>> linux kernel versions?
>
> We were talking about nft manpage (which happens to live in section 8,
> hence why I referred to it as 'nft.8'), not some version 8 (which would
> still take a while to come as we're only at version 0.6 ATM).
>
>> I am deployed on kernel  4.4.0-53-generic and would like to know when
>> structural defines like RTM_NEWADDR,NLM_F_REQUEST, etc become updated
>> or obsoleted.
>
> Not sure I understand you correctly, but why should userspace exported
> constants like RTM_NEWADDR or NLM_F_REQUEST become obsolete? This would
> break backwards compatibility, which is generally frowned upon.
>
>> As you can likely tell, I am not using libmnl or libnft but using
>> direct NETFILTER kernel calls.
>>
>> What a challenge to scan the code and reverse-engineer the byte
>> sequences and understand the way the NFT virtual machine works in the
>> kernel.
>
> Sounds like you're baking your own cake here. I'd say if you decide to
> reinvent the wheel, well, then you have to invent a wheel. No? ;)
>
> Cheers, Phil