[PATCH nft] doc: add MPTCP subtypes documentation to man page

[PATCH nft] doc: add MPTCP subtypes documentation to man page

[Fernando Fernandez Mancera]

In addition, document the limitation when there are multiple MPTCP
options.

Signed-off-by: Fernando Fernandez Mancera <fmancera@suse.de>
---
 doc/payload-expression.txt | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt
index ceccfdaa..f1de0956 100644
--- a/doc/payload-expression.txt
+++ b/doc/payload-expression.txt
@@ -805,6 +805,32 @@ TCP option matching also supports raw expression syntax to access arbitrary opti
 [verse]
 *tcp option* *@*'number'*,*'offset'*,*'length'
 
+.MPTCP subtypes
+[options="header"]
+|============================
+|Keyword| Description
+|mp-capable|
+Multipath capable
+|mp-join|
+Join connection
+|dss|
+Data sequence signal
+|add-addr|
+Add address
+|remove-addr|
+Remove address
+|mp-prio|
+Change subflow priority
+|mp-fail|
+Fallback to single-path TCP
+|mp-fastclose|
+Fast close
+|mp-tcprst|
+Subflow reset
+|============================
+
+Data types can be queried with 'nft describe tcp option mptcp subtype'.
+
 .IP Options
 [options="header"]
 |==================
@@ -833,6 +859,18 @@ filter input tcp option sack-perm exists counter
 filter input tcp option maxseg size lt 536
 --------------------
 
+.matching MPTCP suboptions
+--------------------
+filter input tcp option mptcp subtype mp-join drop
+--------------------
+
+[NOTE]
+====================
+Netfilter currently evaluates only the first MPTCP option found in the TCP
+header. If a packet contains multiple MPTCP options, a rule attempting to match
+the second option will never match.
+====================
+
 .matching IPv6 exthdr
 ---------------------
 ip6 filter input frag more-fragments 1 counter
-- 
2.55.0

Re: [PATCH nft] doc: add MPTCP subtypes documentation to man page

[Matthieu Baerts]

Hi Fernando,

On 29/09/2026 16:14, Fernando Fernandez Mancera wrote:
> In addition, document the limitation when there are multiple MPTCP
> options.

Thank you for this patch!

> diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt
> index ceccfdaa..f1de0956 100644
> --- a/doc/payload-expression.txt
> +++ b/doc/payload-expression.txt

(...)

> @@ -833,6 +859,18 @@ filter input tcp option sack-perm exists counter
>  filter input tcp option maxseg size lt 536
>  --------------------
>  
> +.matching MPTCP suboptions
> +--------------------
> +filter input tcp option mptcp subtype mp-join drop
> +--------------------
> +
> +[NOTE]
> +====================
> +Netfilter currently evaluates only the first MPTCP option found in the TCP
> +header. If a packet contains multiple MPTCP options, a rule attempting to match
> +the second option will never match.

Would it be interesting to give an example? e.g. a rule attempting to
match 'remove-addr', 'mp-prio' and 'mp-fail' (and 'mp-tcprst' in some
cases) are not going to catch anything when the traffic is emitted by
the current Linux kernel stack.

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.

Re: [PATCH nft] doc: add MPTCP subtypes documentation to man page

[Fernando Fernandez Mancera]

On 9/30/26 8:38 PM, Matthieu Baerts wrote:
> Hi Fernando,
> 
> On 29/09/2026 16:14, Fernando Fernandez Mancera wrote:
>> In addition, document the limitation when there are multiple MPTCP
>> options.
> 
> Thank you for this patch!
> 
>> diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt
>> index ceccfdaa..f1de0956 100644
>> --- a/doc/payload-expression.txt
>> +++ b/doc/payload-expression.txt
> 
> (...)
> 
>> @@ -833,6 +859,18 @@ filter input tcp option sack-perm exists counter
>>   filter input tcp option maxseg size lt 536
>>   --------------------
>>   
>> +.matching MPTCP suboptions
>> +--------------------
>> +filter input tcp option mptcp subtype mp-join drop
>> +--------------------
>> +
>> +[NOTE]
>> +====================
>> +Netfilter currently evaluates only the first MPTCP option found in the TCP
>> +header. If a packet contains multiple MPTCP options, a rule attempting to match
>> +the second option will never match.
> 
> Would it be interesting to give an example? e.g. a rule attempting to
> match 'remove-addr', 'mp-prio' and 'mp-fail' (and 'mp-tcprst' in some
> cases) are not going to catch anything when the traffic is emitted by
> the current Linux kernel stack.
> 

Hi Matthieu,

could you provide a good one? Ideally the documentation should be as 
simple as possible. I thought about adding the rule you asked about 
initially.. but I realized that simply describing the issue was better IMHO.

Thanks,
Fernando.

> Cheers,
> Matt

Re: [PATCH nft] doc: add MPTCP subtypes documentation to man page

[Matthieu Baerts]

Hi Fernando,

On 01/10/2026 10:58, Fernando Fernandez Mancera wrote:
> On 9/30/26 8:38 PM, Matthieu Baerts wrote:
>> On 29/09/2026 16:14, Fernando Fernandez Mancera wrote:
>>> diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt
>>> index ceccfdaa..f1de0956 100644
>>> --- a/doc/payload-expression.txt
>>> +++ b/doc/payload-expression.txt
>>
>> (...)
>>
>>> @@ -833,6 +859,18 @@ filter input tcp option sack-perm exists counter
>>>   filter input tcp option maxseg size lt 536
>>>   --------------------
>>>   +.matching MPTCP suboptions
>>> +--------------------
>>> +filter input tcp option mptcp subtype mp-join drop
>>> +--------------------
>>> +
>>> +[NOTE]
>>> +====================
>>> +Netfilter currently evaluates only the first MPTCP option found in
>>> the TCP
>>> +header. If a packet contains multiple MPTCP options, a rule
>>> attempting to match
>>> +the second option will never match.
>>
>> Would it be interesting to give an example? e.g. a rule attempting to
>> match 'remove-addr', 'mp-prio' and 'mp-fail' (and 'mp-tcprst' in some
>> cases) are not going to catch anything when the traffic is emitted by
>> the current Linux kernel stack.
> 
> could you provide a good one? Ideally the documentation should be as
> simple as possible. I thought about adding the rule you asked about
> initially.. but I realized that simply describing the issue was better
> IMHO.
What about something like this?

  Netfilter currently evaluates only the first MPTCP option found in the
  TCP header. If a packet contains multiple MPTCP options, a rule
  attempting to match the second option will never match. Having
  multiple MPTCP options in the same packet is valid, e.g. the Linux
  MPTCP stack inserts 'remove-addr', 'mp-prio' and 'mp-fail' after an
  MPTCP 'dss' option ; 'mp-tcprst' can also be inserted after an 'mp-
  fastclose'.

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.

Re: [PATCH nft] doc: add MPTCP subtypes documentation to man page

[Fernando Fernandez Mancera]

On 10/6/26 7:06 PM, Matthieu Baerts wrote:
> Hi Fernando,
> 
> On 01/10/2026 10:58, Fernando Fernandez Mancera wrote:
>> On 9/30/26 8:38 PM, Matthieu Baerts wrote:
>>> On 29/09/2026 16:14, Fernando Fernandez Mancera wrote:
>>>> diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt
>>>> index ceccfdaa..f1de0956 100644
>>>> --- a/doc/payload-expression.txt
>>>> +++ b/doc/payload-expression.txt
>>>
>>> (...)
>>>
>>>> @@ -833,6 +859,18 @@ filter input tcp option sack-perm exists counter
>>>>    filter input tcp option maxseg size lt 536
>>>>    --------------------
>>>>    +.matching MPTCP suboptions
>>>> +--------------------
>>>> +filter input tcp option mptcp subtype mp-join drop
>>>> +--------------------
>>>> +
>>>> +[NOTE]
>>>> +====================
>>>> +Netfilter currently evaluates only the first MPTCP option found in
>>>> the TCP
>>>> +header. If a packet contains multiple MPTCP options, a rule
>>>> attempting to match
>>>> +the second option will never match.
>>>
>>> Would it be interesting to give an example? e.g. a rule attempting to
>>> match 'remove-addr', 'mp-prio' and 'mp-fail' (and 'mp-tcprst' in some
>>> cases) are not going to catch anything when the traffic is emitted by
>>> the current Linux kernel stack.
>>
>> could you provide a good one? Ideally the documentation should be as
>> simple as possible. I thought about adding the rule you asked about
>> initially.. but I realized that simply describing the issue was better
>> IMHO.
> What about something like this?
> 
>    Netfilter currently evaluates only the first MPTCP option found in the
>    TCP header. If a packet contains multiple MPTCP options, a rule
>    attempting to match the second option will never match. Having
>    multiple MPTCP options in the same packet is valid, e.g. the Linux
>    MPTCP stack inserts 'remove-addr', 'mp-prio' and 'mp-fail' after an
>    MPTCP 'dss' option ; 'mp-tcprst' can also be inserted after an 'mp-
>    fastclose'.
> 

Yep, that works! Will include in the v2, thanks!

> Cheers,
> Matt