From: Slawek Figiel <slawek@isc.org>
Date: Fri, 24 Sep 2021 10:12:08 +0000 (+0200)
Subject: [#2080] Include statement in docs
X-Git-Tag: Kea-2.0.0~63
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0a0cd13c319c559342bb625c858c966367fc6928;p=thirdparty%2Fkea.git

[#2080] Include statement in docs
---

diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst
index fc7f7b5197..8dbf6a390e 100644
--- a/doc/sphinx/arm/config.rst
+++ b/doc/sphinx/arm/config.rst
@@ -212,3 +212,58 @@ Dhcp4/subnet4[0]/pool.
 
 
 .. include:: config-backend.rst
+
+
+Configuration Files Inclusion
+-----------------------------
+
+The parser provides the ability to include files. The syntax was chosen
+to look similar to how Apache includes PHP scripts in HTML code. This particular
+syntax was chosen to emphasize that the include directive is an additional
+feature and not a part of JSON syntax.
+The inclusion is implemented as a stack of files. You can use the include directive
+in nested includes. Up to ten nesting levels are supported. This arbitrarily chosen
+limit is protection against recursive inclusions.
+
+Include directive has a form:
+
+::
+
+   <?include "[RELATIVE-PATH]"?>
+
+The *[RELATIVE-PATH]* pattern should replace with a relative path to an including JSON file.
+
+To include one file from another, use the following syntax:
+
+.. code-block:: javascript
+
+   {
+      "Dhcp6": {
+         "interfaces-config": {
+            "interfaces": [ "*" ]},
+         "preferred-lifetime": 3000,
+         "rebind-timer": 2000,
+         "renew-timer": 1000,
+         <?include "subnets.json"?>
+         "valid-lifetime": 4000
+      }
+   }
+
+where the content of "subnets.json" may be:
+
+::
+
+   "subnet4": [
+      {
+         "id": 123,
+         "subnet": "192.0.2.0/24"
+      },
+      {
+         "id": 234,
+         "subnet": "192.0.3.0/24"
+      },
+      {
+         "id": 345,
+         "subnet": "10.0.0.0/8"
+      }
+   ],