Notification Message Headers and BundlesCisco Systemsevoit@cisco.comFraunhofer SIThenk.birkholz@sit.fraunhofer.deYumaWorksandy@yumaworks.comFutureweiludwig@clemm.orgCisco Systemstimjenki@cisco.com
Operations & Management
NETCONFDraftThis document defines a new notification message format. Included are:a new notification mechanism and encoding to replace the one way operation of RFC-5277a set of common, transport agnostic message header objects.how to bundle multiple event records into a single notification message.how to ensure these new capabilities are only used with capable receivers.Mechanisms to support subscription to event notifications have been defined in and . Work on those documents has shown that notifications described in section 7.16 could benefit from transport independent headers. With such headers, communicating the following information to receiving applications can be done without explicit linkage to an underlying transport protocol:the time the notification was generatedthe time the notification was placed in a message and queued for transportan identifier for the process generating the notificationsignatures to verify authenticitya subscription id which allows a notification be correlated with a request for that notificationmultiple notifications bundled into one transportable messagea message-id allowing a receiver to check for message loss/reorderingThe document describes information elements needed for the functions above. It also provides instances of YANG structures for sending messages containing one or more notifications to a receiver.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
when, and only when, they appear in all capitals, as shown here. The definition of notification is in Section 4.2.10. Publisher, receiver, subscription, and event occurrence time are defined in . There are a number of transport independent headers which should have common definition. These include:subscription-id: provides a reference into the reason the publisher believed the receiver wishes to be notified of this specific information.notification-time: the origination time where a notification was fully generated within the publisher.notification-id: Identifies an instance of an emitted notification to a receiver.observation-domain-id: identifies the publisher process which discovered and recorded the event notification. (note: look to reuse the domains set up with IPFIX.)message-time: the time the message was packaged sent to the transport layer for delivery to the receiver.signature: allows an application to sign a message so that a receiver can verify the authenticity of the message.message-id: for a specific message generator, this identifies a message which includes one or more event records. The message-id increments by one with sequential messages.message-generator-id: identifier for the process which created the message. This allows disambiguation of an information source, such as the identification of different line cards sending the messages. Used in conjunction with previous-message-id, this can help find drops and duplications when messages are coming from multiple sources on a device. If there is a message-generator-id in the header, then the previous-message-id MUST be the message-id from the last time that message-generator-id was sent.A specific set of well-known objects are of potential use to networking layers prior being interpreted by some receiving application layer process. By exposing this object information as part of a header, and by using standardized object names, it becomes possible for this object information to be leveraged in transit.The objects defined in the previous section are these well-known header objects. These objects are identified within a dedicated header subtree which leads off a particular transportable message. This allows header objects to be easily be decoupled, stripped, and processed separately.A receiver which supporting this document MUST be able to handle receipt of either type of message from a publisher.This section has been deleted from previous versions. It will be re-instated if NETCONF WG members are not comfortable with the efficiency of the solution which can encode many notifications per message, as described below.While possible in some scenarios, it often inefficient to marshal and transport every notification independently. Instead, scale and processing speed can be improved by placing multiple notifications into one transportable bundle.The format of this bundle appears in the YANG structure below, and is fully defined in the YANG module. There are three parts of this bundle:
a message header describing the marshaling, including information such as when the marshaling occurreda list of encapsulated informationan optional message footer for whole-message signing and message-generator integrity verification.Within the list of encapsulated notifications, there are also three parts:
a notification header defining what is in an encapsulated notificationthe actual notification itselfan optional notification footer for individual notification signing and observation-domain integrity verification.An XML instance of a message might look like:A publisher MUST select the set of headers to use within any particular message. The two mandatory headers which MUST always be applied are 'message-time' and 'subscription-id'Beyond these two mandatory headers, additional headers MAY be included. Configuration of what these optional headers should be can come from the following sources:Publisher wide default headers which are placed on all notifications. An optional header is a publisher default if its identity is included within the 'additional-headers' leaf-list.More notification specific headers may also be desired. If new headers are needed for a specific type of YANG notification, these can be populated through 'additional-notification-headers' leaf-list.An application process may also identify common headers to use when transporting notifications for a specific subscription. How such application specific configuration is accomplished within the publisher is out-of-scope.The set of headers selected and populated for any particular message is derived from the union of the mandatory headers and configured optional headers.The YANG tree showing elements of configuration is depicted in the following figure.Of note in this tree is the optional feature of 'publisher'. This feature indicates an ability to send notifications. A publisher supporting this specification MUST also be able to parse any messages received as defined in this document.We need capability exchange from the receiver to the publisher at transport session initiation to indicate support for this specification.For all types of transport connections, if the receiver indicates support for this specification, then it MAY be used. In addition, one-way notifications MUST NOT be used if the receiver indicates support for this specification to a publisher which also supports it.Where NETCONF transport is used, advertising this specification's namespace during an earlier client capabilities discovery phase MAY be used to indicate support for this specification: NOTE: It is understood that even though it is allowed in section 8.1, robust NETCONF client driven capabilities exchange is not something which is common in implementation. Therefore reviewers are asked to submit alternative proposals to the mailing list.For RESTCONF, a mechanism for capability discovery is TBD. Proposals are welcome here.The mechanism described above assumes that a capability discovery phase happens before a subscription is started. This is not always the case. There is no guarantee that a capability exchange has taken place before the messages are emitted. A solution for this in the case of HTTP based transport could be that a receiver would have to reply "ok" and also return the client capabilities as part a response to the initiation of the POST.With this specification, there is no change to YANG's 'notification' statementLegacy clients are unaffected, and existing users of , , and are free to use current behaviors until all involved device support this specification.Certain headers might be computationally complex for a publisher to deliver. Signatures or encryption are two examples of this. It MUST be possible to suspend or terminate a subscription due to lack of resources based on this reason.Decisions on whether to bundle or not to a receiver are fully under the purview of the Publisher. A receiver could slow delivery to existing subscriptions by creating new ones. (Which would result in the publisher going into a bundling mode.) For their valuable comments, discussions, and feedback, we wish to acknowledge Martin Bjorklund, Einar Nilsen-Nygaard, and Kent Watsen. YANG Data Structure ExtensionsYumaWorksCiscoWatsen NetworksCustom Subscription to Event StreamsYANG Datastore SubscriptionRestconf and HTTP transport for event notifications(To be removed by RFC editor prior to publication)v06 - v07
Updated author affiliation.v05 - v06
With SN and YP getting RFC numbers, revisiting this document.Changed yang-data to draft-ietf-netmod-yang-data-ext's 'structure'.Removed the ability to reference structures other than YANG notifications.v04 - v05
Revision before expiration. Awaiting closure of SN and YP prior to update.v03 - v04
Terminology tweaks.Revision before expiration. Awaiting closure of SN prior to update.v02 - v03
Removed the option for an unbundled message. This might be re-added later for transport efficiency if desired by the WGNew message structure driven by the desire to put the signature information at the end.v01 - v02
Fixed the yang-data encapsulation container issueUpdated object definitions to point to RFC-7950 definitionsAdded headers for module and notification-type.v00 - v01
Alternative to 5277 one-way notification addedStorage of default headers by notification typeBackwards compatibilityCapability discoveryMove to yang-dataRemoved dscp and record-type as common headers. (Record type can be determined by the namespace of the record contents. Dscp is useful where applications need internal communications within a Publisher, but it is unclear as to whether this use case need be exposed to a receiver.(To be removed by RFC editor prior to publication)A complete JSON document is supposed to be sent as part of Media Type "application/yang-data+json". As we are sending separate notifications after each other, we need to choose whether we start with some extra encapsulation for the very first message pushed, or if we want a new Media Type for streaming updates.Improved discovery mechanisms for NETCONFNeed to ensure the proper references exist to a notification definition driven by RFC-7950 which is acceptable to other eventual users of this specification.(To be removed by RFC editor prior to publication)This section discusses a future functional addition which could leverage this draft. It is included for informational purposes only.A dynamic subscriber might want to mandate that certain headers be used for push updates from a publisher. Some examples of this include a subscriber requesting to:
establish this subscription, but just if transport messages containing the pushed data will be encrypted,establish this subscription, but only if you can attest to the information being delivered in requested notification records, orprovide a sequence-id for all messages to this receiver (in order to check for loss).Providing this type of functionality would necessitate a new revision of the 's RPCs and state change notifications. Subscription specific header information would overwrite the default headers identified in this document.(To be removed by RFC editor prior to publication)YANG one-way exchanges currently use a non-extensible header and encoding defined in section 4 of RFC-5277.
These RFCs MUST be updated to enable this draft. These RFCs SHOULD be updated to provide examples Sections which expose netconf:capability:notification:1.0 are 4.2.10Sections which provide examples using netconf:notification:1.0 are 7.10.4, 7.16.3, and 9.9.6Section 6.4 demands use of RFC-5277's netconf:notification:1.0, and later in the section provides an example.