From 8f3c4702c2ac68646032b30b5e7b13f21cf7b524 Mon Sep 17 00:00:00 2001 From: "A. Wilcox" Date: Mon, 21 Sep 2020 13:08:14 -0500 Subject: doc: Update logging requirements specification --- doc/logging.rst | 170 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file 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: : : : : @@ -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 -- cgit v1.2.3-70-g09d2