summaryrefslogtreecommitdiffstats
path: root/doc/libnftables-json.adoc
diff options
context:
space:
mode:
authorPhil Sutter <phil@nwl.cc>2018-08-29 16:23:28 +0200
committerPablo Neira Ayuso <pablo@netfilter.org>2018-08-30 12:19:36 +0200
commit49e0f1dc6e52e791f5e0ba21097aea17d5950d38 (patch)
tree00215046781f409c62974cd57bf75f96ad265a51 /doc/libnftables-json.adoc
parent90d4ee087171e75d5313359ad6b6f1341e51ddc5 (diff)
JSON: Add metainfo object to all output
Right now this object merely contains the nftables version and release name as well as a JSON schema version, but it could be extended arbitrarily. In the future, this will also allow for non-compatible schema changes should the need for this arise. Adjust the parser to accept metainfo objects and make it verify json_schema_version to be less than or equal to the one hard-coded in the library. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
Diffstat (limited to 'doc/libnftables-json.adoc')
-rw-r--r--doc/libnftables-json.adoc25
1 files changed, 23 insertions, 2 deletions
diff --git a/doc/libnftables-json.adoc b/doc/libnftables-json.adoc
index c174a354..59bac17f 100644
--- a/doc/libnftables-json.adoc
+++ b/doc/libnftables-json.adoc
@@ -16,13 +16,14 @@ libnftables-json - Supported JSON schema by libnftables
'CMD_OBJECTS' := 'CMD_OBJECT' [ *,* 'CMD_OBJECTS' ]
-'CMD_OBJECT' := *{* 'CMD'*:* 'LIST_OBJECT' *}*
+'CMD_OBJECT' := *{* 'CMD'*:* 'LIST_OBJECT' *}* | 'METAINFO_OBJECT'
'CMD' := *"add"* | *"replace"* | *"create"* | *"insert"* | *"delete"* |
*"list"* | *"reset"* | *"flush"* | *"rename"*
'LIST_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |
- 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT'
+ 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT' |
+ 'METAINFO_OBJECT'
== DESCRIPTION
libnftables supports JSON formatted input and output. This is implemented as an
@@ -47,6 +48,26 @@ It's value is a ruleset element - basically identical to output elements apart
from certain properties which may be interpreted differently or are required
when output generally omits them.
+== METAINFO OBJECT
+In output, the first object in *nftables* array is a special one containing
+library information. Its content is as follows:
+
+[verse]
+*{ "metainfo": {
+ "version":* 'STRING'*,
+ "release_name":* 'STRING'*,
+ "json_schema_version":* 'NUMBER'
+*}}*
+
+The values of *version* and *release_name* properties are equal to the package
+version and release name as printed by *nft -v*. The value of
+*json_schema_version* property is an integer indicating the schema version.
+
+If supplied in library input, the parser will verify *json_schema_version* value
+to not exceed the internally hardcoded one (to make sure the given schema is
+fully understood). In future, a lower number than the internal one may activate
+compatibility mode to parse outdated and incompatible JSON input.
+
== COMMAND OBJECTS
The structure accepts an arbitrary amount of commands which are interpreted in
order of appearance. For instance, the following standard syntax input: