mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 05:27:55 +00:00
Code Issues Releases Wiki Activity

[5495] Checkpoint: added doc/examples, todo: unit tests

Browse Source
This commit is contained in:
Francis Dupont 2018-01-02 10:48:16 +01:00
parent 78229eda2d
commit d716d6a3bd
7 changed files with 167 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/Makefile.am
View File

@ -8,7 +8,9 @@ EXTRA_DIST += devel/mainpage.dox
EXTRA_DIST += devel/terminology.dox EXTRA_DIST += devel/terminology.dox
EXTRA_DIST += devel/unit-tests.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/sample1.json
nobase_dist_doc_DATA += examples/ddns/template.json nobase_dist_doc_DATA += examples/ddns/template.json
nobase_dist_doc_DATA += examples/https/httpd2/kea-httpd2.conf nobase_dist_doc_DATA += examples/https/httpd2/kea-httpd2.conf

37
doc/examples/agent/comments.json Normal file
View File

@ -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"
}
]
}
}

122
doc/examples/agent/simple.json
View File

@ -3,73 +3,73 @@
{ {
"Control-agent": "Control-agent":
{ {
// We need to specify where the agent should listen to incoming HTTP // We need to specify where the agent should listen to incoming HTTP
// queries. Note that agent does not provide SSL or TLS protection // queries. Note that agent does not provide SSL or TLS protection
// on its own, so limiting the traffic to localhost is a good idea. // on its own, so limiting the traffic to localhost is a good idea.
"http-host": "127.0.0.1", "http-host": "127.0.0.1",
// Another mandatory parameter is the HTTP port. // Another mandatory parameter is the HTTP port.
"http-port": 8000, "http-port": 8000,
// This map specifies where control channel of each server is configured // This map specifies where control channel of each server is configured
// to listen on. See 'control-socket' object in the respective // to listen on. See 'control-socket' object in the respective
// servers. At this time the only supported socket type is "unix". // servers. At this time the only supported socket type is "unix".
// Make sure that the Agent and respective servers configuration // Make sure that the Agent and respective servers configuration
// matches exactly, otherwise they won't be able to communicate. // matches exactly, otherwise they won't be able to communicate.
"control-sockets": "control-sockets":
{ {
// This is how the Agent can communicate with the DHCPv4 server. // This is how the Agent can communicate with the DHCPv4 server.
"dhcp4": "dhcp4":
{ {
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v4" "socket-name": "/path/to/the/unix/socket-v4"
}, },
// Location of the DHCPv6 command channel socket. // Location of the DHCPv6 command channel socket.
"dhcp6": "dhcp6":
{ {
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v6" "socket-name": "/path/to/the/unix/socket-v6"
}, },
// Currently DHCP-DDNS (nicknamed D2) does not support // Currently DHCP-DDNS (nicknamed D2) does not support
// command channel yet, but we hope this will change in the // command channel yet, but we hope this will change in the
// future. // future.
"d2": "d2":
{ {
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-d2" "socket-name": "/path/to/the/unix/socket-d2"
} }
}, },
// CA is able to load hook libraries that augment its operation. // CA is able to load hook libraries that augment its operation.
// The primary functionality is the ability to add new commands. // The primary functionality is the ability to add new commands.
"hooks-libraries": [ "hooks-libraries": [
// Hook libraries list may contain more than one library. // Hook libraries list may contain more than one library.
{ {
// The only necessary parameter is the library filename. // The only necessary parameter is the library filename.
"library": "/opt/local/control-agent-commands.so", "library": "/opt/local/control-agent-commands.so",
// Some libraries may support parameters. Make sure you // Some libraries may support parameters. Make sure you
// type this section carefully, as the CA does not validate // type this section carefully, as the CA does not validate
// it (because the format is library specific). // it (because the format is library specific).
"parameters": { "parameters": {
"param1": "foo" "param1": "foo"
} }
} }
] ]
}, },
// Similar to other Kea components, CA also uses logging. // Similar to other Kea components, CA also uses logging.
"Logging": "Logging":
{ {
"loggers": [ "loggers": [
{ {
"name": "kea-ctrl-agent", "name": "kea-ctrl-agent",
"output_options": [ "output_options": [
{ {
"output": "/var/log/kea-ctrl-agent.log", "output": "/var/log/kea-ctrl-agent.log",
// Several additional parameters are possible in addition // Several additional parameters are possible in addition
// to the typical output. Flush determines whether logger // to the typical output. Flush determines whether logger
// flushes output to a file. Maxsize determines maximum // flushes output to a file. Maxsize determines maximum
@ -79,11 +79,11 @@
"flush": true, "flush": true,
"maxsize": 204800, "maxsize": 204800,
"maxver": 4 "maxver": 4
} }
], ],
"severity": "INFO", "severity": "INFO",
"debuglevel": 0 "debuglevel": 0
} }
] ]
} }
} }

22
doc/guide/agent.xml
View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2017;" > <!ENTITY mdash "&#x2018;" >
]> ]>
<chapter id="kea-ctrl-agent"> <chapter id="kea-ctrl-agent">
@ -66,12 +66,14 @@
"control-sockets": { "control-sockets": {
"dhcp4": { "dhcp4": {
"comment": "main server",
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v4" "socket-name": "/path/to/the/unix/socket-v4"
}, },
"dhcp6": { "dhcp6": {
"socket-type": "unix", "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 @@
</simpara> </simpara>
</warning> </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> <para>
Hooks libraries can be attached to the Control Agent just like to Hooks libraries can be attached to the Control Agent just like to
DHCPv4 and DHCPv6 servers. It currently supports one hook point DHCPv4 and DHCPv6 servers. It currently supports one hook point

31
doc/guide/ddns.xml
View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" > <!ENTITY mdash "&#x2018;" >
]> ]>
<chapter id="dhcp-ddns-server"> <chapter id="dhcp-ddns-server">
@ -768,6 +768,30 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</section> <!-- "d2-reverse-ddns-config" --> </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"> <section id="d2-example-config">
<title>Example DHCP-DDNS Server Configuration</title> <title>Example DHCP-DDNS Server Configuration</title>
<para> <para>
@ -858,6 +882,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
The following example configuration specified the Forward DDNS Domains. The following example configuration specified the Forward DDNS Domains.
<screen><userinput> <screen><userinput>
"DhcpDdns": { "DhcpDdns": {
"comment": "example configuration: forward part",
"forward-ddns": { "forward-ddns": {
"ddns-domains": [ "ddns-domains": [
{ {
@ -880,7 +905,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
"key-name": "", "key-name": "",
"dns-servers": [ "dns-servers": [
{ "ip-address": "172.16.2.5" } { "ip-address": "172.16.2.5" }
] ],
"user-context": { "backup": false }
}, },
] ]
@ -932,6 +958,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
<screen><userinput> <screen><userinput>
"DhcpDdns": { "DhcpDdns": {
"comment": "example configuration: reverse part",
"reverse-ddns": { "reverse-ddns": {
"ddns-domains": [ "ddns-domains": [
{ {

8
src/bin/agent/tests/parser_unittests.cc
View File

@ -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 // 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 // License, v. 2.0. If a copy of the MPL was not distributed with this
@ -9,6 +9,7 @@
#include <agent/parser_context.h> #include <agent/parser_context.h>
#include <cc/dhcp_config_error.h> #include <cc/dhcp_config_error.h>
#include <testutils/io_utils.h> #include <testutils/io_utils.h>
#include <testutils/user_context_utils.h>
using namespace isc::data; using namespace isc::data;
using namespace isc::test; using namespace isc::test;
@ -311,6 +312,7 @@ TEST(ParserTest, multilineComments) {
/// ///
/// @param fname name of the file to be loaded /// @param fname name of the file to be loaded
void testFile(const std::string& fname) { void testFile(const std::string& fname) {
ElementPtr json;
ElementPtr reference_json; ElementPtr reference_json;
ConstElementPtr test_json; ConstElementPtr test_json;
@ -318,7 +320,8 @@ void testFile(const std::string& fname) {
cout << "Parsing file " << fname << "(" << decommented << ")" << endl; 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 // remove the temporary file
EXPECT_NO_THROW(::remove(decommented.c_str())); 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. // Hopefully the list of example configs will grow over time.
TEST(ParserTest, file) { TEST(ParserTest, file) {
vector<string> configs; vector<string> configs;
configs.push_back("comments.json");
configs.push_back("simple.json"); configs.push_back("simple.json");
for (int i = 0; i<configs.size(); i++) { for (int i = 0; i<configs.size(); i++) {

14
src/bin/d2/tests/parser_unittest.cc
View File

@ -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 // 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 // License, v. 2.0. If a copy of the MPL was not distributed with this
@ -8,8 +8,10 @@
#include <d2/parser_context.h> #include <d2/parser_context.h>
#include <d2/tests/parser_unittest.h> #include <d2/tests/parser_unittest.h>
#include <testutils/io_utils.h> #include <testutils/io_utils.h>
#include <testutils/user_context_utils.h>
using namespace isc::data; using namespace isc::data;
using namespace isc::test;
using namespace std; using namespace std;
namespace isc { namespace isc {
@ -265,11 +267,16 @@ TEST(ParserTest, multilineComments) {
/// ///
/// @param fname name of the file to be loaded /// @param fname name of the file to be loaded
void testFile(const std::string& fname) { void testFile(const std::string& fname) {
ElementPtr json;
ElementPtr reference_json; ElementPtr reference_json;
ConstElementPtr test_json; ConstElementPtr test_json;
string decommented = isc::test::decommentJSONfile(fname); string decommented = decommentJSONfile(fname);
EXPECT_NO_THROW(reference_json = Element::fromJSONFile(decommented, true));
cout << "Parsing file " << fname << " (" << decommented << ")" << endl;
EXPECT_NO_THROW(json = Element::fromJSONFile(decommented, true));
reference_json = moveComments(json);
// remove the temporary file // remove the temporary file
EXPECT_NO_THROW(::remove(decommented.c_str())); 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. // the second time with D2Parser. Both JSON trees are then compared.
TEST(ParserTest, file) { TEST(ParserTest, file) {
vector<string> configs; vector<string> configs;
configs.push_back("comments.json");
configs.push_back("sample1.json"); configs.push_back("sample1.json");
configs.push_back("template.json"); configs.push_back("template.json");