======================================
Logging 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 logging 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.
* `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.
Intended audience
-----------------
This document is primarily intended to be read by the implementors of
NETCONF APK. It may additionally be useful for documentation writers to
inform network administrators who are interacting with NETCONF APK about
how its logging system functions.
Architecture
============
The logging system processes messages with three fields: Category, Level,
and Message. The message's Category indicates what subsystem is emitting
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:
<iso-date> : <device> : <category> : <level> : <message>
iso-date is defined as an ISO 8601 extended timestamp, of the format:
YYYY-MM-DDThh:mm:ss
`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.
Output locations can be of one of the following three types:
* `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
==========
The following categories are defined for the NETCONF APK system.
auth
----
Messages in this category concern authentication. This includes both
successful and failed authentication attempts to the server.
operational
-----------
Messages in this category concern operations carried out. This includes
standard operations such as `edit-config` and also RPCs such as
`system-restart`.
config
------
Messages in this category concern configuration data. This includes
reading and writing to any NETCONF datastore.
TBD
===
* 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?
* Should logging to the configured Controller Server be configurable?
