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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
=================================================
Network Management Requirements for NETCONF APK
=================================================
:Author:
A. Wilcox
:Copyright:
© 2020 Adélie Software in the Public Benefit, Inc. NCSA license.
:Status:
Draft
Introduction
============
This document defines the network management module requirements for the
NETCONF for APK Distributions system.
Definition of terms
-------------------
A basic familiarity with common networking terms is assumed. Terms
specific to this document are defined as follows.
* ``NETCONF APK``: The NETCONF for APK Distributions system, including the
base server and modules contained in the netconfapk source distribution.
* ``network management system``: The system used on a computer used to
control network interfaces. Common examples include NetworkManager,
ifupdown-ng, and netifrc.
Intended audience
-----------------
This document is primarily intended to be read by the implementors of
NETCONF APK. It is also intended to be read by implementors of external
NETCONF APK modules that need to interact with the network manager. It
may additionally be useful for documentation writers to inform network
administrators who are interacting with NETCONF APK about how its network
management module functions.
Purpose
=======
The network management module allows NETCONF APK to:
* Enumerate configured network interfaces on a computer.
Note that this enumeration is only for network interfaces with a
defined configuration. Interfaces that are present on the system, but
not configured, shall **not** be present in this enumeration.
* Retrieve configuration information for a specific interface.
* Set configuration information for a specific interface.
The network management module provides a well-defined Python API, used by
NETCONF APK to provide other module functionality. This API will be used
by many of the IETF Standard network and IP configuration YANG models.
This Python API is implemented as a module to facilitate the abstraction
of the network management system from the implementation of the actual
model modules. This allows for support of multiple network management
systems with a single model module.
**Note**: If a DHCP client module is not loaded, some features (including
determining if an IP address is sourced from DHCP, and controlling DHCP
usage) may not be available.
Data model definition
=====================
A network interface has the following parameters:
* ``name``, the name of the network interface. This parameter is
read-only.
* ``description``, a freeform string describing the network interface set
by a network administrator.
* ``enabled``, a boolean value describing whether the network interface
is enabled or not. Toggling this setting should immediately change the
state of the interface.
* ``ipv4_enabled``, a boolean value describing whether the network
interface shall participate in IPv4 networks or not.
* ``ipv4_forwarding``, a bolean value describing whether the network
interface shall forward IPv4 packets between hosts.
* ``ipv4_mtu``, an integer value describing the Maximum Transmission
Unit (MTU) for IPv4 packets on the network interface.
* ``ipv6_enabled``, a boolean value describing whether the network
interface shall participate in IPv6 networks or not.
* ``ipv6_forwarding``, a bolean value describing whether the network
interface shall forward IPv6 packets between hosts.
* ``ipv6_mtu``, an integer value describing the Maximum Transmission
Unit (MTU) for IPv6 packets on the network interface.
* ``ipv6_dad_xmit``, an integer value describing the number of DAD probes
to send when configuring this network interface for IPv6 operation.
* ``ipv6_slaac_globaladdr``, a boolean value describing whether SLAAC
addresses on the network interface will be global.
* ``ipv6_slaac_tempaddr``, a boolean value describing whether SLAAC
addresses on the network interface will be temporary.
* ``ipv6_slaac_validlft``, an integer value describing the lifetime of
temporary SLAAC addresses on the network interface.
* ``ipv6_slaac_preflft``, an integer value describing the preferred
lifetime of temporary SLAAC addresses on the network interface.
Python API
==========
The network management system integration module is loaded as any other
NETCONF APK module. The integration module shall implement the
``http://netconf.adelielinux.org/ns/netmgmt`` namespace. Other modules
access the network management system integration Python API by retrieving
a handle to the module implementing that namespace, then call well-
defined methods on it.
``interface_list()``
--------------------
This method takes no arguments.
Returns a list of strings, where each string is a configured network
interface.
``remove_interface(iface)``
---------------------------
Entirely remove a configured interface from the configuration store.
Transactions
------------
You may queue multiple operations to be saved at one time. This allows
processing of multiple nodes at once in a single <edit-config/>
operation, for example.
``begin_transaction()``
~~~~~~~~~~~~~~~~~~~~~~~
Starts a transaction. Every operation performed until ``commit`` is
called will be queued for later.
``commit()``
~~~~~~~~~~~~
Saves all queued operations to configuration storage and configures
network interfaces.
``rollback()``
~~~~~~~~~~~~~~
Erases all queued operations and restores the configuration from when
the transaction began.
``transaction()``
~~~~~~~~~~~~~~~~~
A Python context manager designed to be used with the ``with`` keyword.
Parameters
----------
For manipulating parameters in the section `Data model definition`_,
four methods exist.
``get_param(iface, parameter)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the parameter for the specified interface. If the parameter is
not set for the specified interface, ``None`` will be returned.
``curr_param(iface, parameter)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the current, live value for the parameter for the specified
interface. If the parameter is not set for the specified interface,
``None`` will be returned. The value returned from ``curr_param`` may
differ from ``get_param`` if a network administrator has changed the
value externally, or if the system configuration store is malfunctioning.
``set_param(iface, parameter, value)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set the parameter for the specified interface. If a transaction is not
active, the parameter is immediately set on the network interface.
``unset_param(iface, parameter)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unset the parameter for the specified interface. If a transaction is not
active, the parameter is immediately unset on the network interface.
This may involve resetting a value to a system-defined default value.
Addresses
---------
The following methods exist for manipulating addresses on a network
interface.
``list_addresses(iface)``
~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve all configured addresses for the specified network interface.
The return type is always an iterable; if no addresses are configured,
the iterable will be empty. Each element is a string in the format
"``ip/prefix``" where ``ip`` is the IP address and ``prefix`` is the
subnet prefix.
``add_address(iface, type, addr, prefix)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add a statically configured address of the specified ``type`` to the
specified network interface.
``type`` must be ``socket.AF_INET`` for IPv4 or ``socket.AF_INET6`` for
IPv6. ``addr`` must be the IP address as a string. ``prefix`` may be
an integer or string containing only numeric digits that represents the
desired subnet prefix for the address.
If a transaction is not active, the address is immediately added to the
network interface.
``remove_address(iface, addr)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Remove a statically configured address from the specified network
interface.
``addr`` may optionally have a ``prefix`` component, but it will be
ignored and will *not* be checked for accuracy before the address is
removed.
If a transaction is not active, the address is immediately removed from
the network interface.
|
