idnits 2.17.1 draft-gunter-calext-maintenance-notifications-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 11 characters in excess of 72. ** The abstract seems to contain references ([RFC5545]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 3, 2019) is 1749 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'RFC 5545' is mentioned on line 877, but not defined == Missing Reference: 'RFC 2119' is mentioned on line 139, but not defined == Missing Reference: 'RFC 7159' is mentioned on line 400, but not defined ** Obsolete undefined reference: RFC 7159 (Obsoleted by RFC 8259) == Missing Reference: 'RFC 3156' is mentioned on line 896, but not defined == Missing Reference: 'RFC 4791' is mentioned on line 912, but not defined == Missing Reference: 'RFC 5246' is mentioned on line 914, but not defined ** Obsolete undefined reference: RFC 5246 (Obsoleted by RFC 8446) == Unused Reference: 'RFC3156' is defined on line 956, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 6 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendaring Extensions R. Gunter, Ed. 3 Internet-Draft Twitch 4 Intended status: Experimental July 3, 2019 5 Expires: January 4, 2020 7 Maintenance Notification Improvements Using iCalendar 8 draft-gunter-calext-maintenance-notifications-00 10 Abstract 12 This document proposes a maintenance notification convention that 13 requires the use an iCalendar file augmented with standarzied and 14 machine parseable metadata. The metadata is constructed by using the 15 x-name property in the iCalendar file in compliance with [RFC 5545] 16 [RFC5545]. This specification substantially reduces automation 17 efforts, and still provides easy calendaring for manual processing. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 4, 2020. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.2. iCalendar Object . . . . . . . . . . . . . . . . . . . . 4 58 2.3. iCalendar Properties . . . . . . . . . . . . . . . . . . 4 59 2.3.1. Method Calendar Property . . . . . . . . . . . . . . 4 60 2.4. Event Component and Associated Properties . . . . . . . . 5 61 2.5. Descriptive Component Properties . . . . . . . . . . . . 6 62 2.5.1. Provider . . . . . . . . . . . . . . . . . . . . . . 6 63 2.5.2. Account . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.5.3. Maintenance ID . . . . . . . . . . . . . . . . . . . 8 65 2.5.4. Object ID . . . . . . . . . . . . . . . . . . . . . . 8 66 2.5.5. Impact . . . . . . . . . . . . . . . . . . . . . . . 10 67 2.5.6. Status . . . . . . . . . . . . . . . . . . . . . . . 11 68 3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 3.1. Initial Maintenance Notification . . . . . . . . . . . . 12 70 3.1.1. Example Provider . . . . . . . . . . . . . . . . . . 12 71 3.1.2. Example Consumer . . . . . . . . . . . . . . . . . . 13 72 3.2. Updated Maintenance Notification Window . . . . . . . . . 13 73 3.2.1. Example Provider . . . . . . . . . . . . . . . . . . 14 74 3.2.2. Example Consumer . . . . . . . . . . . . . . . . . . 14 75 3.3. Canceled Maintenance Notification Window . . . . . . . . 14 76 3.3.1. Example Provider . . . . . . . . . . . . . . . . . . 14 77 3.3.2. Example Consumer . . . . . . . . . . . . . . . . . . 15 78 3.4. Open Maintenance Notification Window . . . . . . . . . . 15 79 3.4.1. Example Provider . . . . . . . . . . . . . . . . . . 15 80 3.4.2. Example Consumer . . . . . . . . . . . . . . . . . . 16 81 3.5. Closed Maintenance Notification Window . . . . . . . . . 16 82 3.5.1. Example Provider . . . . . . . . . . . . . . . . . . 16 83 3.5.2. Example Consumer . . . . . . . . . . . . . . . . . . 16 84 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17 85 4.1. Initial Maintenance Notification . . . . . . . . . . . . 17 86 4.2. Updated Maintenance Notification . . . . . . . . . . . . 17 87 4.3. Cancelled Maintenance Notification . . . . . . . . . . . 18 88 4.4. Open Maintenance Notification . . . . . . . . . . . . . . 19 89 4.5. Closed Maintenance Notification . . . . . . . . . . . . . 19 90 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 20 91 5.1. Localization Considerations . . . . . . . . . . . . . . . 20 92 5.2. Security Considerations . . . . . . . . . . . . . . . . . 20 93 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 94 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 95 8. Normative References . . . . . . . . . . . . . . . . . . . . 21 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 98 1. Introduction 100 Network maintenance notifications are currently sent by email with no 101 standard format or information. This becomes problematic 102 particularly for larger networks as emails need to be read and acted 103 upon manually. Common procedures associated with parsing these 104 emails include converting time zones, adding the information into a 105 calendar, and create tickets in preparation for the maintenance 106 event. As networks continue to grow it becomes unscalable to 107 manually parse and act upon every maintenance email. Missed or 108 misread maintenance emails can cause unexpected and potentially 109 business impacting downtime. 111 The automated processing of unstandardized maintenance emails is 112 arduous and unreliable due to the variety of formats from senders. 113 Developers must create and maintain a separate code base for each 114 maintenance email format. Regex and bit matching are commonly used 115 as parsing tools; any modification made to those templates could 116 cause machine parsing to fail. 118 This memo proposes the use of machine parseable metadata relating to 119 a network maintenance event by applying the experimental x-name 120 property of the Internet Calendering file specified in [RFC 5545] 121 [RFC5545]. The additional properties have constrained parameters, 122 simplifying automation efforts. Additionally, the iCalendar file 123 will still function as intended with calendar scheduling. Having an 124 iCalendar attachment present in a maintenance notifications reduces 125 load and mistakes for operators without automation present. 127 Currently, the advocates and subject matter experts are Todd Parker, 128 Eric Cables Shane Mountain, Steven Brudenell, and Ryan Gunter. 130 This convention has been proposed and received positive feedback from 131 many industry vendors, some of whom have already adopted this 132 standard and placed it into production for their customers. 134 1.1. Requirements Language 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 138 document are to be interpreted as described in [RFC 2119] [RFC2119]. 140 2. Specification 142 2.1. Overview 144 The following sections will describe the necessary requirements for 145 an iCalendar file to meet the requirements setforth in this 146 convention. The x-name properties previously mentioned will be 147 introduced and covered in detail. 149 There are six x-name properties: 151 X-MAINTNOTE-PROVIDER 153 X-MAINTNOTE-ACCOUNT 155 X-MAINTNOTE-MAINTENANCE-ID 157 X-MAINTNOTE-OBJECT-ID 159 X-MAINTNOTE-IMPACT 161 X-MAINTNOTE-STATUS 163 2.2. iCalendar Object 165 Maintenance Notification information MUST be represented using the 166 iCalendar object as described in [RFC 5545] [RFC5545] section 3.4. 168 2.3. iCalendar Properties 170 Maintenance Notification information MUST be represented using the 171 iCalendar object as described in section 3.4. 173 +----------+-------------------+------------------------------------+ 174 | Property | Presence Required | Comment | 175 +----------+-------------------+------------------------------------+ 176 | VERSION | 1 | Required per [RFC 5545] [RFC5545] | 177 | PRODID | 1 | Required per [RFC 5545] [RFC5545] | 178 | METHOD | 0 or 1 | See Below | 179 +----------+-------------------+------------------------------------+ 181 Table 1 183 2.3.1. Method Calendar Property 185 The METHOD Calendar Property MAY be included in Maintenance 186 Notification Calendar Objects. By default implementations SHOULD NOT 187 include the METHOD Calendar Property. Implementations MAY add the 188 METHOD Calendar Property when they intend for the iCalendar Object to 189 represent a scheduling transaction, with the value set to the desired 190 transaction method. For more information on the METHOD Calendar 191 Property, and other required fields depending on its value, see [RFC 192 5545] [RFC5545]. 194 When an iCalendar Object represents a scheduling transaction, Human 195 facing Calendaring systems may attempt to process the transaction. 196 Experimentation has shown this to result in the addition of an event 197 to a calendar contained within the Calendaring system. The 198 desirability of this outcome will vary based on the recipient. For 199 example, it may be desirable for maintenance notifications to auto 200 populate to a shared calendar devoted to maintenances. It may not be 201 desirable for maintenance notifications to auto populate to personal 202 calendars. Providers SHOULD implement a way for recipients of their 203 maintenance notifications to determine individually if their 204 notifications will include the METHOD Calendar Property. Recipients 205 MAY need determine individually if their notifications will include 206 the METHOD Calendar Property. Recipients MAY need to perform some 207 level of pre-processing in order to ensure that maintenance 208 notifications do not interact with their Human Calendaring systems in 209 undesirable ways. 211 2.4. Event Component and Associated Properties 213 Maintenance Notification information MUST be represented using the 214 iCalendar Event Component as described in [RFC 5545] [RFC5545] 215 section 3.6.1. All of the following Properties MUST be included with 216 any iCalendar Event for it to be a properly formatted maintenance 217 notification. These properties are the minimum set required to 218 automate common processing and dispatching of maintenance 219 notifications. Implementors MAY include and/or parse other iCal 220 Properties, however the presence of other iCal Properties MUST NOT 221 conflict with the use of mandatory Properties listed below. 223 +-----------------------------+-------------------+-----------+ 224 | Property | Presence Required | Comment | 225 +-----------------------------+-------------------+-----------+ 226 | DTSTAMP | 1 | | 227 | DTSTART | 1 | | 228 | DTEND | 1 | | 229 | UID | 1 | | 230 | Summary | 1 | | 231 | Organizer | 1 | | 232 | Sequence | 1 | | 233 | X-MAINTENOTE-PROVIDER | 1 | See Below | 234 | X-MAINTENOTE-ACCOUNT | 1 | See Below | 235 | X-MAINTENOTE-MAINTENANCE-ID | 1 | See Below | 236 | X-MAINTENOTE-OBJECT-ID | 1 | See Below | 237 | X-MAINTENOTE-IMPACT | 1 | See Below | 238 | X-MAINTENOTE-STATUS | 0 or 1 | See Below | 239 +-----------------------------+-------------------+-----------+ 241 Table 2 243 2.5. Descriptive Component Properties 245 The following properties extend iCalendar to specify additional 246 descriptive information specific to the maintenance notification use 247 case.Note that due to the status of this document as a NANOG BCOP, 248 these extensions fall under the non-standard properties class of 249 iCalendar properties defined in section 3.8.8.2 of [RFC 5545] 250 [RFC5545]. To avoid possible collision with other non-standard 251 properties, and in keeping with the suggested approach defined in 252 section 3.8.8.2 of [RFC 5545] [RFC5545], all properties defined in 253 this document have the prefix text "X-MAINTNOTE-" where "MAINTNOTE" 254 is the short text that identifies the common nature and purpose of 255 these extensions. Testing of the effect of adding non-standard 256 properties of this format with several consumers of iCalendar 257 formatted information has shown that these properties will be ignored 258 by consumers not configured to interpret them. 260 2.5.1. Provider 262 Propery Name: X-MAINTNOTE-PROVIDER 264 Purpose: This descriptive component property contains text that 265 identifies the provider of the service that is the subject of the 266 maintenance notification 268 Value Type: TEXT 269 Property Parameters: IANA, non-standard, and language property 270 parameters can be specified on this property. 272 Conformance: This property can be specified in "VEVENT" calendar 273 component. 275 Description: This field MUST contain text that identifies the 276 provider of the service that is the subject of the maintenance 277 notification. The text used SHOULD be chosen to ensure uniqueness, 278 such as by using the well known trademark of the provider or using a 279 registered string from a globally unique namespace (for example a 280 domain name associated with the provider, e.g. example.com). 282 Format Definition: This property is defined by the following 283 notation: 285 x-maintnote-provider = "X-MAINTNOTE-PROVIDER" *(";" icalparameter) ":" text CRLF 287 Example: The following example is of a provider descriptive component 288 property for the provider with the domain name example.com: 290 X-MAINTNOTE-PROVIDER:example.com 292 2.5.2. Account 294 Property Name: X-MAINTNOTE-ACCOUNT 296 Purpose: This descriptive component property contains text that 297 identifies an account associated with the service that is the subject 298 of the maintenance notification. 300 Value Type: TEXT 302 Property Parameters: IANA, non-standard, and language property 303 parameters can be specified on this property. 305 Conformance: This property can be specified in "VEVENT" calendar 306 component. 308 Description: This field MUST contain text that identifies an account 309 associated with the service that is the subject of the maintenance 310 notification. 312 Format Definition: This property is defined by the following 313 notation: 315 x-maintnote-account = "X-MAINTNOTE-ACCOUNT" *(";" icalparameter) ":" text CRLF 316 Example: The following example is of an account descriptive component 317 property: 319 X-MAINTNOTE-ACCOUNT:137.035999173 321 2.5.3. Maintenance ID 323 Property Name: X-MAINTNOTE-MAINTENANCE-ID 325 Purpose: This descriptive component property contains text that 326 uniquely identifies the maintenance that is the subject of the 327 notification. 329 Value Type: TEXT 331 Property Parameters: IANA, non-standard, and language property 332 parameters can be specified on this property. 334 Conformance: This property can be specified in "VEVENT" calendar 335 component. 337 Description: This field MUST contain text that uniquely identifies 338 the maintenance that is the subject of the notification from all 339 other unrelated notifications sent by the provider. 341 Format Definition: This property is defined by the following 342 notation: 344 x-maintnote-maintenance-id = "X-MAINTNOTE-MAINTENANCE-ID" *(";" icalparameter) ":" 345 text CRLF 347 Example: The following example is of an account descriptive component 348 property: 350 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 352 2.5.4. Object ID 354 Property Name: X-MAINTNOTE-OBJECT-ID 356 Purpose: This descriptive component property contains text that 357 uniquely identifies a service object that is within the scope of the 358 maintenance that is the subject of the notification. 360 Value Type: TEXT 362 Property Parameters: IANA, non-standard, and language property 363 parameters can be specified on this property. 365 Conformance: This property can be specified in "VEVENT" calendar 366 component. 368 Description: This field MUST contain text that uniquely identifies a 369 service object that is within the scope of the maintenance that is 370 the subject of the notification. The object identifier MUST 371 distinguish the referenced service object from all other unrelated 372 service objects of the provider. The consumer of the field SHOULD 373 use both the object identifier descriptive component property and the 374 provider descriptive component property to identify the service to 375 protect against object identifier namespace collisions across 376 providers. Multiple instances of this descriptive component MAY be 377 included simultaneously where the scope of a maintenance includes 378 multiple service objects. 380 Providers SHOULD choose a service object identifier which is most 381 descriptive for the service(s) under maintenance, and which best 382 enables automation by the recipient. In some cases, a unique (to the 383 service provider) identifier without any technical connection to the 384 service that is arranged at the time of initial service provisioning 385 and communicated to the recipient as the future identifier for the 386 service may be the best option. In other cases, some identifier 387 associated with the technical expression of the service may be the 388 best option. Identifiers that appear in both provider and recipient 389 technical configuration related to the service SHOULD be used 390 whenever possible; otherwise an identifier that appears in the 391 recipient technical configuration related to the service MAY be used. 393 In cases where the provider wishes to provide additional formatted 394 information beyond a single unique identifier, the Alternative Text 395 Representation property parameter defined in [RFC 5545] [RFC5545] 396 section 3.2.1 SHOULD be used to provide a URI where additional data 397 may be obtained. Any guidelines for the formatting of this external 398 information is outside of the scope of this standard, however the 399 authors recommend that the provider use a well known encoding method 400 such as JSON [RFC 7159] [RFC7159] and a naming standard for different 401 types of data commonly used for the service in question. One of the 402 examples below shows a query against the API for the popular 403 PeeringDB service that - when populated with valid parameters - 404 should return JSON formatted data for two networks' presences on a 405 public Internet exchange. This example shows one way of providing 406 additional formatted information for a particular use case, 407 specifically BGP peering on public Internet exchanges. 409 Format Definition: This property is defined by the following 410 notation: 412 x-maintnote-object-id = "X-MAINTNOTE-OBJECT-ID" *(";" icalparameter) ":" text CRLF 413 Example: The following are examples of service objects: 415 X-MAINTNOTE-OBJECT-ID:2718281828459 417 X-MAINTNOTE-OBJECT-ID;ALTREP="https://example.org/maintenance? 418 id=2718281828459":2718281828459 420 X-MAINTNOTE-OBJECT-ID;ALTREP="https://www.peeringdb.com/api/netixlan? 421 asn__in=64496,65536&ipaddr4__in=192.0.2.42,192.0.2.137":2718281828459 423 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 424 X-MAINTNOTE-OBJECT-ID:vm-1054571726.region.example.com 425 X-MAINTNOTE-OBJECT-ID:2001:db8::d06:f00d 426 X-MAINTNOTE-OBJECT-ID:198.51.100.13 428 2.5.5. Impact 430 Property Name: X-MAINTNOTE-IMPACT 432 Purpose: This descriptive component property specifies the impact of 433 the maintenance to the services within its scope. 435 Value Type: TEXT 437 Property Parameters: IANA and non-standard property parameters can be 438 specified on this property. Conformance: This property can be 439 specified in "VEVENT" calendar component. 441 Description: The X-MAINTNOTE-IMPACT property type MUST be specified 442 on this property. This field may contain one of several labels that 443 describes the impact of the maintenance to the services within its 444 scope. The value "NO-IMPACT" indicates that there is no expected 445 impact to services in scope for the maintenance. The value "REDUCED- 446 REDUNDANCY" indicates that during the maintenance the services in 447 scope are expected to continue operating without any consumer visible 448 impact, however the services are without their normal level of 449 redundancy. While operating at a reduced level of redundancy, 450 failure of supporting infrastructure outside the scope of the 451 maintenance occurring concurrent to the maintenance may cause 452 consumer visible service impact. The value "DEGRADED" indicates that 453 negative impact to services in scope for the maintenance is expected, 454 however the maintenance will not result in a total service outage. 455 The value "OUTAGE" indicates that the services in scope of the 456 maintenance are expected to be completely out of service. 457 Implementors MAY create other property parameter values that better 458 describe their specific situations. The default value is "OUTAGE"; 459 applications SHOULD treat x-name and iana-token values they don't 460 recognize the same way as they would the "OUTAGE" value. 462 Format Definition: This property is defined by the following 463 notation: 465 x-maintnote-impact = "X-MAINTNOTE-IMPACT" *(";" icalparameter) ":" impactvalue CRLF 467 +----------------------+--------------------------------------------+ 468 | impactvalue | Comment | 469 +----------------------+--------------------------------------------+ 470 | "NO-IMPACT" | | 471 | "REDUCED-REDUNDANCY" | | 472 | "DEGRADED" | | 473 | "OUTAGE" | | 474 | x-name | Some experimental impact property | 475 | | parameter value | 476 | iana-token | Some other IANA-registered impact property | 477 | | parameter value | 478 +----------------------+--------------------------------------------+ 480 Table 3 482 Example: The following are examples of service objects: 484 X-MAINTNOTE-IMPACT:DEGRADED 486 2.5.6. Status 488 Property Name: X-MAINTNOTE-STATUS 490 Purpose: This property defines the overall status or confirmation for 491 the maintenance. 493 Value Type: TEXT 495 Property Parameters: IANA and non-standard property parameters can be 496 specified on this property. 498 Conformance: This property can be specified once in "VEVENT" calendar 499 components. 501 Description: The property is used by the "Organizer" to provide 502 information regarding the status of the maintenance event. 504 Format Definition: This property is defined by the following 505 notation: 507 x-maintnote-status = "X-MAINTNOTE-STATUS" statusparam ":" statusvalue CRLF 508 statusparam = *(";" other-param) 509 +--------------+----------------------------------------------------+ 510 | statvalue | Comment | 511 +--------------+----------------------------------------------------+ 512 | "TENTATIVE" | Indicates maintenance event is tentative | 513 | "CONFIRMED" | Indicates maintenance event is definite | 514 | "CANCELLED" | Indicates maintenance event was cancelled | 515 | "IN-PROCESS" | Indicates maintenance event is in process (e.g. | 516 | | open) | 517 | "COMPLETED" | Indicates maintenance event completed (e.g. | 518 | | closed) | 519 | x-name | Some experimental impact property parameter value | 520 | iana-token | Some other IANA-registered impact property | 521 | | parameter value | 522 +--------------+----------------------------------------------------+ 524 Table 4 526 Example: The following is an example of this property for a "VEVENT" 527 calendar component: 529 X-MAINTNOTE-STATUS:TENTATIVE 531 3. Workflow 533 This section describes several workflows typical to maintenance 534 notifications. It describes the sequence of steps to produce and 535 consume properly formatted ical data extended as specified in this 536 document. 538 3.1. Initial Maintenance Notification 540 This workflow describes the actions required by the example provider 541 and example consumer for an initial maintenance notification. 543 3.1.1. Example Provider 545 The example provider determine that a maintenance on a network 546 element is required to avoid service disruption in the future. This 547 maintenance will result in the network element going out of service. 548 Their systems determine the impacted services provided by the network 549 element, and the list of accounts and consumer contacts associated 550 with those services. Their systems also generate a maintenance 551 identifier. 553 Using the above information, individual maintenance notifications are 554 generated for each consumer using existing processes. Automated 555 systems also generate iCal formatted attachments following the 556 standards described in this document. These iCal attachments include 557 the start and end timestamps for the proposed maintenance window 558 (DTSTART, DTEND), the same summary of the maintenance that was 559 included in the email summary for the notification (SUMMARY), the 560 same contact information included in the email notification 561 (ORGANIZER), the status of the maintenance as tentative since this is 562 a proposed window (X- MAINTNOTE-STATUS), the well known domain name 563 of the company (X-MAINTNOTE-PROVIDER), the maintenance identifier (X- 564 MAINTNOTE-MAINTENANCE-ID) and the worst case impact (X-MAINTNOTE- 565 IMPACT). Each consumer receives specific information relative to 566 their impacted service(s) in the following fields: X-MAINTNOTE- 567 ACCOUNT includes the consumer's account identifier, one or more 568 instances of X- MAINTNOTE-OBJECT-ID list the consumer's impacted 569 service(s). 571 To enable association of subsequent updates to these notifications, 572 the following values are tracked in the systems of the example 573 provider. A ical specific unique identifier for each notification 574 (UID), so that subsequent updates may be associated with the original 575 notification. A sequence number - initially zero - to serialize 576 updates in case they are received or processed out of order 577 (SEQUENCE). 579 3.1.2. Example Consumer 581 The example consumer receives the example provider's notification, 582 detects the presence of the ical attachment and routes it to a 583 program for processing. Values of relevance are then parsed. The 584 program examines a database to determine if a maintenance 585 notification with the same unique identifier as this notifications 586 been processed in the past. No entry corresponding to the unique 587 identifier is found. The lack of a matching entry in the database 588 indicates this is an initial notification, so the program opens a new 589 ticket in the consumer's ticketing system. This ticket is used to 590 track the maintenance. Because the maintenance may result in an 591 outage, the priority of the ticket is elevated. Because the 592 notification is tentative, the ticket is not assigned to the 593 remediation queue. The parsing program records the UID and sequence 594 number in a database along with an identifier for the created ticket. 595 This state will be used to update the ticket should any further 596 information be received from the vendor. 598 3.2. Updated Maintenance Notification Window 600 This workflow describes the actions required by the example provider 601 and example consumer for an updated maintenance notification window. 603 3.2.1. Example Provider 605 After reviewing feedback from affected consumers, the example 606 provider negotiates a new maintenance window acceptable to consumers. 607 The example provider's automated systems generate new maintenance 608 notifications using the same information as the initial maintenance 609 notification with several key fields modified. The start and end 610 timestamps for the proposed maintenance window (DTSTART, DTEND) are 611 updated to their new values. Of key importance is the use of the 612 same unique identifier value as the first message, to ensure that 613 consumers are able to associate this new notification with the 614 previous one. The sequence number (SEQUENCE) is incremented to one 615 so that this notification contains newer informationthan the initial 616 notification that preceded it. All other information is included as 617 it appeared in the initial notification. 619 3.2.2. Example Consumer 621 The example consumer receives the example provider's notification, 622 detects the presence of the ical attachment and routes it to a 623 program for processing. Values of relevance are then parsed. The 624 program examines a database to determine if a maintenance 625 notification with the same unique identifier as this notifications 626 been processed in the past. A match is found for the unique 627 identifier, and the sequence number in the current notification is 628 greater than the one in the database indicating that the current 629 notification contains updated information. The associated record 630 includes an identifier for a ticket in the consumer's ticketing 631 system. Given the current notification contains updates to previous 632 information, the program updates fields in the corresponding ticket 633 with values from the current notification. Thus the ticket is 634 updated to contain the new start and end timestamps. The program 635 notes that other key fields - such as the status of the notification 636 - have not changed in a way that requires any updates to the ticket. 638 3.3. Canceled Maintenance Notification Window 640 This workflow describes the actions required by the example provider 641 and example consumer for a canceled maintenance notification window. 643 3.3.1. Example Provider 645 After determining that a maintenance window is no longer needed, the 646 example provider cancels a previously announced maintenance window. 647 The example provider's automated systems generate new maintenance 648 notifications using the same information as the last maintenance 649 notification for this maintenance with several fields modified. Of 650 key importance is the use of the same unique identifier value as the 651 prior messages, to ensure that consumers are able to associate this 652 new notification with previous ones. The sequence number (SEQUENCE) 653 is incremented by one from the value used in the last messages, to 654 indicate that this notification contains newer information than the 655 notifications that preceded it. The maintenance status (X-MAINTNOTE- 656 STATUS) field is set to the value CANCELLED. All other information 657 is included as it appeared in the prior notification. 659 3.3.2. Example Consumer 661 The example consumer receives the example provider's notification, 662 detects the presence of the iCal attachment and routes it to a 663 program for processing. Values of relevance are then parsed. The 664 program examines a database to determine if a maintenance 665 notification with the same unique identifier as his notifications 666 been processed in the past. A match is found for the unique 667 identifier, and the sequence number in the current notification is 668 greater than the one in the database indicating that the current 669 notification contains updated information. The associated record 670 includes an identifier for a ticket in the consumer's ticketing 671 system. Given the current notification is that the maintenance 672 previously announced is cancelled, the program cancels the 673 corresponding ticket for the maintenance. 675 3.4. Open Maintenance Notification Window 677 This workflow describes the actions required by the example provider 678 and example consumer for an open maintenance notification window. 680 3.4.1. Example Provider 682 At the beginning of the scheduled maintenance window, the example 683 provider declares the announced maintenance window open and begins 684 work. The example provider's automated systems generate new 685 maintenance notifications using the same information as the last 686 maintenance notification for this maintenance with several fields 687 modified. Of key importance is the use of the same unique identifier 688 value as the prior messages, to ensure that consumers are able to 689 associate this new notification with previous ones. The sequence 690 number (SEQUENCE) is incremented by one from the value used in the 691 last messages, to indicate that this notification contains newer 692 information than the notifications that preceded it. The maintenance 693 status (X-MAINTNOTE-STATUS) field is set to the value IN-PROCESS. 694 With the exception of modifications to the textual description 695 stating that the maintenance window is open, all other information is 696 included as it appeared in the prior notifications. 698 3.4.2. Example Consumer 700 The example consumer receives the example provider's notification, 701 detects the presence of the iCal attachment and routes it to a 702 program for processing. Values of relevance are then parsed. The 703 program examines a database to determine if a maintenance 704 notification with the same unique identifier as this notifications 705 been processed in the past. A match is found for the unique 706 identifier, and the sequence number in the current notification is 707 greater than the one in the database indicating that the current 708 notification contains updated information. The associated record 709 includes an identifier for a ticket in the consumer's ticketing 710 system. Given the current notification is an update to the 711 maintenance previously announced maintenance window, the program 712 updates the ticket for the maintenance with the new textual 713 description and marks it as open. 715 3.5. Closed Maintenance Notification Window 717 This workflow describes the actions required by the example provider 718 and example consumer for a closed maintenance notification window. 720 3.5.1. Example Provider 722 At the end of the scheduled maintenance window, the example provider 723 confirms all work is complete, that all affected services have 724 returned to normal operation, then declares the announced maintenance 725 window closed. The example provider's automated systems generate new 726 maintenance notifications using the same information as the last 727 maintenance notification for this maintenance with several fields 728 modified. Of key importance is the use of the same unique identifier 729 value as the prior messages, to ensure that consumers are able to 730 associate this new notification with previous ones. The sequence 731 number (SEQUENCE) is incremented by one from the value used in the 732 last messages, to indicate that this notification contains newer 733 information than the notifications that preceded it. The maintenance 734 status (X-MAINTNOTE-STATUS) field is set to the value COMPLETED. 735 With the exception of modifications to the textual description 736 stating that the maintenance window is closed, all other information 737 is included as it appeared in the prior notifications. 739 3.5.2. Example Consumer 741 The example consumer receives the example provider's notification, 742 detects the presence of the iCal attachment and routes it to a 743 program for processing. Values of relevance are then parsed. The 744 program examines a database to determine if a maintenance 745 notification with the same unique identifier as this notifications 746 been processed in the past. A match is found for the unique 747 identifier, and the sequence number in the current notification is 748 greater than the one in the database indicating that the current 749 notification contains updated information. The associated record 750 includes an identifier for a ticket in the consumer's ticketing 751 system. Given the current notification is an update to the 752 maintenance previously announced maintenance window, the program 753 updates the ticket for the maintenance with the new textual 754 description and marks it as closed. 756 4. Examples 758 This section of the document provides example iCalendar formats as 759 described in this document. 761 4.1. Initial Maintenance Notification 763 BEGIN:VCALENDAR 764 VERSION:2.0 765 PRODID:-//Maint Note//https://github.com/maint-notification// BEGIN:VEVENT 766 SUMMARY:Maint Note Example 767 DTSTART;VALUE=DATE-TIME:20151010T080000Z 768 DTEND;VALUE=DATE-TIME:20151010T100000Z 769 DTSTAMP;VALUE=DATE-TIME:20151010T001000Z 770 UID:42 771 SEQUENCE:1 772 X-MAINTNOTE-PROVIDER:example.com 773 X-MAINTNOTE-ACCOUNT:137.035999173 774 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 775 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 776 X-MAINTNOTE-IMPACT:NO-IMPACT 777 X-MAINTNOTE-STATUS:TENTATIVE 778 ORGANIZER;CN="Example NOC":mailto:noone@example.com 779 END:VEVENT 780 END:VCALENDAR 782 4.2. Updated Maintenance Notification 783 BEGIN:VCALENDAR 784 VERSION:2.0 785 PRODID:-//Maint Note//https://github.com/maint-notification// 786 BEGIN:VEVENT 787 SUMMARY:Maint Note Example 788 DTSTART;VALUE=DATE-TIME:20151012T080000Z 789 DTEND;VALUE=DATE-TIME:20151012T100000Z 790 DTSTAMP;VALUE=DATE-TIME:20151012T001000Z 791 UID:42 792 SEQUENCE:2 793 X-MAINTNOTE-PROVIDER:example.com 794 X-MAINTNOTE-ACCOUNT:137.035999173 795 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 796 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 797 X-MAINTNOTE-IMPACT:NO-IMPACT 798 X-MAINTNOTE-STATUS:CONFIRMED 799 ORGANIZER;CN="Example NOC":mailto:noone@example.com 800 END:VEVENT 801 END:VCALENDAR 803 4.3. Cancelled Maintenance Notification 805 BEGIN:VCALENDAR 806 VERSION:2.0 807 PRODID:-//Maint Note//https://github.com/maint-notification// 808 BEGIN:VEVENT 809 SUMMARY:Maint Note Example 810 DTSTART;VALUE=DATE-TIME:20151012T080000Z 811 DTEND;VALUE=DATE-TIME:20151012T100000Z 812 DTSTAMP;VALUE=DATE-TIME:20151012T001000Z 813 UID:42 814 SEQUENCE:3 815 X-MAINTNOTE-PROVIDER:example.com 816 X-MAINTNOTE-ACCOUNT:137.035999173 817 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 818 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 819 X-MAINTNOTE-IMPACT:NO-IMPACT 820 X-MAINTNOTE-STATUS:CANCELLED 821 ORGANIZER;CN="Example NOC":mailto:noone@example.com 822 END:VEVENT 823 END:VCALENDAR 825 4.4. Open Maintenance Notification 827 BEGIN:VCALENDAR 828 VERSION:2.0 829 PRODID:-//Maint Note//https://github.com/maint-notification// 830 BEGIN:VEVENT 831 SUMMARY:Open - Maint Note Example 832 DTSTART;VALUE=DATE-TIME:20151012T080000Z 833 DTEND;VALUE=DATE-TIME:20151012T100000Z 834 DTSTAMP;VALUE=DATE-TIME:20151012T001000Z 835 UID:42 836 SEQUENCE:3 837 X-MAINTNOTE-PROVIDER:example.com 838 X-MAINTNOTE-ACCOUNT:137.035999173 839 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 840 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 841 X-MAINTNOTE-IMPACT:NO-IMPACT 842 X-MAINTNOTE-STATUS:IN-PROCESS 843 ORGANIZER;CN="Example NOC":mailto:noone@example.com 844 END:VEVENT 845 END:VCALENDAR 847 4.5. Closed Maintenance Notification 849 BEGIN:VCALENDAR 850 VERSION:2.0 851 PRODID:-//Maint Note//https://github.com/maint-notification// 852 BEGIN:VEVENT 853 SUMMARY:Closed - Maint Note Example 854 DTSTART;VALUE=DATE-TIME:20151012T080000Z 855 DTEND;VALUE=DATE-TIME:20151012T100000Z 856 DTSTAMP;VALUE=DATE-TIME:20151012T001000Z 857 UID:42 858 SEQUENCE:4 859 X-MAINTNOTE-PROVIDER:example.com 860 X-MAINTNOTE-ACCOUNT:137.035999173 861 X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415 862 X-MAINTNOTE-OBJECT-ID:acme-widgets-as-a-service 863 X-MAINTNOTE-IMPACT:NO-IMPACT 864 X-MAINTNOTE-STATUS: COMPLETED 865 ORGANIZER;CN="Example NOC":mailto:noone@example.com 866 END:VEVENT 867 END:VCALENDAR 869 5. Considerations 871 The following sections outlines Localization and Security 872 considerations. 874 5.1. Localization Considerations 876 Localization may be performed as needed by the implementors of this 877 document. English text used in the iCalendar data format [RFC 5545] 878 [RFC5545] or extensions described in this document may be converted 879 to local languages as required. 881 5.2. Security Considerations 883 Maintenance notifications are often used as an aid in the planning of 884 operational activities. Incorrect or undelivered maintenance 885 notification information could, if used or required to plan 886 operational activities, result in an operational problem. By 887 preventing the receipt or correct processing of maintenance 888 notifications, modifying or generating false maintenance 889 notifications, an attacker could negatively impact the operations of 890 targeted organizations. 892 It is a common practice to distribute maintenance notifications via 893 Email. Email messages are not immune to disruption, modification or 894 fabrication by an attacker. To mitigate possible attacks we 895 recommend the use of existing techniques to authenticate maintenance 896 notifications distributed via email. For example, OpenPGP [RFC 3156] 897 [RFC3156]could be used to sign a maintenance notification email and 898 include a message integrity check covering the contents of the email. 899 This technique is applied to the contents of the email, which would 900 include the extended iCal data specified in this document. This 901 method, where implemented by both the generator and receiver of a 902 maintenance notification, would prevent the fabrication or 903 modification of maintenance notification emails. Use of OpenPGP to 904 sign messages would only benefit those messages that were delivered 905 to the receiver; it does not address situations where maintenance 906 notifications are disrupted before they can be delivered to the 907 recipient. 909 As an alternative to pushing maintenance notifications from 910 generators to receivers via email distribution, receivers could pull 911 maintenance notification information from generators via the CalDAV 912 protocol [RFC 4791] [RFC4791]. Authenticity and integrity of this 913 communications channel could be provided by accessing CalDAV end 914 points via TLS [RFC 5246] [RFC5246]. CalDAV is simply a means to 915 publish iCal formatted content, in this case the extended iCal data 916 specified in this document. 918 Implementors of this convention SHOULD ensure the correctness of all 919 information exchanged when taking automated action based on what they 920 receive. Comparison against out of band sources of information to 921 confirm the correctness of information received MAY be used to detect 922 incorrect information and prevent acting based on it. 924 6. IANA Considerations 926 This memo includes no request to IANA. 928 7. Acknowledgements 930 The authors of this document would like to thank the original authors 931 and advocates of the BCOP draft for their efforts to contributing to 932 this maintenance notifcation improvement. Their initial design and 933 creativity building this convention is sincerely appreciated. 935 To give credit where it's due, this is an excerpt from the original 936 draft: "At NANOG 60, Randy Neals floated the idea of improving 937 maintenance notifications to make it easier to write programs to 938 consume them. Noting a willingness on the part of several attendees 939 (Peter Hoose, Erik Klavon, Dave McGaugh, Paul Schultz, and Joel 940 Wride) to collaborate on drafting standards for machine parsable 941 maintenance notifications, Randy organized the initial effort. Randy 942 held a couple conference calls and worked with the group to draft a 943 rough charter. Unfortunately Randy had to withdraw from the role of 944 shepherd due to competing priorities. Erik picked up where Randy 945 left off, and - thanks to the advocacy of the other original 946 participants - began working with Francisco Hidalgo, Tylar Keese, and 947 Tj Trask on the project." 949 8. Normative References 951 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 952 Requirement Levels", BCP 14, RFC 2119, 953 DOI 10.17487/RFC2119, March 1997, 954 . 956 [RFC3156] Elkins, M., Del Torto, D., Levien, R., and T. Roessler, 957 "MIME Security with OpenPGP", RFC 3156, 958 DOI 10.17487/RFC3156, August 2001, 959 . 961 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 962 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 963 DOI 10.17487/RFC4791, March 2007, 964 . 966 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 967 (TLS) Protocol Version 1.2", RFC 5246, 968 DOI 10.17487/RFC5246, August 2008, 969 . 971 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 972 Scheduling Core Object Specification (iCalendar)", 973 RFC 5545, DOI 10.17487/RFC5545, September 2009, 974 . 976 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 977 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 978 2014, . 980 Author's Address 982 Ryan Gunter (editor) 983 Twitch 984 350 Bush St 985 San Francisco, CA 94104 986 USA 988 Phone: +1 415 568 7607 989 Email: rgunter@twitch.tv