doc: Update roadmap and add Service Mgmt spec draft

2 files changed, 258 insertions, 0 deletions

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