nftables documentation improvement?

nftables documentation improvement?

[Harald Welte]

Dear netfilter project,

In my recent interaction explaining nftables to some other users I am
under the impression that there is likely some improvement possible to
the nftables wiki.

The wiki is full of details about the individual expressions, actions,
etc. - but I think what's lacking (or I couldn't find it) is some kind
of conscise overall description of the terminology + the general
high-level architecture of the ruleset.

You can find some description in the first two paragraphs of 
https://wiki.nftables.org/wiki-nftables/index.php/Simple_rule_management
but that doesn't define the terms used (action, expression, statement,
...)

You can find an overview of the terms used in
https://wiki.nftables.org/wiki-nftables/index.php/Quick_reference-nftables_in_10_minutes
[but then actually with imprecise language like "rule refers to an
action to be configured within a chain." while a rule actually consists
of matching expressions and an action"]

I'd be willing to try to write a proposed improvded text expressing what
I have in mind.  I'd prefer to do that as some separate wiki page as a
draft for you guys to review before deciding whether to use it in the
main wiki pages.  I just didn't want to write it as unformatted
plain-text here in e-mail and then later have to re-format in wiki
syntax.

So in short: If anybody would be willing to add an account for me, I'd
give it a shot and you can decide if you think what I'd consider an
improvement is also one in your point of view.

Thanks,
	Harald

p.s.: I'm not subscribed to the list since becoming emeritus status a long
time ago, so please Cc me in any responses.

-- 
- Harald Welte <laforge@gnumonks.org>          https://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
                                                  (ETSI EN 300 175-7 Ch. A6)

Re: nftables documentation improvement?

[Pablo Neira Ayuso]

Hi Harald,

On Sat, Mar 23, 2024 at 09:54:50AM +0100, Harald Welte wrote:
> Dear netfilter project,
> 
> In my recent interaction explaining nftables to some other users I am
> under the impression that there is likely some improvement possible to
> the nftables wiki.
> 
> The wiki is full of details about the individual expressions, actions,
> etc. - but I think what's lacking (or I couldn't find it) is some kind
> of conscise overall description of the terminology + the general
> high-level architecture of the ruleset.
> 
> You can find some description in the first two paragraphs of 
> https://wiki.nftables.org/wiki-nftables/index.php/Simple_rule_management
> but that doesn't define the terms used (action, expression, statement,
> ...)
> 
> You can find an overview of the terms used in
> https://wiki.nftables.org/wiki-nftables/index.php/Quick_reference-nftables_in_10_minutes
> [but then actually with imprecise language like "rule refers to an
> action to be configured within a chain." while a rule actually consists
> of matching expressions and an action"]
> 
> I'd be willing to try to write a proposed improvded text expressing what
> I have in mind.  I'd prefer to do that as some separate wiki page as a
> draft for you guys to review before deciding whether to use it in the
> main wiki pages.  I just didn't want to write it as unformatted
> plain-text here in e-mail and then later have to re-format in wiki
> syntax.

That's fine, I should have written that already myself, your help is
welcome on this.

> So in short: If anybody would be willing to add an account for me, I'd
> give it a shot and you can decide if you think what I'd consider an
> improvement is also one in your point of view.

Just sent you credentials in a private email.

Thanks.

Re: nftables documentation improvement?

[Harald Welte]

Hi Pablo,

On Sat, Mar 23, 2024 at 10:03:46PM +0100, Pablo Neira Ayuso wrote:
> That's fine, I should have written that already myself, your help is
> welcome on this.

I'm not saying anyone should have done XYZ.  Sometimes its useful to have a
[semi-] outside perspective of somebody who was not involved with the development.

> Just sent you credentials in a private email.

Thanks, I'll work on the proposed text shortly.

-- 
- Harald Welte <laforge@gnumonks.org>          https://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
                                                  (ETSI EN 300 175-7 Ch. A6)