--- 1/draft-ietf-netmod-geo-location-04.txt 2020-07-29 04:13:59.413327768 -0700 +++ 2/draft-ietf-netmod-geo-location-05.txt 2020-07-29 04:13:59.461328987 -0700 @@ -1,18 +1,18 @@ Network Working Group C. Hopps Internet-Draft LabN Consulting, L.L.C. -Intended status: Standards Track 1 March 2020 -Expires: 2 September 2020 +Intended status: Standards Track 29 July 2020 +Expires: 30 January 2021 A YANG Grouping for Geographic Locations - draft-ietf-netmod-geo-location-04 + draft-ietf-netmod-geo-location-05 Abstract This document defines a generic geographical location object YANG grouping. The geographical location grouping is intended to be used in YANG models for specifying a location on or in reference to the Earth or any other astronomical object. Status of This Memo @@ -22,21 +22,21 @@ 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 2 September 2020. + This Internet-Draft will expire on 30 January 2021. Copyright Notice Copyright (c) 2020 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 @@ -50,35 +50,37 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3 2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3 2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5 2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5 2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 11 + 4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 12 5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13 5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 13 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 15 5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 - 6.1. Geodetic System Value Registry . . . . . . . . . . . . . 16 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 - 8. Normative References . . . . . . . . . . . . . . . . . . . . 18 - 9. Informative References . . . . . . . . . . . . . . . . . . . 19 - Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 - Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 + 6.1. Geodetic System Values Registry . . . . . . . . . . . . . 16 + 6.2. Updates to the IETF XML Registry . . . . . . . . . . . . 18 + 6.3. Updates to the YANG Module Names Registry . . . . . . . . 18 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 + 8. Normative References . . . . . . . . . . . . . . . . . . . . 19 + 9. Informative References . . . . . . . . . . . . . . . . . . . 20 + Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 24 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 1. Introduction In many applications we would like to specify the location of something geographically. Some examples of locations in networking might be the location of data center, a rack in an internet exchange point, a router, a firewall, a port on some device, or it could be the endpoints of a fiber, or perhaps the failure point along a fiber. Additionally, while this location is typically relative to The Earth, @@ -226,85 +229,91 @@ | | +-- longitude? decimal64 | | +-- height? decimal64 | +--:(cartesian) | +-- x? decimal64 | +-- y? decimal64 | +-- z? decimal64 +-- velocity | +-- v-north? decimal64 | +-- v-east? decimal64 | +-- v-up? decimal64 - +-- timestamp? types:date-and-time - +-- valid-until? types:date-and-time + +-- timestamp? yang:date-and-time + +-- valid-until? yang:date-and-time 3. YANG Module + This model imports Common YANG Data Types [RFC6991]. + file "ietf-geo-location@2019-02-17.yang" module ietf-geo-location { + yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; prefix geo; - import ietf-yang-types { prefix types; } + import ietf-yang-types { + prefix yang; + reference "RFC 6991: Common YANG Data Types."; + } organization "IETF NETMOD Working Group (NETMOD)"; contact "Christian Hopps "; - // RFC Ed.: replace XXXX with actual RFC number and - // remove this note. + // RFC Ed.: replace XXXX with actual RFC number or IANA reference + // and remove this note. description "This module defines a grouping of a container object for specifying a location on or around an astronomical object (e.g., The Earth). Copyright (c) 2019 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. - // RFC Ed.: replace XXXX with actual RFC number and - // remove this note. + // RFC Ed.: replace XXXX with actual RFC number or IANA reference + // and remove this note. 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 (RFC 2119) (RFC 8174) when, and only when, they appear in all capitals, as shown here."; revision 2019-02-17 { description "Initial Revision"; - reference "RFC XXXX: YANG Geo Location"; + reference "RFC XXXX: A YANG Grouping for Geographic Locations"; } feature alternate-systems { description "This feature means the device supports specifying locations using alternate systems for reference frames."; } grouping geo-location { description "Grouping to identify a location on an astronomical object."; container geo-location { description - "A location on an astronomical body (e.g., The Earth) + "A location on an astronomical body (e.g., the Earth) somewhere in a universe."; container reference-frame { description "The Frame of Reference for the location values."; leaf alternate-system { if-feature alternate-systems; type string; description @@ -325,37 +334,41 @@ "An astronomical body as named by the International Astronomical Union (IAU) or according to the alternate system if specified. Examples include 'sun' (our star), 'earth' (our planet), 'moon' (our moon), 'enceladus' (a moon of Saturn), 'ceres' (an asteroid), '67p/churyumov-gerasimenko (a comet). The value should be comprised of all lower case ASCII characters not including control characters (i.e., values 32..64, and 91..126). Any preceding 'the' in the name should not be included."; + reference "https://www.iau.org/"; } container geodetic-system { description "The geodetic system of the location data."; leaf geodetic-datum { type string { pattern '[ -@\[-\^_-~]*'; } default "wgs-84"; description "A geodetic-datum defining the meaning of latitude, longitude and height. The default is 'wgs-84' which is used by the Global Positioning System (GPS). The value SHOULD be comprised of all lower case ASCII characters not including control characters (i.e., values 32..64, and 91..126). The IANA registry further restricts the value by converting all spaces (' ') to dashes ('-')"; + reference + "IANA XXXX YANG Geographic Location Parameters, + Geodetic System Values"; } leaf coord-accuracy { type decimal64 { fraction-digits 6; } description "The accuracy of the latitude longitude pair for ellipsoidal coordinates, or the X, Y and Z components for Cartesian coordinates. When coord-accuracy is specified it overrides the geodetic-datum implied @@ -431,21 +444,25 @@ } units "meters"; description "The Z value as defined by the reference-frame."; } } } container velocity { description "If the object is in motion the velocity vector describes - this motion at the the time given by the timestamp"; + this motion at the the time given by the timestamp. For a + formula to convert these values to speed and heading see + this modules defining document RFC XXXX."; + reference + "RFC XXXX: A YANG Grouping for Geographic Locations"; leaf v-north { type decimal64 { fraction-digits 12; } units "meters per second"; description "v-north is the rate of change (i.e., speed) towards truth north as defined by the ~geodetic-system~."; } @@ -463,25 +481,25 @@ type decimal64 { fraction-digits 12; } units "meters per second"; description "v-up is the rate of change (i.e., speed) away from the center of mass."; } } leaf timestamp { - type types:date-and-time; + type yang:date-and-time; description "Reference time when location was recorded."; } leaf valid-until { - type types:date-and-time; + type yang:date-and-time; description "The timestamp for which this geo-location is valid until. If unspecified the geo-location has no specific expiration time."; } } } } @@ -661,22 +679,22 @@ geodetic systems fully supported. GML also defines an observation value in "gml:Observation" which includes a timestamp value "gml:validTime" in addition to other components such as "gml:using" "gml:target" and "gml:resultOf". Only the timestamp is mappable to and from the YANG grouping. Furthermore "gml:validTime" can either be an Instantaneous measure ("gml:TimeInstant") or a time period ("gml:TimePeriod"). The instantaneous "gml:TimeInstant" is mappable to and from the YANG grouping "timestamp" value, and values down to the resolution of - seconds for "gml:TimePeriod" can be mapped using the using the - "valid-for" node of the YANG grouping. + seconds for "gml:TimePeriod" can be mapped using the "valid-until" + node of the YANG grouping. 5.1.4. KML KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by Google to the Open Geospatial Consortium, (https://www.opengeospatial.org/) and was adopted. The latest version as of this writing is KML 2.3 [KML23]. This schema includes geographic location data in some of its objects (e.g., "kml:Point" or "kml:Camera" objects). This data is provided in string format and corresponds to the [W3CGEO] values. The timestamp value is also @@ -705,21 +723,25 @@ directions (when using a supported altitude mode) with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than strings. For the relative height cases the application doing the transformation is expected to have the data available to transform the relative height into an absolute height which can then be expressed using the YANG grouping. 6. IANA Considerations -6.1. Geodetic System Value Registry +6.1. Geodetic System Values Registry + + IANA is asked to create a new registry "Geodetic System Values" + grouped under a new category named "YANG Geographic Location + Parameters". This registry allocates names for standard geodetic systems. Often these values are referred to using multiple names (e.g., full names or multiple acronyms values). The intent of this registry is to provide a single standard value for any given geodetic system. The values SHOULD use an acronym when available, they MUST be converted to lower case, and spaces MUST be changed to dashes "-". Each entry should be sufficient to define the 3 coordinate values (2 @@ -751,28 +773,90 @@ | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | +------------+------------------------------------------------------+ | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | +------------+------------------------------------------------------+ | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or | | | better) | +------------+------------------------------------------------------+ Table 3 +6.2. Updates to the IETF XML Registry + + This document registers a URI in the "IETF XML Registry" [RFC3688]. + Following the format in [RFC3688], the following registration has + been made: + + URI urn:ietf:params:xml:ns:yang:ietf-geo-location + + Registrant Contact The IESG. + + XML N/A; the requested URI is an XML namespace. + +6.3. Updates to the YANG Module Names Registry + + This document registers one YANG module in the "YANG Module Names" + registry [RFC6020]. Following the format in [RFC6020], the following + registration has been made: + + name ietf-geo-location + + namespace urn:ietf:params:xml:ns:yang:ietf-geo-location + + prefix geo + + reference RFC XXXX (RFC Ed.: replace XXX with actual RFC number and + remove this note.) + 7. Security Considerations - This document defines a common geo location grouping using the YANG - data modeling language. The grouping itself has no security or - privacy impact on the Internet, but the usage of the grouping in - concrete YANG modules might have. The security considerations - spelled out in the YANG 1.1 specification [RFC7950] apply for this - document as well. + The YANG module specified in this document defines a schema for data + that is designed to be accessed via network management protocols such + as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer + is the secure transport layer, and the mandatory-to-implement secure + transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer + is HTTPS, and the mandatory-to-implement secure transport is TLS + [RFC8446]. + + The NETCONF access control model [RFC8341] provides the means to + restrict access for particular NETCONF or RESTCONF users to a + preconfigured subset of all available NETCONF or RESTCONF protocol + operations and content. + + Since the modules defined in this document only define groupings, + these considerations are primarily for the designers of other modules + that use these groupings. + + All of the data nodes defined in this YANG module are + writable/creatable/deletable (i.e., "config true", which is the + default). These data nodes may be considered sensitive or vulnerable + in some network environments. Write operations (e.g., edit-config) + to these data nodes without proper protection can have a negative + effect on network operations. These are the subtrees and data nodes + and their sensitivity/vulnerability: + + None of the writable/creatable/deletable data nodes in the YANG + module defined in this document are by themselves considered more + sensitive or vulnerable then standard configuration. + + Some of the readable data nodes in this YANG module may be considered + sensitive or vulnerable in some network environments. It is thus + important to control read access (e.g., via get, get-config, or + notification) to these data nodes. These are the subtrees and data + nodes and their sensitivity/vulnerability: + + Since the grouping defined in this module identifies locations, + authors using this grouping SHOULD consider any privacy issues that + may arise when the data is readable. + + This document does not define any RPC actions and hence this section + does not consider the security of RPCs. 8. Normative References [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, "An Earth Gravitational Model to Degree 2160: EGM08.", Presented at the 2008 General Assembly of the European Geosciences Union, Vienna, Arpil13-18, 2008, 2008, . @@ -789,71 +873,105 @@ [ISO.6709.2008] International Organization for Standardization, "ISO 6709:2008 Standard representation of geographic point location by coordinates.", 2008. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . - [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for - Writing an IANA Considerations Section in RFCs", BCP 26, - RFC 8126, DOI 10.17487/RFC8126, June 2017, - . + [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6991, DOI 10.17487/RFC6991, July 2013, + . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, . [WGS84] National Imagery and Mapping Agency., "National Imagery and Mapping Agency Technical Report 8350.2, Third - Edition.", 3 January 2000, - . + Edition.", 3 January 2000, . 9. Informative References [ISO.19136.2007] International Organization for Standardization, "ISO 19136:2007 Geographic information -- Geography Markup - Language (GML)", March 2020. + Language (GML)". [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, . [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, . + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + . + [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, June 2010, . + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, October 2010, + . + + [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., + and A. Bierman, Ed., "Network Configuration Protocol + (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, + . + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + . + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF + Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, + . + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November - 2016, . + 2016, . Appendix A. Examples Below is a fictitious module that uses the geo-location grouping. module example-uses-geo-location { namespace "urn:example:example-uses-geo-location"; prefix ugeo; import ietf-geo-location { prefix geo; } @@ -898,22 +1016,22 @@ | | +--rw longitude? decimal64 | | +--rw height? decimal64 | +--:(cartesian) | +--rw x? decimal64 | +--rw y? decimal64 | +--rw z? decimal64 +--rw velocity | +--rw v-north? decimal64 | +--rw v-east? decimal64 | +--rw v-up? decimal64 - +--rw timestamp? types:date-and-time - +--rw valid-until? types:date-and-time + +--rw timestamp? yang:date-and-time + +--rw valid-until? yang:date-and-time Below is some example YANG XML data for the fictitious module that uses the geo-location grouping. Gaetana's 40.73297 -74.007696 @@ -958,21 +1076,21 @@ me Figure 3: Example XML data of geo location use. -Appendix B. Acknowledgements +Appendix B. Acknowledgments We would like to thank Jim Biard and Ben Koziol for their reviews and suggested improvements. We would also like to thank Peter Lothberg for the motivation as well as help in defining a broadly useful geographic location object, and Acee Lindem and Qin Wu for their work on a geographic location object that led to this documents creation. Author's Address Christian Hopps LabN Consulting, L.L.C.