mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-29 13:07:50 +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/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

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":
{
// 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
}
]
}
}

22
doc/guide/agent.xml
View File

@ -1,7 +1,7 @@
<?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 "&#x2017;" >
<!ENTITY mdash "&#x2018;" >
]>
<chapter id="kea-ctrl-agent">
@ -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 @@
</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

31
doc/guide/ddns.xml
View File

@ -1,7 +1,7 @@
<?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 "&#x2014;" >
<!ENTITY mdash "&#x2018;" >
]>
<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 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>
@ -858,6 +882,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
The following example configuration specified the Forward DDNS Domains.
<screen><userinput>
"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.
<screen><userinput>
"DhcpDdns": {
"comment": "example configuration: reverse part",
"reverse-ddns": {
"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
// 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 <cc/dhcp_config_error.h>
#include <testutils/io_utils.h>
#include <testutils/user_context_utils.h>
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<string> configs;
configs.push_back("comments.json");
configs.push_back("simple.json");
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
// 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/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 {
@ -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<string> configs;
configs.push_back("comments.json");
configs.push_back("sample1.json");
configs.push_back("template.json");