1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
// Copyright (C) 2018-2022 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
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
/**
@page libyang libkea-yang - Kea YANG Utilities Library
The libkea-yang library was developed to handle base YANG operations,
such as retrieving YANG schema and configuration and translating
data between YANG data and JSON that is understandable by Kea.
@section yangTranslator Translator between YANG and JSON
An essential concept is the idea of translator. It is a primitive that is able
to convert certain data structure between YANG and JSON. It is envisaged
that more complex translators will use other translators to handle more
complex data structures. For details, see @ref isc::yang::TranslatorBasic.
It is also envisioned that translators could do the translation automatically by
relying on capabilities of iterating through data, retrieving data type
information and value information from nodes through the libyang and sysrepo
APIs.
Note that although the initial focus is on translation from YANG to JSON (so
Kea can retrieve its configuration), the opposite translation direction -
from JSON to YANG - is also very useful, for at least three reasons. First,
in many cases we can use it in tests to check that conversion back and forth
doesn't lose anything: yang = toYang(toJson(yang)). Second, YANG modules
cover two major types of data: configuration and run-time state. While
we're initially focusing on getting the configuration, the run-time state
is something that Kea is expected to provide. Kea uses JSON internally in many
places and that data will have to be exported in YANG format. Thirdly, the
SR_EV_UPDATE callback allows mid-flight configuration changes before data is
committed to the sysrepo datastore. If it ever will be used in the future,
changes applied during this step will most likely come from Kea's current JSON
configuration. As such, JSON to YANG translation will be necessary. One
application for this is reverting stuff that is necessary for Kea - Sysrepo
communication like the unix socket.
All translators take a Session pointer (a structure provided by Sysrepo that
is responsible for maintaining a connection) in constructors and derive from
the basic / base class and recursively from translators for embedded parts.
@c isc::yang::TranslatorBasic provides some methods:
- getItem() retrieves and translates basic value from YANG to JSON
- getItems() retrieves and translates a leaf-list from YANG to JSON
- getList() retrieves and translates a list from YANG to JSON
- setItem() translates and sets a basic value from JSON to YANG
- delItem() deletes a value
- forAll() iterates over the top node and its descendants and calls a function
@section yangTranslatorPool Pool translator
@c isc::yang::TranslatorPool is the standard example of a translator
for a structured value. Its constructor takes a module name: the code
implements some variants to accommodate the module with shared code
moved into a common private routine. When called with an unsupported
module, generic methods of all structure translators throw
@c isc::NotImplemented.
Note pools show two shortcomings in IETF modules:
- option sets make to track changes nearly impossible: the only easy
code is to translate the whole configuration.
- prefix and start - end forms of pool ranges are both mandatory.
(reported to authors' so should be fixed in the next version).
All structure translators depend on @c isc::yang::TranslatorBasic and
some of them depend on other structures, for instance
@c isc::yang::TranslatorPool depends on
@c isc::yang::TranslatorOptionDataList which itself as all list translators
depends on the corresponding list item translator
@c isc::yang::TranslatorOptionData. This multiple inheritance forms
a graph with the basic and the configuration translators at the two ends.
Multiple inheritance and its "diamond" issue are handled by C++ with
the "virtual" inheritance: depending classes must be virtually inherited
and explicitly constructed.
@section yangTranslatorSubnet Subnet translator
The new thing here is the use of adaptors to move timers from subnets
to pools and back.
@section yangAdaptor Adapting JSON configuration
Adaptors are tools which adapts JSON complete or partial configuration
before translation to YANG to ease this translation or after translation
from YANG to follow the Kea syntax, for instance by adding static
components which are not in the module.
Methods provided by adaptors are class methods (i.e. declared static).
Specific adaptors can be derived from the isc::yang::Adaptor base class.
There are a few basic adaptors and per structure adaptors. The second
category of adaptors are divided into:
- from JSON to YANG adaptors or pre-processing which adapt a JSON
configuration to make it acceptable by a from JSON to YANG (setXXX)
translators. For a Kea module this kind of adaptors fill some required
but missing fields, or only transform a configuration into a canonical
form. Note for a Kea module and a configuration taken from config-get
or config-write it likely does nearly nothing but the code must
handle any hand written configuration so these adaptors are always
applied.
- from YANG to JSON adaptors or post-processing which adapt translated
YANG configuration (by getXXX) to make it acceptable by a Kea server.
By definition, they are not defined for Kea modules.
@section unitTestsSysrepo Running unit tests with Sysrepo
To run YANG/NETCONF/Sysrepo tests you need to compile Kea with Sysrepo support:
@verbatim
./configure --with-sysrepo
@endverbatim
For details, see Section "YANG/NETCONF support" in the Kea Administrator
Reference Manual: https://kea.readthedocs.io/en/latest/arm/integrations.html#yang-netconf.
You also need to install YANG modules, so the unit tests are able to
retrieve, add, update and generally interact with the sysrepo information.
There are several Kea modules (*.yang in src/share/yang/modules/), mostly usable in
production, but one called keatest-module is only used in unit tests. To be able
to run unit tests as a non-root user, which is the recommended way, make sure
the sysrepo repository and /dev/shm/sr* are owned by said user. One way to
prevent sporadic chown-ing is to install sysrepo and the Kea modules as non-root.
To install all the modules, run the following script:
@verbatim
./src/share/yang/modules/utils/reinstall.sh
@endverbatim
Alternatively to install each module, issue the following command:
@verbatim
sysrepoctl -i "src/share/yang/modules/${module}.yang"
@endverbatim
To verify that you have the schemas installed, do this:
@verbatim
sysrepoctl -l
@endverbatim
Make sure that keatest-module and other necessary modules are on the list.
As DHCP modules are still being developed, if the revision has been bumped,
reinstalling it will update the module automatically . Otherwise, it can be
useful to uninstall them before reinstalling a more recent version:
@verbatim
sysrepoctl -u <module-name>
@endverbatim
Tests use these modules which you can find in src/share/yang/modules in addition
to keatest-module:
- ietf-dhcpv6-server
- kea-ctrl-agent
- kea-dhcp-ddns
- kea-dhcp4-server
- kea-dhcp6-server
Those modules depend on the following modules:
- ietf-inet-types
- ietf-yang-types
- ietf-interfaces
- kea-types
- kea-dhcp-types
The following modules are extracted from the IETF DHCPv6 YANG draft:
- ietf-dhcpv6-client
- ietf-dhcpv6-options
- ietf-dhcpv6-relay
- ietf-dhcpv6-types
All are available in the src/share/yang/modules directory using the
<module-name>[@<revision>].yang syntax for file names.
src/share/yang/modules/utils provides a few utilities for developers:
- check-revisions.sh which verifies if the revision in the file name
and in the file content matches
- check-hashes.sh which detects updates in the file content without
a revision change using the SHA-256 hash of the to YIN translation.
Updates hashes automatically if -a is passed to the script.
- gen-revisions.sh which produces the module / revision table of
the yang_revisions.h header file.
- reinstall.sh which installs all the modules.
You can run this tool:
@verbatim
src/lib/yang/pretests/sysrepo_setup_tests
@endverbatim
to verify that your environment is ready. If there is anything
wrong, it will enumerate the problems and will suggest how to solve
them.
@section yangMTConsiderations Multi-Threading Consideration for YANG Utilities
The YANG utilities are not thread safe. Note as they are used only in a
configuration context it is not a problem, and the yang / sysrepo libraries
are multi-threaded so their APIs are thread safe.
*/
|
