doc: Add draft Network Management API spec

1 files changed, 233 insertions, 0 deletions

diff --git a/doc/network.rst b/doc/network.rst
new file mode 100644
index 0000000..5bf9126
--- /dev/null
+++ b/doc/network.rst
@@ -0,0 +1,233 @@
+=================================================
+ 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.
+
+
+
+
+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.
+
+
+
+
+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.
+
+
+
+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.
+
+
+
+Parameters
+----------
+
+For each parameter described in the section `Data model definition`_,
+three methods exist.  Where the italicised word "*parameter*" appears,
+replace it with the desired parameter.
+
+
+``get_`` *parameter* ``(iface)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieve the parameter for the specified interface.  If the parameter is
+not set for the specified interface, ``None`` will be returned.
+
+
+``set_`` *parameter* ``(iface, value)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set the parameter for the specified interface.  If a transaction is not
+active, the parameter is immediately set on the network interface.
+
+
+``unset_`` *parameter* ``(iface)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.