From bc317b274504fcd51119c2e8d30c5c4217f8c9f3 Mon Sep 17 00:00:00 2001 From: "A. Wilcox" <AWilcox@Wilcox-Tech.com> Date: Mon, 21 Sep 2020 16:38:36 -0500 Subject: doc: Update roadmap and add Service Mgmt spec draft --- doc/roadmap.rst | 66 +++++++++++++++++++ doc/service.rst | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 258 insertions(+) create mode 100644 doc/service.rst (limited to 'doc') diff --git a/doc/roadmap.rst b/doc/roadmap.rst index b011ab8..b4517bb 100644 --- a/doc/roadmap.rst +++ b/doc/roadmap.rst @@ -58,6 +58,52 @@ Resolved TBDs +[ ] Logging system +------------------ + +* [ ] Output format + +* [ ] Configuration + +* [ ] Event logging + + * [ ] auth + + * [ ] Connection established + + * [ ] Authentication succeess + + * [ ] Authentication failure + + * [ ] Connection closed + + * [ ] operational + + * [ ] RPC executed + + * [ ] RPC unknown + + * [ ] RPC failure + + * [ ] RPC success + + * [ ] config + + * [ ] Configuration editing + + * [ ] Configuration edited + + * [ ] Configuration reading + + * [ ] Configuration operation denied + +This system is reponsible for all event logging for the NETCONF APK +project. See the `logging specification`_ for more details. + +.. _`logging specification`: ./logging.rst + + + [ ] NACM -------- @@ -65,6 +111,26 @@ This feature will require in-depth discussion. +[ ] Service management module +----------------------------- + +* [ ] Design API + +* [ ] Design YANG model + +* [ ] Implement module + + * [ ] OpenRC + + * [ ] s6? + +This module allows administration of services on the system. See the +separate `service management specification`_ for more details. + +.. _`service management specification`: ./service.rst + + + [/] System module ----------------- diff --git a/doc/service.rst b/doc/service.rst new file mode 100644 index 0000000..e8f19eb --- /dev/null +++ b/doc/service.rst @@ -0,0 +1,192 @@ +================================================= + Service 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 service management module requirements for the +NETCONF for APK Distributions system. + + +Definition of terms +------------------- + +* ``NETCONF APK``: The NETCONF for APK Distributions system, including the + base server and modules contained in the netconfapk source distribution. + +* ``service``: A long-running process (or ``daemon``) on a system. + +* ``service manager``: The component of the operating system that controls + daemons. This is sometimes also referred to as a ``service supervisor``, + however this confers additional properties that the service management + module does not require. Therefore, this document will refer to any + such system as a ``service manager``. + + +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 service manager. It +may additionally be useful for documentation writers to inform network +administrators who are interacting with NETCONF APK about how its service +management module functions. + + + + +Purpose +======= + +The service management module allows NETCONF APK to query service status, +start and stop services, list running services, and list available +services on a system. + +The service management module provides two methods of interaction. The +first is a well-defined Python API, used by NETCONF APK to provide other +module functionality. For example, this includes /system/ntp/enabled. +The second is a YANG model that allows network administrators to directly +interrogate the system via NETCONF on current service status, and to +request services to start and stop in a service-independent manner using +a well-defined RPC. + + + + +Data model definition +===================== + +A service has at least the following properties: + +* ``name``, the name of the service. + +* ``description``, a meaningful description of what the service does or + provides. This may be the name of the service if the service + description does not provide or support a description field. + +* ``enabled``, a boolean value describing whether the service is enabled + or not. When a service is enabled, it is automatically started when the + system boots. + +* ``status``, an enumeration value of the current status of the service. + + The ``ServiceStatus`` enumeration has at least the following values: + + * ``stopped``: the service is not presently started. + + * ``starting``: the service is in the process of starting up. + + * ``started``: the service is presently running. + + * ``stopping``: the service is in the process of stopping. + + * ``crashed``: the service was started, but stopped unexpectedly. + Not all service managers support this enumeration value. + + Additional values may be defined depending on the service manager + currently in use on the system. + +* ``start-time``, a timestamp when the service was started. This property + is only available if ``status`` is ``started``. + +Additional properties may be available depending on the service manager +currently in use on the system. + + + + +Python API +========== + +The service management module is loaded as any other NETCONF APK module. +It implements the ``http://adelielinux.org/ns/netconf/service`` namespace. +Other modules access the service management Python API by retrieving a +handle to the module implementing that namespace, and then calling well- +defined methods on it. + + + +``service_list()`` +------------------ + +This method takes no arguments. + +Returns an iterable of ``Service`` objects as described in the section +`Python Service objects`_. + + + +``info(service)`` +----------------- + +This method takes a single argument, ``service``. This argument is a +string and must contain the name of a service present on the system. + +This method returns the Service object associated with the service given +as the argument, as described in the section `Python Service objects`_. + +If the argument is not a string or does not the contain the name of a +service present on the system, a Python ``NameError`` will be raised. + + + +Python Service objects +---------------------- + +A Python ``Service`` object has all properties defined in the section +`Data model definition`_. Any dash (``-``) characters in a property name +are replaced with underscore (``_``) characters. + +The ``Service`` object contains the following methods: + + +``status()`` +~~~~~~~~~~~~ + +This method queries the service manager for the current status of the +service associated with the Service object. + +This method returns a value from the ``ServiceStatus`` enumeration defined +under the ``status`` property in the `Data model definition`_ section. + + +``start()`` +~~~~~~~~~~~ + +This method starts the service associated with the Service object. + +This method has no effect if the status of the service is ``started``. + +This method returns immediately with no value. To determine if a service +started successfully, you must query the service's status. + + +``stop()`` +~~~~~~~~~~ + +This method stops the service associated with the Service object. + +This method has no effect if the status of the service is ``stopped`` or +``crashed``. + +This method returns immediately with no value. To determine if a service +stopped successfully, you must query the service's status. + + + + +YANG Model +========== + +TBD -- cgit v1.2.3-70-g09d2