doc: Document ct timeout support

Add documentation for creating ct timeout objects and assigning timeout
policies via rules.

Signed-off-by: Harsha Sharma <harshasharmaiitr@gmail.com>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

diff --git a/doc/libnftables-json.adoc b/doc/libnftables-json.adoc
index 59bac17fd005113dc1318084f6bb411ab359fbb2..98303b357f10c267ebea11d1a7f49da58e28e9a2 100644 (file)
--- 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 83a25753039ac0bbb17704402ced94ec1b3184c2..6de4e8bd023fbe36a45c29f659674c795997ae71 100644 (file)
--- a/doc/stateful-objects.txt
+++ b/doc/stateful-objects.txt
@@ -1,5 +1,5 @@
-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 filter {
+       ct timeout customtimeout {
+               protocol tcp;
+               l3proto ip
+               policy = { established: 120, close: 20 }
+       }
+
+       chain output {
+               type filter hook output priority filter; policy accept;
+               ct timeout set "customtimeout"
+       }
+}
+----------------------------------
+
+.testing the updated timeout policy
+----------------------------------
+
+% conntrack -E
+
+It should display:
+
+[UPDATE] tcp      6 120 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]