From 49e0f1dc6e52e791f5e0ba21097aea17d5950d38 Mon Sep 17 00:00:00 2001 From: Phil Sutter Date: Wed, 29 Aug 2018 16:23:28 +0200 Subject: 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 Signed-off-by: Pablo Neira Ayuso --- doc/libnftables-json.adoc | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'doc/libnftables-json.adoc') 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: -- cgit v1.2.3