Internet DRAFT - draft-gunter-calext-maintenance-notifications
draft-gunter-calext-maintenance-notifications
Calendaring Extensions R. Gunter, Ed.
Internet-Draft Twitch
Intended status: Experimental July 3, 2019
Expires: January 4, 2020
Maintenance Notification Improvements Using iCalendar
draft-gunter-calext-maintenance-notifications-00
Abstract
This document proposes a maintenance notification convention that
requires the use an iCalendar file augmented with standarzied and
machine parseable metadata. The metadata is constructed by using the
x-name property in the iCalendar file in compliance with [RFC 5545]
[RFC5545]. This specification substantially reduces automation
efforts, and still provides easy calendaring for manual processing.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 4, 2020.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Gunter Expires January 4, 2020 [Page 1]
Internet-Draft Abbreviated Title July 2019
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. iCalendar Object . . . . . . . . . . . . . . . . . . . . 4
2.3. iCalendar Properties . . . . . . . . . . . . . . . . . . 4
2.3.1. Method Calendar Property . . . . . . . . . . . . . . 4
2.4. Event Component and Associated Properties . . . . . . . . 5
2.5. Descriptive Component Properties . . . . . . . . . . . . 6
2.5.1. Provider . . . . . . . . . . . . . . . . . . . . . . 6
2.5.2. Account . . . . . . . . . . . . . . . . . . . . . . . 7
2.5.3. Maintenance ID . . . . . . . . . . . . . . . . . . . 8
2.5.4. Object ID . . . . . . . . . . . . . . . . . . . . . . 8
2.5.5. Impact . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.6. Status . . . . . . . . . . . . . . . . . . . . . . . 11
3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1. Initial Maintenance Notification . . . . . . . . . . . . 12
3.1.1. Example Provider . . . . . . . . . . . . . . . . . . 12
3.1.2. Example Consumer . . . . . . . . . . . . . . . . . . 13
3.2. Updated Maintenance Notification Window . . . . . . . . . 13
3.2.1. Example Provider . . . . . . . . . . . . . . . . . . 14
3.2.2. Example Consumer . . . . . . . . . . . . . . . . . . 14
3.3. Canceled Maintenance Notification Window . . . . . . . . 14
3.3.1. Example Provider . . . . . . . . . . . . . . . . . . 14
3.3.2. Example Consumer . . . . . . . . . . . . . . . . . . 15
3.4. Open Maintenance Notification Window . . . . . . . . . . 15
3.4.1. Example Provider . . . . . . . . . . . . . . . . . . 15
3.4.2. Example Consumer . . . . . . . . . . . . . . . . . . 16
3.5. Closed Maintenance Notification Window . . . . . . . . . 16
3.5.1. Example Provider . . . . . . . . . . . . . . . . . . 16
3.5.2. Example Consumer . . . . . . . . . . . . . . . . . . 16
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1. Initial Maintenance Notification . . . . . . . . . . . . 17
4.2. Updated Maintenance Notification . . . . . . . . . . . . 17
4.3. Cancelled Maintenance Notification . . . . . . . . . . . 18
4.4. Open Maintenance Notification . . . . . . . . . . . . . . 19
4.5. Closed Maintenance Notification . . . . . . . . . . . . . 19
5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 20
5.1. Localization Considerations . . . . . . . . . . . . . . . 20
5.2. Security Considerations . . . . . . . . . . . . . . . . . 20
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21
8. Normative References . . . . . . . . . . . . . . . . . . . . 21
Gunter Expires January 4, 2020 [Page 2]
Internet-Draft Abbreviated Title July 2019
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction
Network maintenance notifications are currently sent by email with no
standard format or information. This becomes problematic
particularly for larger networks as emails need to be read and acted
upon manually. Common procedures associated with parsing these
emails include converting time zones, adding the information into a
calendar, and create tickets in preparation for the maintenance
event. As networks continue to grow it becomes unscalable to
manually parse and act upon every maintenance email. Missed or
misread maintenance emails can cause unexpected and potentially
business impacting downtime.
The automated processing of unstandardized maintenance emails is
arduous and unreliable due to the variety of formats from senders.
Developers must create and maintain a separate code base for each
maintenance email format. Regex and bit matching are commonly used
as parsing tools; any modification made to those templates could
cause machine parsing to fail.
This memo proposes the use of machine parseable metadata relating to
a network maintenance event by applying the experimental x-name
property of the Internet Calendering file specified in [RFC 5545]
[RFC5545]. The additional properties have constrained parameters,
simplifying automation efforts. Additionally, the iCalendar file
will still function as intended with calendar scheduling. Having an
iCalendar attachment present in a maintenance notifications reduces
load and mistakes for operators without automation present.
Currently, the advocates and subject matter experts are Todd Parker,
Eric Cables Shane Mountain, Steven Brudenell, and Ryan Gunter.
This convention has been proposed and received positive feedback from
many industry vendors, some of whom have already adopted this
standard and placed it into production for their customers.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC 2119] [RFC2119].
Gunter Expires January 4, 2020 [Page 3]
Internet-Draft Abbreviated Title July 2019
2. Specification
2.1. Overview
The following sections will describe the necessary requirements for
an iCalendar file to meet the requirements setforth in this
convention. The x-name properties previously mentioned will be
introduced and covered in detail.
There are six x-name properties:
X-MAINTNOTE-PROVIDER
X-MAINTNOTE-ACCOUNT
X-MAINTNOTE-MAINTENANCE-ID
X-MAINTNOTE-OBJECT-ID
X-MAINTNOTE-IMPACT
X-MAINTNOTE-STATUS
2.2. iCalendar Object
Maintenance Notification information MUST be represented using the
iCalendar object as described in [RFC 5545] [RFC5545] section 3.4.
2.3. iCalendar Properties
Maintenance Notification information MUST be represented using the
iCalendar object as described in section 3.4.
+----------+-------------------+------------------------------------+
| Property | Presence Required | Comment |
+----------+-------------------+------------------------------------+
| VERSION | 1 | Required per [RFC 5545] [RFC5545] |
| PRODID | 1 | Required per [RFC 5545] [RFC5545] |
| METHOD | 0 or 1 | See Below |
+----------+-------------------+------------------------------------+
Table 1
2.3.1. Method Calendar Property
The METHOD Calendar Property MAY be included in Maintenance
Notification Calendar Objects. By default implementations SHOULD NOT
include the METHOD Calendar Property. Implementations MAY add the
Gunter Expires January 4, 2020 [Page 4]
Internet-Draft Abbreviated Title July 2019
METHOD Calendar Property when they intend for the iCalendar Object to
represent a scheduling transaction, with the value set to the desired
transaction method. For more information on the METHOD Calendar
Property, and other required fields depending on its value, see [RFC
5545] [RFC5545].
When an iCalendar Object represents a scheduling transaction, Human
facing Calendaring systems may attempt to process the transaction.
Experimentation has shown this to result in the addition of an event
to a calendar contained within the Calendaring system. The
desirability of this outcome will vary based on the recipient. For
example, it may be desirable for maintenance notifications to auto
populate to a shared calendar devoted to maintenances. It may not be
desirable for maintenance notifications to auto populate to personal
calendars. Providers SHOULD implement a way for recipients of their
maintenance notifications to determine individually if their
notifications will include the METHOD Calendar Property. Recipients
MAY need determine individually if their notifications will include
the METHOD Calendar Property. Recipients MAY need to perform some
level of pre-processing in order to ensure that maintenance
notifications do not interact with their Human Calendaring systems in
undesirable ways.
2.4. Event Component and Associated Properties
Maintenance Notification information MUST be represented using the
iCalendar Event Component as described in [RFC 5545] [RFC5545]
section 3.6.1. All of the following Properties MUST be included with
any iCalendar Event for it to be a properly formatted maintenance
notification. These properties are the minimum set required to
automate common processing and dispatching of maintenance
notifications. Implementors MAY include and/or parse other iCal
Properties, however the presence of other iCal Properties MUST NOT
conflict with the use of mandatory Properties listed below.
Gunter Expires January 4, 2020 [Page 5]
Internet-Draft Abbreviated Title July 2019
+-----------------------------+-------------------+-----------+
| Property | Presence Required | Comment |
+-----------------------------+-------------------+-----------+
| DTSTAMP | 1 | |
| DTSTART | 1 | |
| DTEND | 1 | |
| UID | 1 | |
| Summary | 1 | |
| Organizer | 1 | |
| Sequence | 1 | |
| X-MAINTENOTE-PROVIDER | 1 | See Below |
| X-MAINTENOTE-ACCOUNT | 1 | See Below |
| X-MAINTENOTE-MAINTENANCE-ID | 1 | See Below |
| X-MAINTENOTE-OBJECT-ID | 1 | See Below |
| X-MAINTENOTE-IMPACT | 1 | See Below |
| X-MAINTENOTE-STATUS | 0 or 1 | See Below |
+-----------------------------+-------------------+-----------+
Table 2
2.5. Descriptive Component Properties
The following properties extend iCalendar to specify additional
descriptive information specific to the maintenance notification use
case.Note that due to the status of this document as a NANOG BCOP,
these extensions fall under the non-standard properties class of
iCalendar properties defined in section 3.8.8.2 of [RFC 5545]
[RFC5545]. To avoid possible collision with other non-standard
properties, and in keeping with the suggested approach defined in
section 3.8.8.2 of [RFC 5545] [RFC5545], all properties defined in
this document have the prefix text "X-MAINTNOTE-" where "MAINTNOTE"
is the short text that identifies the common nature and purpose of
these extensions. Testing of the effect of adding non-standard
properties of this format with several consumers of iCalendar
formatted information has shown that these properties will be ignored
by consumers not configured to interpret them.
2.5.1. Provider
Propery Name: X-MAINTNOTE-PROVIDER
Purpose: This descriptive component property contains text that
identifies the provider of the service that is the subject of the
maintenance notification
Value Type: TEXT
Gunter Expires January 4, 2020 [Page 6]
Internet-Draft Abbreviated Title July 2019
Property Parameters: IANA, non-standard, and language property
parameters can be specified on this property.
Conformance: This property can be specified in "VEVENT" calendar
component.
Description: This field MUST contain text that identifies the
provider of the service that is the subject of the maintenance
notification. The text used SHOULD be chosen to ensure uniqueness,
such as by using the well known trademark of the provider or using a
registered string from a globally unique namespace (for example a
domain name associated with the provider, e.g. example.com).
Format Definition: This property is defined by the following
notation:
x-maintnote-provider = "X-MAINTNOTE-PROVIDER" *(";" icalparameter) ":" text CRLF
Example: The following example is of a provider descriptive component
property for the provider with the domain name example.com:
X-MAINTNOTE-PROVIDER:example.com
2.5.2. Account
Property Name: X-MAINTNOTE-ACCOUNT
Purpose: This descriptive component property contains text that
identifies an account associated with the service that is the subject
of the maintenance notification.
Value Type: TEXT
Property Parameters: IANA, non-standard, and language property
parameters can be specified on this property.
Conformance: This property can be specified in "VEVENT" calendar
component.
Description: This field MUST contain text that identifies an account
associated with the service that is the subject of the maintenance
notification.
Format Definition: This property is defined by the following
notation:
x-maintnote-account = "X-MAINTNOTE-ACCOUNT" *(";" icalparameter) ":" text CRLF
Gunter Expires January 4, 2020 [Page 7]
Internet-Draft Abbreviated Title July 2019
Example: The following example is of an account descriptive component
property:
X-MAINTNOTE-ACCOUNT:137.035999173
2.5.3. Maintenance ID
Property Name: X-MAINTNOTE-MAINTENANCE-ID
Purpose: This descriptive component property contains text that
uniquely identifies the maintenance that is the subject of the
notification.
Value Type: TEXT
Property Parameters: IANA, non-standard, and language property
parameters can be specified on this property.
Conformance: This property can be specified in "VEVENT" calendar
component.
Description: This field MUST contain text that uniquely identifies
the maintenance that is the subject of the notification from all
other unrelated notifications sent by the provider.
Format Definition: This property is defined by the following
notation:
x-maintnote-maintenance-id = "X-MAINTNOTE-MAINTENANCE-ID" *(";" icalparameter) ":"
text CRLF
Example: The following example is of an account descriptive component
property:
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
2.5.4. Object ID
Property Name: X-MAINTNOTE-OBJECT-ID
Purpose: This descriptive component property contains text that
uniquely identifies a service object that is within the scope of the
maintenance that is the subject of the notification.
Value Type: TEXT
Property Parameters: IANA, non-standard, and language property
parameters can be specified on this property.
Gunter Expires January 4, 2020 [Page 8]
Internet-Draft Abbreviated Title July 2019
Conformance: This property can be specified in "VEVENT" calendar
component.
Description: This field MUST contain text that uniquely identifies a
service object that is within the scope of the maintenance that is
the subject of the notification. The object identifier MUST
distinguish the referenced service object from all other unrelated
service objects of the provider. The consumer of the field SHOULD
use both the object identifier descriptive component property and the
provider descriptive component property to identify the service to
protect against object identifier namespace collisions across
providers. Multiple instances of this descriptive component MAY be
included simultaneously where the scope of a maintenance includes
multiple service objects.
Providers SHOULD choose a service object identifier which is most
descriptive for the service(s) under maintenance, and which best
enables automation by the recipient. In some cases, a unique (to the
service provider) identifier without any technical connection to the
service that is arranged at the time of initial service provisioning
and communicated to the recipient as the future identifier for the
service may be the best option. In other cases, some identifier
associated with the technical expression of the service may be the
best option. Identifiers that appear in both provider and recipient
technical configuration related to the service SHOULD be used
whenever possible; otherwise an identifier that appears in the
recipient technical configuration related to the service MAY be used.
In cases where the provider wishes to provide additional formatted
information beyond a single unique identifier, the Alternative Text
Representation property parameter defined in [RFC 5545] [RFC5545]
section 3.2.1 SHOULD be used to provide a URI where additional data
may be obtained. Any guidelines for the formatting of this external
information is outside of the scope of this standard, however the
authors recommend that the provider use a well known encoding method
such as JSON [RFC 7159] [RFC7159] and a naming standard for different
types of data commonly used for the service in question. One of the
examples below shows a query against the API for the popular
PeeringDB service that - when populated with valid parameters -
should return JSON formatted data for two networks' presences on a
public Internet exchange. This example shows one way of providing
additional formatted information for a particular use case,
specifically BGP peering on public Internet exchanges.
Format Definition: This property is defined by the following
notation:
x-maintnote-object-id = "X-MAINTNOTE-OBJECT-ID" *(";" icalparameter) ":" text CRLF
Gunter Expires January 4, 2020 [Page 9]
Internet-Draft Abbreviated Title July 2019
Example: The following are examples of service objects:
X-MAINTNOTE-OBJECT-ID:2718281828459
X-MAINTNOTE-OBJECT-ID;ALTREP="https://example.org/maintenance?
id=2718281828459":2718281828459
X-MAINTNOTE-OBJECT-ID;ALTREP="https://www.peeringdb.com/api/netixlan?
asn__in=64496,65536&ipaddr4__in=192.0.2.42,192.0.2.137":2718281828459
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-OBJECT-ID:vm-1054571726.region.example.com
X-MAINTNOTE-OBJECT-ID:2001:db8::d06:f00d
X-MAINTNOTE-OBJECT-ID:198.51.100.13
2.5.5. Impact
Property Name: X-MAINTNOTE-IMPACT
Purpose: This descriptive component property specifies the impact of
the maintenance to the services within its scope.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be
specified on this property. Conformance: This property can be
specified in "VEVENT" calendar component.
Description: The X-MAINTNOTE-IMPACT property type MUST be specified
on this property. This field may contain one of several labels that
describes the impact of the maintenance to the services within its
scope. The value "NO-IMPACT" indicates that there is no expected
impact to services in scope for the maintenance. The value "REDUCED-
REDUNDANCY" indicates that during the maintenance the services in
scope are expected to continue operating without any consumer visible
impact, however the services are without their normal level of
redundancy. While operating at a reduced level of redundancy,
failure of supporting infrastructure outside the scope of the
maintenance occurring concurrent to the maintenance may cause
consumer visible service impact. The value "DEGRADED" indicates that
negative impact to services in scope for the maintenance is expected,
however the maintenance will not result in a total service outage.
The value "OUTAGE" indicates that the services in scope of the
maintenance are expected to be completely out of service.
Implementors MAY create other property parameter values that better
describe their specific situations. The default value is "OUTAGE";
applications SHOULD treat x-name and iana-token values they don't
recognize the same way as they would the "OUTAGE" value.
Gunter Expires January 4, 2020 [Page 10]
Internet-Draft Abbreviated Title July 2019
Format Definition: This property is defined by the following
notation:
x-maintnote-impact = "X-MAINTNOTE-IMPACT" *(";" icalparameter) ":" impactvalue CRLF
+----------------------+--------------------------------------------+
| impactvalue | Comment |
+----------------------+--------------------------------------------+
| "NO-IMPACT" | |
| "REDUCED-REDUNDANCY" | |
| "DEGRADED" | |
| "OUTAGE" | |
| x-name | Some experimental impact property |
| | parameter value |
| iana-token | Some other IANA-registered impact property |
| | parameter value |
+----------------------+--------------------------------------------+
Table 3
Example: The following are examples of service objects:
X-MAINTNOTE-IMPACT:DEGRADED
2.5.6. Status
Property Name: X-MAINTNOTE-STATUS
Purpose: This property defines the overall status or confirmation for
the maintenance.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be
specified on this property.
Conformance: This property can be specified once in "VEVENT" calendar
components.
Description: The property is used by the "Organizer" to provide
information regarding the status of the maintenance event.
Format Definition: This property is defined by the following
notation:
x-maintnote-status = "X-MAINTNOTE-STATUS" statusparam ":" statusvalue CRLF
statusparam = *(";" other-param)
Gunter Expires January 4, 2020 [Page 11]
Internet-Draft Abbreviated Title July 2019
+--------------+----------------------------------------------------+
| statvalue | Comment |
+--------------+----------------------------------------------------+
| "TENTATIVE" | Indicates maintenance event is tentative |
| "CONFIRMED" | Indicates maintenance event is definite |
| "CANCELLED" | Indicates maintenance event was cancelled |
| "IN-PROCESS" | Indicates maintenance event is in process (e.g. |
| | open) |
| "COMPLETED" | Indicates maintenance event completed (e.g. |
| | closed) |
| x-name | Some experimental impact property parameter value |
| iana-token | Some other IANA-registered impact property |
| | parameter value |
+--------------+----------------------------------------------------+
Table 4
Example: The following is an example of this property for a "VEVENT"
calendar component:
X-MAINTNOTE-STATUS:TENTATIVE
3. Workflow
This section describes several workflows typical to maintenance
notifications. It describes the sequence of steps to produce and
consume properly formatted ical data extended as specified in this
document.
3.1. Initial Maintenance Notification
This workflow describes the actions required by the example provider
and example consumer for an initial maintenance notification.
3.1.1. Example Provider
The example provider determine that a maintenance on a network
element is required to avoid service disruption in the future. This
maintenance will result in the network element going out of service.
Their systems determine the impacted services provided by the network
element, and the list of accounts and consumer contacts associated
with those services. Their systems also generate a maintenance
identifier.
Using the above information, individual maintenance notifications are
generated for each consumer using existing processes. Automated
systems also generate iCal formatted attachments following the
standards described in this document. These iCal attachments include
Gunter Expires January 4, 2020 [Page 12]
Internet-Draft Abbreviated Title July 2019
the start and end timestamps for the proposed maintenance window
(DTSTART, DTEND), the same summary of the maintenance that was
included in the email summary for the notification (SUMMARY), the
same contact information included in the email notification
(ORGANIZER), the status of the maintenance as tentative since this is
a proposed window (X- MAINTNOTE-STATUS), the well known domain name
of the company (X-MAINTNOTE-PROVIDER), the maintenance identifier (X-
MAINTNOTE-MAINTENANCE-ID) and the worst case impact (X-MAINTNOTE-
IMPACT). Each consumer receives specific information relative to
their impacted service(s) in the following fields: X-MAINTNOTE-
ACCOUNT includes the consumer's account identifier, one or more
instances of X- MAINTNOTE-OBJECT-ID list the consumer's impacted
service(s).
To enable association of subsequent updates to these notifications,
the following values are tracked in the systems of the example
provider. A ical specific unique identifier for each notification
(UID), so that subsequent updates may be associated with the original
notification. A sequence number - initially zero - to serialize
updates in case they are received or processed out of order
(SEQUENCE).
3.1.2. Example Consumer
The example consumer receives the example provider's notification,
detects the presence of the ical attachment and routes it to a
program for processing. Values of relevance are then parsed. The
program examines a database to determine if a maintenance
notification with the same unique identifier as this notifications
been processed in the past. No entry corresponding to the unique
identifier is found. The lack of a matching entry in the database
indicates this is an initial notification, so the program opens a new
ticket in the consumer's ticketing system. This ticket is used to
track the maintenance. Because the maintenance may result in an
outage, the priority of the ticket is elevated. Because the
notification is tentative, the ticket is not assigned to the
remediation queue. The parsing program records the UID and sequence
number in a database along with an identifier for the created ticket.
This state will be used to update the ticket should any further
information be received from the vendor.
3.2. Updated Maintenance Notification Window
This workflow describes the actions required by the example provider
and example consumer for an updated maintenance notification window.
Gunter Expires January 4, 2020 [Page 13]
Internet-Draft Abbreviated Title July 2019
3.2.1. Example Provider
After reviewing feedback from affected consumers, the example
provider negotiates a new maintenance window acceptable to consumers.
The example provider's automated systems generate new maintenance
notifications using the same information as the initial maintenance
notification with several key fields modified. The start and end
timestamps for the proposed maintenance window (DTSTART, DTEND) are
updated to their new values. Of key importance is the use of the
same unique identifier value as the first message, to ensure that
consumers are able to associate this new notification with the
previous one. The sequence number (SEQUENCE) is incremented to one
so that this notification contains newer informationthan the initial
notification that preceded it. All other information is included as
it appeared in the initial notification.
3.2.2. Example Consumer
The example consumer receives the example provider's notification,
detects the presence of the ical attachment and routes it to a
program for processing. Values of relevance are then parsed. The
program examines a database to determine if a maintenance
notification with the same unique identifier as this notifications
been processed in the past. A match is found for the unique
identifier, and the sequence number in the current notification is
greater than the one in the database indicating that the current
notification contains updated information. The associated record
includes an identifier for a ticket in the consumer's ticketing
system. Given the current notification contains updates to previous
information, the program updates fields in the corresponding ticket
with values from the current notification. Thus the ticket is
updated to contain the new start and end timestamps. The program
notes that other key fields - such as the status of the notification
- have not changed in a way that requires any updates to the ticket.
3.3. Canceled Maintenance Notification Window
This workflow describes the actions required by the example provider
and example consumer for a canceled maintenance notification window.
3.3.1. Example Provider
After determining that a maintenance window is no longer needed, the
example provider cancels a previously announced maintenance window.
The example provider's automated systems generate new maintenance
notifications using the same information as the last maintenance
notification for this maintenance with several fields modified. Of
key importance is the use of the same unique identifier value as the
Gunter Expires January 4, 2020 [Page 14]
Internet-Draft Abbreviated Title July 2019
prior messages, to ensure that consumers are able to associate this
new notification with previous ones. The sequence number (SEQUENCE)
is incremented by one from the value used in the last messages, to
indicate that this notification contains newer information than the
notifications that preceded it. The maintenance status (X-MAINTNOTE-
STATUS) field is set to the value CANCELLED. All other information
is included as it appeared in the prior notification.
3.3.2. Example Consumer
The example consumer receives the example provider's notification,
detects the presence of the iCal attachment and routes it to a
program for processing. Values of relevance are then parsed. The
program examines a database to determine if a maintenance
notification with the same unique identifier as his notifications
been processed in the past. A match is found for the unique
identifier, and the sequence number in the current notification is
greater than the one in the database indicating that the current
notification contains updated information. The associated record
includes an identifier for a ticket in the consumer's ticketing
system. Given the current notification is that the maintenance
previously announced is cancelled, the program cancels the
corresponding ticket for the maintenance.
3.4. Open Maintenance Notification Window
This workflow describes the actions required by the example provider
and example consumer for an open maintenance notification window.
3.4.1. Example Provider
At the beginning of the scheduled maintenance window, the example
provider declares the announced maintenance window open and begins
work. The example provider's automated systems generate new
maintenance notifications using the same information as the last
maintenance notification for this maintenance with several fields
modified. Of key importance is the use of the same unique identifier
value as the prior messages, to ensure that consumers are able to
associate this new notification with previous ones. The sequence
number (SEQUENCE) is incremented by one from the value used in the
last messages, to indicate that this notification contains newer
information than the notifications that preceded it. The maintenance
status (X-MAINTNOTE-STATUS) field is set to the value IN-PROCESS.
With the exception of modifications to the textual description
stating that the maintenance window is open, all other information is
included as it appeared in the prior notifications.
Gunter Expires January 4, 2020 [Page 15]
Internet-Draft Abbreviated Title July 2019
3.4.2. Example Consumer
The example consumer receives the example provider's notification,
detects the presence of the iCal attachment and routes it to a
program for processing. Values of relevance are then parsed. The
program examines a database to determine if a maintenance
notification with the same unique identifier as this notifications
been processed in the past. A match is found for the unique
identifier, and the sequence number in the current notification is
greater than the one in the database indicating that the current
notification contains updated information. The associated record
includes an identifier for a ticket in the consumer's ticketing
system. Given the current notification is an update to the
maintenance previously announced maintenance window, the program
updates the ticket for the maintenance with the new textual
description and marks it as open.
3.5. Closed Maintenance Notification Window
This workflow describes the actions required by the example provider
and example consumer for a closed maintenance notification window.
3.5.1. Example Provider
At the end of the scheduled maintenance window, the example provider
confirms all work is complete, that all affected services have
returned to normal operation, then declares the announced maintenance
window closed. The example provider's automated systems generate new
maintenance notifications using the same information as the last
maintenance notification for this maintenance with several fields
modified. Of key importance is the use of the same unique identifier
value as the prior messages, to ensure that consumers are able to
associate this new notification with previous ones. The sequence
number (SEQUENCE) is incremented by one from the value used in the
last messages, to indicate that this notification contains newer
information than the notifications that preceded it. The maintenance
status (X-MAINTNOTE-STATUS) field is set to the value COMPLETED.
With the exception of modifications to the textual description
stating that the maintenance window is closed, all other information
is included as it appeared in the prior notifications.
3.5.2. Example Consumer
The example consumer receives the example provider's notification,
detects the presence of the iCal attachment and routes it to a
program for processing. Values of relevance are then parsed. The
program examines a database to determine if a maintenance
notification with the same unique identifier as this notifications
Gunter Expires January 4, 2020 [Page 16]
Internet-Draft Abbreviated Title July 2019
been processed in the past. A match is found for the unique
identifier, and the sequence number in the current notification is
greater than the one in the database indicating that the current
notification contains updated information. The associated record
includes an identifier for a ticket in the consumer's ticketing
system. Given the current notification is an update to the
maintenance previously announced maintenance window, the program
updates the ticket for the maintenance with the new textual
description and marks it as closed.
4. Examples
This section of the document provides example iCalendar formats as
described in this document.
4.1. Initial Maintenance Notification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Maint Note//https://github.com/maint-notification// BEGIN:VEVENT
SUMMARY:Maint Note Example
DTSTART;VALUE=DATE-TIME:20151010T080000Z
DTEND;VALUE=DATE-TIME:20151010T100000Z
DTSTAMP;VALUE=DATE-TIME:20151010T001000Z
UID:42
SEQUENCE:1
X-MAINTNOTE-PROVIDER:example.com
X-MAINTNOTE-ACCOUNT:137.035999173
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-IMPACT:NO-IMPACT
X-MAINTNOTE-STATUS:TENTATIVE
ORGANIZER;CN="Example NOC":mailto:noone@example.com
END:VEVENT
END:VCALENDAR
4.2. Updated Maintenance Notification
Gunter Expires January 4, 2020 [Page 17]
Internet-Draft Abbreviated Title July 2019
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Maint Note//https://github.com/maint-notification//
BEGIN:VEVENT
SUMMARY:Maint Note Example
DTSTART;VALUE=DATE-TIME:20151012T080000Z
DTEND;VALUE=DATE-TIME:20151012T100000Z
DTSTAMP;VALUE=DATE-TIME:20151012T001000Z
UID:42
SEQUENCE:2
X-MAINTNOTE-PROVIDER:example.com
X-MAINTNOTE-ACCOUNT:137.035999173
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-IMPACT:NO-IMPACT
X-MAINTNOTE-STATUS:CONFIRMED
ORGANIZER;CN="Example NOC":mailto:noone@example.com
END:VEVENT
END:VCALENDAR
4.3. Cancelled Maintenance Notification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Maint Note//https://github.com/maint-notification//
BEGIN:VEVENT
SUMMARY:Maint Note Example
DTSTART;VALUE=DATE-TIME:20151012T080000Z
DTEND;VALUE=DATE-TIME:20151012T100000Z
DTSTAMP;VALUE=DATE-TIME:20151012T001000Z
UID:42
SEQUENCE:3
X-MAINTNOTE-PROVIDER:example.com
X-MAINTNOTE-ACCOUNT:137.035999173
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-IMPACT:NO-IMPACT
X-MAINTNOTE-STATUS:CANCELLED
ORGANIZER;CN="Example NOC":mailto:noone@example.com
END:VEVENT
END:VCALENDAR
Gunter Expires January 4, 2020 [Page 18]
Internet-Draft Abbreviated Title July 2019
4.4. Open Maintenance Notification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Maint Note//https://github.com/maint-notification//
BEGIN:VEVENT
SUMMARY:Open - Maint Note Example
DTSTART;VALUE=DATE-TIME:20151012T080000Z
DTEND;VALUE=DATE-TIME:20151012T100000Z
DTSTAMP;VALUE=DATE-TIME:20151012T001000Z
UID:42
SEQUENCE:3
X-MAINTNOTE-PROVIDER:example.com
X-MAINTNOTE-ACCOUNT:137.035999173
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-IMPACT:NO-IMPACT
X-MAINTNOTE-STATUS:IN-PROCESS
ORGANIZER;CN="Example NOC":mailto:noone@example.com
END:VEVENT
END:VCALENDAR
4.5. Closed Maintenance Notification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Maint Note//https://github.com/maint-notification//
BEGIN:VEVENT
SUMMARY:Closed - Maint Note Example
DTSTART;VALUE=DATE-TIME:20151012T080000Z
DTEND;VALUE=DATE-TIME:20151012T100000Z
DTSTAMP;VALUE=DATE-TIME:20151012T001000Z
UID:42
SEQUENCE:4
X-MAINTNOTE-PROVIDER:example.com
X-MAINTNOTE-ACCOUNT:137.035999173
X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service
X-MAINTNOTE-IMPACT:NO-IMPACT
X-MAINTNOTE-STATUS: COMPLETED
ORGANIZER;CN="Example NOC":mailto:noone@example.com
END:VEVENT
END:VCALENDAR
Gunter Expires January 4, 2020 [Page 19]
Internet-Draft Abbreviated Title July 2019
5. Considerations
The following sections outlines Localization and Security
considerations.
5.1. Localization Considerations
Localization may be performed as needed by the implementors of this
document. English text used in the iCalendar data format [RFC 5545]
[RFC5545] or extensions described in this document may be converted
to local languages as required.
5.2. Security Considerations
Maintenance notifications are often used as an aid in the planning of
operational activities. Incorrect or undelivered maintenance
notification information could, if used or required to plan
operational activities, result in an operational problem. By
preventing the receipt or correct processing of maintenance
notifications, modifying or generating false maintenance
notifications, an attacker could negatively impact the operations of
targeted organizations.
It is a common practice to distribute maintenance notifications via
Email. Email messages are not immune to disruption, modification or
fabrication by an attacker. To mitigate possible attacks we
recommend the use of existing techniques to authenticate maintenance
notifications distributed via email. For example, OpenPGP [RFC 3156]
[RFC3156]could be used to sign a maintenance notification email and
include a message integrity check covering the contents of the email.
This technique is applied to the contents of the email, which would
include the extended iCal data specified in this document. This
method, where implemented by both the generator and receiver of a
maintenance notification, would prevent the fabrication or
modification of maintenance notification emails. Use of OpenPGP to
sign messages would only benefit those messages that were delivered
to the receiver; it does not address situations where maintenance
notifications are disrupted before they can be delivered to the
recipient.
As an alternative to pushing maintenance notifications from
generators to receivers via email distribution, receivers could pull
maintenance notification information from generators via the CalDAV
protocol [RFC 4791] [RFC4791]. Authenticity and integrity of this
communications channel could be provided by accessing CalDAV end
points via TLS [RFC 5246] [RFC5246]. CalDAV is simply a means to
publish iCal formatted content, in this case the extended iCal data
specified in this document.
Gunter Expires January 4, 2020 [Page 20]
Internet-Draft Abbreviated Title July 2019
Implementors of this convention SHOULD ensure the correctness of all
information exchanged when taking automated action based on what they
receive. Comparison against out of band sources of information to
confirm the correctness of information received MAY be used to detect
incorrect information and prevent acting based on it.
6. IANA Considerations
This memo includes no request to IANA.
7. Acknowledgements
The authors of this document would like to thank the original authors
and advocates of the BCOP draft for their efforts to contributing to
this maintenance notifcation improvement. Their initial design and
creativity building this convention is sincerely appreciated.
To give credit where it's due, this is an excerpt from the original
draft: "At NANOG 60, Randy Neals floated the idea of improving
maintenance notifications to make it easier to write programs to
consume them. Noting a willingness on the part of several attendees
(Peter Hoose, Erik Klavon, Dave McGaugh, Paul Schultz, and Joel
Wride) to collaborate on drafting standards for machine parsable
maintenance notifications, Randy organized the initial effort. Randy
held a couple conference calls and worked with the group to draft a
rough charter. Unfortunately Randy had to withdraw from the role of
shepherd due to competing priorities. Erik picked up where Randy
left off, and - thanks to the advocacy of the other original
participants - began working with Francisco Hidalgo, Tylar Keese, and
Tj Trask on the project."
8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3156] Elkins, M., Del Torto, D., Levien, R., and T. Roessler,
"MIME Security with OpenPGP", RFC 3156,
DOI 10.17487/RFC3156, August 2001,
<https://www.rfc-editor.org/info/rfc3156>.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
DOI 10.17487/RFC4791, March 2007,
<https://www.rfc-editor.org/info/rfc4791>.
Gunter Expires January 4, 2020 [Page 21]
Internet-Draft Abbreviated Title July 2019
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/info/rfc7159>.
Author's Address
Ryan Gunter (editor)
Twitch
350 Bush St
San Francisco, CA 94104
USA
Phone: +1 415 568 7607
Email: rgunter@twitch.tv
Gunter Expires January 4, 2020 [Page 22]
