doc: Update logging requirements specification

1 files changed, 125 insertions, 45 deletions

diff --git a/doc/logging.rst b/doc/logging.rst
index 54bfbc1..c282b21 100644
--- a/doc/logging.rst
+++ b/doc/logging.rst
@@ -24,10 +24,7 @@ Definition of terms
 * `NETCONF APK`: The NETCONF for APK Distributions system, including the
   base server and modules contained in the netconfapk source distribution.
 
-* `controller server`: A system on the network that runs the NSL
-  Controller system, a presently-undocumented AAA and telemetry system.
-
-* `stdout`: The standard output stream as defined by POSIX.
+* `stderr`: The standard error output stream as defined by POSIX.
 
 
 Intended audience
@@ -50,8 +47,8 @@ the message.  The message's Level indicates the urgency of the message,
 and may be one of the following five values: Critical, Error, Warning,
 Info, and Debug.  The message's Message is the text being logged.
 
-The system has a "catch-all" log, which by default outputs every message
-processed to `stdout`, with the following format:
+The system outputs every message processed to `stderr`, with the
+following format:
 
     <iso-date> : <device> : <category> : <level> : <message>
 
@@ -61,47 +58,31 @@ iso-date is defined as an ISO 8601 extended timestamp, of the format:
 
 `device` is the hostname of the device running the logging system.
 
-The administrator may configure one or more outputs for each category,
-including defining one or more explicit outputs for the "catch-all" log.
-
-All messages will additionally be sent to a Controller Server, if one is
-configured.  This will include the device name and all three message
-fields.  This cannot be disabled.
-
 
 
 
 Configuration
 =============
 
-The `netconf.conf` YAML configuration file will be read for a top-level
-`logging` node, which must be a mapping.  Each key will be interpreted
-as the name of a Category.  The `default` key will configure the "catch-
-all" log.  The value must be either a string scalar, or a sequence of
-string scalars.  Each scalar describes an output location for the
-specified logging category.
+The `netconf.conf` YAML configuration file will be read for a scalar
+`loglevel` present in the top-level `server` node, which defines the
+lowest log level to output.  The default, if the `loglevel` scalar is not
+set, is `info`.
 
-Output locations can be of one of the following three types:
+The `loglevel` node is case-insensitive.
 
-* `stdout`.  If the scalar is the exact string "stdout", the specified
-  messages will be written to the standard output stream.
 
-* `file:`.  If the scalar starts with the string "file:", and an absolute
-  path follows the "file:" string, the specified messages will be
-  appended to the file at the specified path.
 
-* `url:`.  If the scalar starts with the string "url:", and an HTTPS URL
-  follows the "url:" string, the specified messages will be sent to the
-  URL specified using the POST HTTP verb.  The log message will be the
-  payload, and the Content-Type will be text/plain.
 
+Categories and Log Messages
+===========================
 
+Each following section defines a logging category for the NETCONF APK
+system.  Under each logging category, each event that would generate a
+message in that category will be described.
 
-
-Categories
-==========
-
-The following categories are defined for the NETCONF APK system.
+This list is not exclusive.  Underlying system libraries may log
+additional messages that are not included in this list.
 
 
 auth
@@ -110,6 +91,44 @@ auth
 Messages in this category concern authentication.  This includes both
 successful and failed authentication attempts to the server.
 
+Connection established
+``````````````````````
+This event is triggered when a connection is established, before
+authentication is attempted.
+
+:Format:
+  Connection from %{ip}:%{srcport} established with client %{client_ver}
+:Level:
+  Info
+
+Authentication succeess
+```````````````````````
+This event is triggered when authentication is successful and a user is
+granted access to the system.
+
+:Format:
+  Authentication granted to %{user} from %{ip}:%{srcport}, session %{sessid}
+:Level:
+  Info
+
+Authentication failure
+``````````````````````
+This event is triggered when authentication has failed.
+
+:Format:
+  Authentication failed for %{user} from %{ip}:%{srcport}
+:Level:
+  Error
+
+Connection closed
+`````````````````
+This event is triggered when a client disconnects.
+
+:Format:
+  Session %{sessid} for %{user} closed
+:Level:
+  Info
+
 
 operational
 -----------
@@ -118,23 +137,84 @@ Messages in this category concern operations carried out.  This includes
 standard operations such as `edit-config` and also RPCs such as
 `system-restart`.
 
+RPC executed
+````````````
+This event is triggered when any RPC is sent to the system.
 
-config
-------
+:Format:
+  RPC %{rpc} invoked by %{user} on session %{sessid}
+:Level:
+  Info
 
-Messages in this category concern configuration data.  This includes
-reading and writing to any NETCONF datastore.
+RPC unknown
+```````````
+This event is triggered when an RPC is received that the system does not
+recognise as a valid RPC.
+
+:Format:
+  RPC %{rpc} invoked by %{user} on session %{sessid} is unknown
+:Level:
+  Warning
 
+RPC failure
+```````````
+This event is triggered when an RPC encounters an error during execution.
 
+:Format:
+  RPC %{rpc} invoked by %{user} on session %{sessid} encountered error %{error}
+:Level:
+  Error
 
+RPC success
+```````````
+This event is triggered when an RPC is executed successfully.
 
-TBD
-===
+:Format:
+  RPC %{rpc} invoked by %{user} on session %{sessid} completed successfully
+:Level:
+  Info
 
-* What happens if a Controller Server is configured and unreachable?
 
-  * If we choose to buffer and wait for it to reachable again, should
-    there be a maximum buffer size?  Maximum age of replayed messages?
-    Should these parameters be configurable or hard?
+config
+------
+
+Messages in this category concern configuration data.  This includes
+reading and writing to any NETCONF datastore.
 
-* Should logging to the configured Controller Server be configurable?
+Configuration editing
+`````````````````````
+This event is triggered just before `edit-config` is executed.
+
+:Format:
+  %{user} on session %{sessid} is editing configuration: %{xml}
+:Level:
+  Debug
+
+Configuration edited
+````````````````````
+This event is triggered when `edit-config` nodes are being processed by
+their respective NETCONF modules.
+
+:Format:
+  %{user} on session %{sessid} is editing %{node}: %{module-specific information}
+:Level:
+  Info
+
+Configuration reading
+`````````````````````
+This event is triggered just before `get-config` or `get` is executed.
+
+:Format:
+  %{user} on session %{sessid} is requesting configuration: %{xml}
+:Level:
+  Debug
+
+Configuration operation denied
+``````````````````````````````
+This event is triggered when a user attempts an operation on a datastore
+that is not permitted by the current NACM policy.
+
+:Format:
+  %{user} on session %{sessid} attempted %{operation} on %{node}, not permitted by NACM
+:Level:
+  Error