Skip to contentSkip to conversation

doc: nft.8: Describe iface_type data type

PATCH In review Phil Sutter 2 participants 8 messages Jan 27 – Feb 5 netfilter

lore
Share & tools
lore

Phil Sutter

author reviewer
#0 lore raw

PATCH 1/1 doc: nft.8: Describe iface_type data type

An entry in data-types.txt offers space for a name-value table. Even if one would refer to ARPHRD_*, some names are not derived from the respective macro name and thus not intuitive.

---
 doc/data-types.txt         | 27 +++++++++++++++++++++++++++
 doc/primary-expression.txt |  2 --
 2 files changed, 27 insertions(+), 2 deletions(-)
doc/data-types.txt +27 -0
index e44308b5322cb..0b350effbea68 100644
@@ -83,6 +83,33 @@ filter input iifname eth0
 filter input iifname "(eth0)"
 ----------------------------
 
+INTERFACE TYPE TYPE
+~~~~~~~~~~~~~~~~~~~
+[options="header"]
+|==================
+|Name | Keyword | Size | Base type
+|Interface type |
+iface_type|
+16 bit |
+integer
+|===================
+
+The interface type type is used with *meta iiftype/oiftype* expression. Its values correspond with respective ARPHRD_* defines in <linux/if_arp.h>.
+
+.The following keywords will automatically resolve into an interface type type with given value
+
+[options="header"]
+|==================
+|Keyword | Value
+| ether | 1
+| ppp | 512
+| ipip | 768
+| ipip6 | 769
+| loopback | 772
+| sit | 776
+| ipgre | 778
+|===================
+
 LINK LAYER ADDRESS TYPE
 ~~~~~~~~~~~~~~~~~~~~~~~
 [options="header"]
doc/primary-expression.txt +0 -2
index d5495e2c86291..bd80cd7f92fda 100644
@@ -149,8 +149,6 @@ String value in the form HH:MM or HH:MM:SS. Values are expected to be less than
 Interface index (32 bit number). Can be specified numerically or as name of an existing interface.
 |ifname|
 Interface name (16 byte string). Does not have to exist.
-|iface_type|
-Interface type (16 bit number).
 |uid|
 User ID (32 bit number). Can be specified numerically or as user name.
 |gid|
Signature · 1 line
2.51.0
maintainer
#1 lore raw
Quoted 15 lines · Phil Sutter

An entry in data-types.txt offers space for a name-value table. Even if one would refer to ARPHRD_*, some names are not derived from the respective macro name and thus not intuitive.

---
 doc/data-types.txt         | 27 +++++++++++++++++++++++++++
 doc/primary-expression.txt |  2 --
 2 files changed, 27 insertions(+), 2 deletions(-)
doc/data-types.txt +0 -0
index e44308b5322cb..0b350effbea68 100644

doc/data-types.txt filter input iifname eth0 · line 87

Quoted 5 lines
doc/data-types.txt +2 -0
@@ -83,6 +83,33 @@ filter input iifname eth0
 filter input iifname "(eth0)"
 ----------------------------
 
+INTERFACE TYPE TYPE
+~~~~~~~~~~~~~~~~~~~

TYPE TYPE?

author reviewer
#2 lore raw
Quoted 19 lines · Florian Westphal
Quoted 18 lines · Phil Sutter

An entry in data-types.txt offers space for a name-value table. Even if one would refer to ARPHRD_*, some names are not derived from the respective macro name and thus not intuitive.

---
 doc/data-types.txt         | 27 +++++++++++++++++++++++++++
 doc/primary-expression.txt |  2 --
 2 files changed, 27 insertions(+), 2 deletions(-)
doc/data-types.txt +0 -0
index e44308b5322cb..0b350effbea68 100644
@@ -83,6 +83,33 @@ filter input iifname eth0
 filter input iifname "(eth0)"
 ----------------------------
 
Quoted 4 lines

doc/data-types.txt filter input iifname eth0 · line 87

Quoted 2 lines
doc/data-types.txt +2 -0
+INTERFACE TYPE TYPE
+~~~~~~~~~~~~~~~~~~~

TYPE TYPE?

Yes, sadly. ;)

We also have "ICMP TYPE TYPE" and "ICMPV6 TYPE TYPE" - the types themselves are called "icmp_type", "icmpv6_type" and "iface_type". So section titles formed like "<type> type" end up this way. It seems wrong, but "INTERFACE TYPE" is misleading as the type is not called "interface" but "interface type".

Maybe we should include the underscores in the title?

Cheers, Phil

maintainer
#3 lore raw
Quoted 8 lines · Phil Sutter
Quoted 5 lines · Florian Westphal
Quoted 2 lines · Phil Sutter

+INTERFACE TYPE TYPE
+~~~~~~~~~~~~~~~~~~~

TYPE TYPE?

Yes, sadly. ;)

Ugh.

Quoted 5 lines

We also have "ICMP TYPE TYPE" and "ICMPV6 TYPE TYPE" - the types themselves are called "icmp_type", "icmpv6_type" and "iface_type". So section titles formed like "<type> type" end up this way. It seems wrong, but "INTERFACE TYPE" is misleading as the type is not called "interface" but "interface type".

Whats wrong with INTERFACE TYPE?

Its called interface type.
I'd remove the extra TYPE everywhere, its not many occurences:

data-types.txt:ICMP TYPE TYPE
data-types.txt:The ICMP Type type is used to conveniently specify the ICMP header's type field. data-types.txt:ICMPV6 TYPE TYPE
data-types.txt:The ICMPv6 Type type is used to conveniently specify the ICMPv6 header's type field.

author reviewer
#4 lore raw
Quoted 12 lines · Florian Westphal
Quoted 8 lines · Phil Sutter
Quoted 5 lines · Florian Westphal
Quoted 2 lines · Phil Sutter

+INTERFACE TYPE TYPE
+~~~~~~~~~~~~~~~~~~~

TYPE TYPE?

Yes, sadly. ;)

Ugh.

Quoted 7 lines
Quoted 5 lines

We also have "ICMP TYPE TYPE" and "ICMPV6 TYPE TYPE" - the types themselves are called "icmp_type", "icmpv6_type" and "iface_type". So section titles formed like "<type> type" end up this way. It seems wrong, but "INTERFACE TYPE" is misleading as the type is not called "interface" but "interface type".

Whats wrong with INTERFACE TYPE?

As said, these headers are all structured as "<typename> TYPE":

- INTEGER TYPE
- BITMASK TYPE
- STRING TYPE
- INTERFACE TYPE TYPE
- LINK LAYER ADDRESS TYPE
- IPV4 ADDRESS TYPE
...
- ICMP TYPE TYPE
- ICMP CODE TYPE
- ICMPV6 TYPE TYPE
...

IMO we could drop the " TYPE" suffix from them all, but only merging the "TYPE TYPE" cases is inconsistent.

Quoted 7 lines

Its called interface type.
I'd remove the extra TYPE everywhere, its not many occurences:

data-types.txt:ICMP TYPE TYPE
data-types.txt:The ICMP Type type is used to conveniently specify the ICMP header's type field. data-types.txt:ICMPV6 TYPE TYPE
data-types.txt:The ICMPv6 Type type is used to conveniently specify the ICMPv6 header's type field.

Here we at least get a hint from the casing: The type's name is "ICMPv6 Type", so "the type named "ICMPv6 Type" becomes "the ICMPv6 Type type".

I get your point, it looks wrong and sounds odd when reading out loud but it is formally correct.

Cheers, Phil

maintainer
#5 lore raw
Quoted 6 lines · Phil Sutter

As said, these headers are all structured as "<typename> TYPE":

- INTEGER TYPE
- BITMASK TYPE
- STRING TYPE
- INTERFACE TYPE TYPE

- INTERFACE TYPE

Quoted 4 lines

- LINK LAYER ADDRESS TYPE
- IPV4 ADDRESS TYPE
...
- ICMP TYPE TYPE

ICMP TYPE

Quoted 7 lines

- ICMP CODE TYPE
- ICMPV6 TYPE TYPE

- ICMPV6 TYPE

IMO we could drop the " TYPE" suffix from them all, but only merging the "TYPE TYPE" cases is inconsistent.

Why?!

INTEGER TYPE
INTERFACE TYPE TYPE

Thats absolutely sounds inconsistent.

Sure:
payload expression, datatype integer (integer), 4 bits
meta expression, datatype iface_type (network interface type) (basetype integer), 16 bits

So what?
I don't see any implication that you can take 'FOO TYPE' to mean that the type is called 'foo' internally.

Quoted 2 lines

I get your point, it looks wrong and sounds odd when reading out loud but it is formally correct.

Ok, I give up.

author reviewer
#6 lore raw
Quoted 25 lines · Florian Westphal
Quoted 6 lines · Phil Sutter

As said, these headers are all structured as "<typename> TYPE":

- INTEGER TYPE
- BITMASK TYPE
- STRING TYPE
- INTERFACE TYPE TYPE

- INTERFACE TYPE

Quoted 4 lines

- LINK LAYER ADDRESS TYPE
- IPV4 ADDRESS TYPE
...
- ICMP TYPE TYPE

ICMP TYPE

Quoted 7 lines

- ICMP CODE TYPE
- ICMPV6 TYPE TYPE

- ICMPV6 TYPE

IMO we could drop the " TYPE" suffix from them all, but only merging the "TYPE TYPE" cases is inconsistent.

Quoted 6 lines

Why?!

INTEGER TYPE
INTERFACE TYPE TYPE

Thats absolutely sounds inconsistent.

Why is it? First type is named "integer", the second one "interface type".

Quoted 7 lines

Sure:
payload expression, datatype integer (integer), 4 bits
meta expression, datatype iface_type (network interface type) (basetype integer), 16 bits

So what?
I don't see any implication that you can take 'FOO TYPE' to mean that the type is called 'foo' internally.

We start splitting hair, but IMO a user reading "ICMP CODE TYPE" and "ICMP TYPE" will likely assume the first type is called "ICMP CODE" and the second just "ICMP".

Quoted 4 lines
Quoted 2 lines

I get your point, it looks wrong and sounds odd when reading out loud but it is formally correct.

Ok, I give up.

I'm just stating my point. If you think we should just 's/type type/type/g' and it's not a problem, just go for it and I'll adjust my patch to it.

Cheers, Phil