[nft] doc: Document ct timeout support

Message ID 20180904185116.10826-1-harshasharmaiitr@gmail.com
State Changes Requested
Delegated to: Pablo Neira
Headers show
Series
  • [nft] doc: Document ct timeout support
Related show

Commit Message

Harsha Sharma Sept. 4, 2018, 6:51 p.m.
Add documentation for creating ct timeout objects and assigning timeout
policies via rules.

Signed-off-by: Harsha Sharma <harshasharmaiitr@gmail.com>
---
 doc/libnftables-json.adoc | 52 +++++++++++++++++++++++++++++++++++++++---
 doc/stateful-objects.txt  | 57 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 105 insertions(+), 4 deletions(-)

Comments

Pablo Neira Ayuso Oct. 2, 2018, 6:20 p.m. | #1
Hi Harsha,

On Wed, Sep 05, 2018 at 12:21:16AM +0530, Harsha Sharma wrote:
[...]
> diff --git a/doc/stateful-objects.txt b/doc/stateful-objects.txt
> index 83a2575..120673d 100644
> --- a/doc/stateful-objects.txt
> +++ b/doc/stateful-objects.txt
> @@ -1,4 +1,4 @@
> -CT
> +CT HELPER
>  ~~

This show via 'man nft' as:

       CT HELPER ~~

instead of using bold fonts, might be related to using two words for
the title?

I mean, if you look at "counter" and "quota" stateful objects, they
show different via 'man nft'.

Can you see what I mean? Thanks!

Patch

diff --git a/doc/libnftables-json.adoc b/doc/libnftables-json.adoc
index 59bac17..98303b3 100644
--- a/doc/libnftables-json.adoc
+++ b/doc/libnftables-json.adoc
@@ -23,7 +23,7 @@  libnftables-json - Supported JSON schema by libnftables
 
 'LIST_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |
 		 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT' |
-		 'METAINFO_OBJECT'
+		 'METAINFO_OBJECT' | 'CT_TIMEOUT'
 
 == DESCRIPTION
 libnftables supports JSON formatted input and output. This is implemented as an
@@ -117,7 +117,8 @@  ____
 *{ "add":* 'ADD_OBJECT' *}*
 
 'ADD_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |
-                'FLOWTABLE' | 'COUNTER | QUOTA' | 'CT_HELPER' | 'LIMIT'
+                'FLOWTABLE' | 'COUNTER | QUOTA' | 'CT_HELPER' | 'LIMIT' |
+		'CT_TIMEOUT'
 ____
 
 Add a new ruleset element to the kernel.
@@ -161,7 +162,7 @@  ____
 'LIST_OBJECT' := 'TABLE' | 'TABLES' | 'CHAIN' | 'CHAINS' | 'SET' | 'SETS' |
                  'MAP' | 'MAPS | COUNTER' | 'COUNTERS' | 'QUOTA' | 'QUOTAS' |
                  'CT_HELPER' | 'CT_HELPERS' | 'LIMIT' | 'LIMITS | RULESET' |
-                 'METER' | 'METERS' | 'FLOWTABLES'
+                 'METER' | 'METERS' | 'FLOWTABLES' | 'CT_TIMEOUT'
 ____
 
 List ruleset elements. The plural forms are used to list all objects of that
@@ -559,6 +560,42 @@  This object represents a named limit.
 *inv*::
 	If true, match if limit was exceeded. If omitted, defaults to *false*.
 
+=== CT TIMEOUT
+[verse]
+____
+*{ "ct timeout": {
+	"family":* 'STRING'*,
+	"table":* 'STRING'*,
+	"name":* 'STRING'*,
+	"handle":* 'NUMBER'*,
+	"protocol":* 'CTH_PROTO'*,
+	"state":* 'STRING'*,
+	"value:* 'NUMBER'*,
+	"l3proto":* 'STRING'
+*}}*
+
+'CTH_PROTO' := *"tcp"* | *"udp"* | *"dccp"* | *"sctp"* | *"gre"* | *"icmpv6"* | *"icmp"* | *"generic"*
+____
+
+This object represents a named conntrack timeout policy.
+
+*family*::
+	The table's family.
+*table*::
+	The table's name.
+*name*::
+	The ct timeout object's name.
+*handle*::
+	The ct timeout object's handle. In input, used for *delete* command only.
+*protocol*::
+	The ct timeout object's layer 4 protocol.
+*state*::
+	The connection state name, for which timeout value has to be updated, e.g. *"established"*, *"syn_sent"*, *"close"* or *"close_wait"*.
+*value*::
+	The updated timeout value for specified connection state.
+*l3proto*::
+	The ct timeout object's layer 3 protocol, e.g. *"ip"* or *"ip6"*.
+
 == STATEMENTS
 Statements are the building blocks for rules. Each rule consists of at least a
 single statement.
@@ -952,6 +989,15 @@  Limit number of connections using conntrack.
 	If *true*, match if *val* was exceeded. If omitted, defaults to
 	*false*.
 
+=== CT TIMEOUT
+[verse]
+*{ "ct timeout":* 'EXPRESSION' *}*
+
+Assign connection tracking timeout policy.
+
+*ct timeout*::
+	CT timeout reference.
+
 == EXPRESSIONS
 Expressions are the building blocks of (most) statements. In their most basic
 form, they are just immediate values represented as JSON string, integer or
diff --git a/doc/stateful-objects.txt b/doc/stateful-objects.txt
index 83a2575..120673d 100644
--- a/doc/stateful-objects.txt
+++ b/doc/stateful-objects.txt
@@ -1,4 +1,4 @@ 
-CT
+CT HELPER
 ~~
 [verse]
 *ct* helper 'helper' {type 'type' protocol 'protocol' ; [l3proto 'family' ;] }
@@ -40,6 +40,61 @@  table inet myhelpers {
 }
 ----------------------------------
 
+CT TIMEOUT
+~~
+[verse]
+*ct* timeout 'name' {protocol 'protocol' ; policy = {'state': 'value'} ;[l3proto 'family' ;] }
+
+Ct timeout is used to update connection tracking timeout values.Timeout policies are assigned
+with the *ct timeout set* statement. 'protocol' and 'policy' are
+  mandatory, l3proto is derived from the table family by default.
+
+.conntrack timeout specifications
+[options="header"]
+|=================
+|Keyword | Description | Type
+| protocol |
+layer 4 protocol of the timeout object |
+string (e.g. ip)
+|state |
+connection state name |
+string (e.g. "established")
+|value |
+timeout value for connection state |
+unsigned integer
+|l3proto |
+layer 3 protocol of the timeout object |
+address family (e.g. ip)
+|=================
+
+.defining and assigning ct timeout policy
+----------------------------------
+table ip raw {
+	ct timeout cttime {
+		protocol tcp;
+		l3proto ip
+		policy = { established: 111, close: 13 }
+	}
+
+	chain output {
+		type filter hook output priority -300; policy accept;
+		ct timeout set "cttime"
+	}
+}
+----------------------------------
+
+.testing the updated timeout policy
+----------------------------------
+
+%conntrack -E
+
+It should display:
+
+[NEW] tcp      6 111 ESTABLISHED src=172.16.19.128 dst=172.16.19.1
+sport=22 dport=41360 [UNREPLIED] src=172.16.19.1 dst=172.16.19.128
+sport=41360 dport=22
+----------------------------------
+
 COUNTER
 ~~~~~~~
 [verse]