EXTRA_DIST += devel/terminology.dox
EXTRA_DIST += devel/unit-tests.dox
-nobase_dist_doc_DATA = examples/agent/simple.json
+nobase_dist_doc_DATA = examples/agent/comments.json
+nobase_dist_doc_DATA += examples/agent/simple.json
+nobase_dist_doc_DATA += examples/ddns/comments.json
nobase_dist_doc_DATA += examples/ddns/sample1.json
nobase_dist_doc_DATA += examples/ddns/template.json
nobase_dist_doc_DATA += examples/https/httpd2/kea-httpd2.conf
--- /dev/null
+// This is a example of a configuration for Control-Agent (CA) or simply Agent.
+// It uses embedded (i.e., which will be included in configuration objects
+// and not stripped by at lexical analysis) comments.
+
+{
+ "Control-agent":
+ {
+ // Global scope
+ "comment": "A Control Agent",
+
+ "http-host": "127.0.0.1",
+ "http-port": 8000,
+
+ // In control socket
+ "control-sockets":
+ {
+ "dhcp4":
+ {
+ "comment": "control socket for DHCP4 server",
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v4"
+ }
+ }
+
+ },
+
+ "Logging":
+ {
+ // In loggers
+ "loggers": [
+ {
+ "comment": "A logger",
+ "name": "kea-ctrl-agent"
+ }
+ ]
+ }
+}
{
"Control-agent":
{
- // We need to specify where the agent should listen to incoming HTTP
- // queries. Note that agent does not provide SSL or TLS protection
- // on its own, so limiting the traffic to localhost is a good idea.
- "http-host": "127.0.0.1",
+ // We need to specify where the agent should listen to incoming HTTP
+ // queries. Note that agent does not provide SSL or TLS protection
+ // on its own, so limiting the traffic to localhost is a good idea.
+ "http-host": "127.0.0.1",
- // Another mandatory parameter is the HTTP port.
- "http-port": 8000,
+ // Another mandatory parameter is the HTTP port.
+ "http-port": 8000,
- // This map specifies where control channel of each server is configured
- // to listen on. See 'control-socket' object in the respective
- // servers. At this time the only supported socket type is "unix".
- // Make sure that the Agent and respective servers configuration
- // matches exactly, otherwise they won't be able to communicate.
- "control-sockets":
- {
- // This is how the Agent can communicate with the DHCPv4 server.
- "dhcp4":
- {
- "socket-type": "unix",
- "socket-name": "/path/to/the/unix/socket-v4"
- },
+ // This map specifies where control channel of each server is configured
+ // to listen on. See 'control-socket' object in the respective
+ // servers. At this time the only supported socket type is "unix".
+ // Make sure that the Agent and respective servers configuration
+ // matches exactly, otherwise they won't be able to communicate.
+ "control-sockets":
+ {
+ // This is how the Agent can communicate with the DHCPv4 server.
+ "dhcp4":
+ {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v4"
+ },
- // Location of the DHCPv6 command channel socket.
- "dhcp6":
- {
- "socket-type": "unix",
- "socket-name": "/path/to/the/unix/socket-v6"
- },
+ // Location of the DHCPv6 command channel socket.
+ "dhcp6":
+ {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v6"
+ },
- // Currently DHCP-DDNS (nicknamed D2) does not support
- // command channel yet, but we hope this will change in the
- // future.
- "d2":
- {
- "socket-type": "unix",
- "socket-name": "/path/to/the/unix/socket-d2"
- }
- },
+ // Currently DHCP-DDNS (nicknamed D2) does not support
+ // command channel yet, but we hope this will change in the
+ // future.
+ "d2":
+ {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-d2"
+ }
+ },
- // CA is able to load hook libraries that augment its operation.
- // The primary functionality is the ability to add new commands.
- "hooks-libraries": [
- // Hook libraries list may contain more than one library.
- {
- // The only necessary parameter is the library filename.
- "library": "/opt/local/control-agent-commands.so",
+ // CA is able to load hook libraries that augment its operation.
+ // The primary functionality is the ability to add new commands.
+ "hooks-libraries": [
+ // Hook libraries list may contain more than one library.
+ {
+ // The only necessary parameter is the library filename.
+ "library": "/opt/local/control-agent-commands.so",
- // Some libraries may support parameters. Make sure you
- // type this section carefully, as the CA does not validate
- // it (because the format is library specific).
- "parameters": {
- "param1": "foo"
- }
- }
- ]
+ // Some libraries may support parameters. Make sure you
+ // type this section carefully, as the CA does not validate
+ // it (because the format is library specific).
+ "parameters": {
+ "param1": "foo"
+ }
+ }
+ ]
},
// Similar to other Kea components, CA also uses logging.
"Logging":
{
- "loggers": [
- {
- "name": "kea-ctrl-agent",
- "output_options": [
- {
- "output": "/var/log/kea-ctrl-agent.log",
+ "loggers": [
+ {
+ "name": "kea-ctrl-agent",
+ "output_options": [
+ {
+ "output": "/var/log/kea-ctrl-agent.log",
// Several additional parameters are possible in addition
// to the typical output. Flush determines whether logger
// flushes output to a file. Maxsize determines maximum
"flush": true,
"maxsize": 204800,
"maxver": 4
- }
- ],
- "severity": "INFO",
- "debuglevel": 0
- }
- ]
+ }
+ ],
+ "severity": "INFO",
+ "debuglevel": 0
+ }
+ ]
}
}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "‗" >
+<!ENTITY mdash "‘" >
]>
<chapter id="kea-ctrl-agent">
"control-sockets": {
"dhcp4": {
+ "comment": "main server",
"socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v4"
},
"dhcp6": {
"socket-type": "unix",
- "socket-name": "/path/to/the/unix/socket-v4"
+ "socket-name": "/path/to/the/unix/socket-v4",
+ "user-context": { "version": 3 }
}
},
</simpara>
</warning>
+ <para>
+ User contexts can store arbitrary data as long as it is valid JSON
+ syntax and its top level element is a map (i.e. the data must be
+ enclosed in curly brackets). Some hook libraries may expect specific
+ formatting, though. Please consult specific hook library
+ documentation for details.
+ </para>
+
+ <para>
+ User contexts can be specified on either global scope, control
+ socket and loggers. One other useful usage is the ability to
+ store comments or descriptions: the parser translates a
+ "comment" entry into a user-context with the entry, this allows
+ to attach a comment inside the configuration itself.
+ </para>
+
<para>
Hooks libraries can be attached to the Control Agent just like to
DHCPv4 and DHCPv6 servers. It currently supports one hook point
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
+<!ENTITY mdash "‘" >
]>
<chapter id="dhcp-ddns-server">
</section> <!-- "d2-reverse-ddns-config" -->
+ <section id="d2-user-contexts">
+ <title>User context in DDNS</title>
+
+ <note>
+ <para>User contexts were designed for hook libraries which
+ are not yet supported for DHCP-DDNS server configuration.</para>
+ </note>
+
+ <para>
+ User contexts can store arbitrary data as long as it is valid JSON
+ syntax and its top level element is a map (i.e. the data must be
+ enclosed in curly brackets).
+ </para>
+
+ <para>
+ User contexts can be specified on either global scope, ddns
+ domain, dns server, tsig key and loggers. One other useful
+ usage is the ability to store comments or descriptions: the
+ parser translates a "comment" entry into a user-context with
+ the entry, this allows to attach a comment inside the
+ configuration itself.
+ </para>
+ </section> <!-- "d2-user-contexts" -->
+
<section id="d2-example-config">
<title>Example DHCP-DDNS Server Configuration</title>
<para>
The following example configuration specified the Forward DDNS Domains.
<screen><userinput>
"DhcpDdns": {
+ "comment": "example configuration: forward part",
"forward-ddns": {
"ddns-domains": [
{
"key-name": "",
"dns-servers": [
{ "ip-address": "172.16.2.5" }
- ]
+ ],
+ "user-context": { "backup": false }
},
]
<screen><userinput>
"DhcpDdns": {
+ "comment": "example configuration: reverse part",
"reverse-ddns": {
"ddns-domains": [
{
-// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
#include <agent/parser_context.h>
#include <cc/dhcp_config_error.h>
#include <testutils/io_utils.h>
+#include <testutils/user_context_utils.h>
using namespace isc::data;
using namespace isc::test;
///
/// @param fname name of the file to be loaded
void testFile(const std::string& fname) {
+ ElementPtr json;
ElementPtr reference_json;
ConstElementPtr test_json;
cout << "Parsing file " << fname << "(" << decommented << ")" << endl;
- EXPECT_NO_THROW(reference_json = Element::fromJSONFile(decommented, true));
+ EXPECT_NO_THROW(json = Element::fromJSONFile(decommented, true));
+ reference_json = moveComments(json);
// remove the temporary file
EXPECT_NO_THROW(::remove(decommented.c_str()));
// Hopefully the list of example configs will grow over time.
TEST(ParserTest, file) {
vector<string> configs;
+ configs.push_back("comments.json");
configs.push_back("simple.json");
for (int i = 0; i<configs.size(); i++) {
-// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
#include <d2/parser_context.h>
#include <d2/tests/parser_unittest.h>
#include <testutils/io_utils.h>
+#include <testutils/user_context_utils.h>
using namespace isc::data;
+using namespace isc::test;
using namespace std;
namespace isc {
///
/// @param fname name of the file to be loaded
void testFile(const std::string& fname) {
+ ElementPtr json;
ElementPtr reference_json;
ConstElementPtr test_json;
- string decommented = isc::test::decommentJSONfile(fname);
- EXPECT_NO_THROW(reference_json = Element::fromJSONFile(decommented, true));
+ string decommented = decommentJSONfile(fname);
+
+ cout << "Parsing file " << fname << " (" << decommented << ")" << endl;
+
+ EXPECT_NO_THROW(json = Element::fromJSONFile(decommented, true));
+ reference_json = moveComments(json);
// remove the temporary file
EXPECT_NO_THROW(::remove(decommented.c_str()));
// the second time with D2Parser. Both JSON trees are then compared.
TEST(ParserTest, file) {
vector<string> configs;
+ configs.push_back("comments.json");
configs.push_back("sample1.json");
configs.push_back("template.json");
projects / thirdparty / kea.git / commitdiff
