From d716d6a3bd25b93c41e078486dfee6a3071d43b7 Mon Sep 17 00:00:00 2001 From: Francis Dupont Date: Tue, 2 Jan 2018 10:48:16 +0100 Subject: [PATCH] [5495] Checkpoint: added doc/examples, todo: unit tests --- doc/Makefile.am | 4 +- doc/examples/agent/comments.json | 37 +++++++ doc/examples/agent/simple.json | 122 ++++++++++++------------ doc/guide/agent.xml | 22 ++++- doc/guide/ddns.xml | 31 +++++- src/bin/agent/tests/parser_unittests.cc | 8 +- src/bin/d2/tests/parser_unittest.cc | 14 ++- 7 files changed, 167 insertions(+), 71 deletions(-) create mode 100644 doc/examples/agent/comments.json diff --git a/doc/Makefile.am b/doc/Makefile.am index 0210541b28..eb35605ad5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,7 +8,9 @@ EXTRA_DIST += devel/mainpage.dox 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 diff --git a/doc/examples/agent/comments.json b/doc/examples/agent/comments.json new file mode 100644 index 0000000000..d0d0c10798 --- /dev/null +++ b/doc/examples/agent/comments.json @@ -0,0 +1,37 @@ +// 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" + } + ] + } +} diff --git a/doc/examples/agent/simple.json b/doc/examples/agent/simple.json index 819ae82154..de3932ce88 100644 --- a/doc/examples/agent/simple.json +++ b/doc/examples/agent/simple.json @@ -3,73 +3,73 @@ { "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 @@ -79,11 +79,11 @@ "flush": true, "maxsize": 204800, "maxver": 4 - } - ], - "severity": "INFO", - "debuglevel": 0 - } - ] + } + ], + "severity": "INFO", + "debuglevel": 0 + } + ] } } diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml index 90dffee1c7..5a3652b1ee 100644 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@ -1,7 +1,7 @@ + ]> @@ -66,12 +66,14 @@ "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 } } }, @@ -145,6 +147,22 @@ + + 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. + + + + 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. + + Hooks libraries can be attached to the Control Agent just like to DHCPv4 and DHCPv6 servers. It currently supports one hook point diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index 64b90f6f31..5b5bc5db77 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -1,7 +1,7 @@ + ]> @@ -768,6 +768,30 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. +
+ User context in DDNS + + + User contexts were designed for hook libraries which + are not yet supported for DHCP-DDNS server configuration. + + + + 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). + + + + 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. + +
+
Example DHCP-DDNS Server Configuration @@ -858,6 +882,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. The following example configuration specified the Forward DDNS Domains. "DhcpDdns": { + "comment": "example configuration: forward part", "forward-ddns": { "ddns-domains": [ { @@ -880,7 +905,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. "key-name": "", "dns-servers": [ { "ip-address": "172.16.2.5" } - ] + ], + "user-context": { "backup": false } }, ] @@ -932,6 +958,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. "DhcpDdns": { + "comment": "example configuration: reverse part", "reverse-ddns": { "ddns-domains": [ { diff --git a/src/bin/agent/tests/parser_unittests.cc b/src/bin/agent/tests/parser_unittests.cc index c651eaab6e..e777811463 100644 --- a/src/bin/agent/tests/parser_unittests.cc +++ b/src/bin/agent/tests/parser_unittests.cc @@ -1,4 +1,4 @@ -// 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 @@ -9,6 +9,7 @@ #include #include #include +#include using namespace isc::data; using namespace isc::test; @@ -311,6 +312,7 @@ TEST(ParserTest, multilineComments) { /// /// @param fname name of the file to be loaded void testFile(const std::string& fname) { + ElementPtr json; ElementPtr reference_json; ConstElementPtr test_json; @@ -318,7 +320,8 @@ void testFile(const std::string& fname) { 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())); @@ -344,6 +347,7 @@ void testFile(const std::string& fname) { // Hopefully the list of example configs will grow over time. TEST(ParserTest, file) { vector configs; + configs.push_back("comments.json"); configs.push_back("simple.json"); for (int i = 0; i #include #include +#include using namespace isc::data; +using namespace isc::test; using namespace std; namespace isc { @@ -265,11 +267,16 @@ TEST(ParserTest, multilineComments) { /// /// @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())); @@ -294,6 +301,7 @@ void testFile(const std::string& fname) { // the second time with D2Parser. Both JSON trees are then compared. TEST(ParserTest, file) { vector configs; + configs.push_back("comments.json"); configs.push_back("sample1.json"); configs.push_back("template.json"); -- 2.47.2