A Network Inventory Location Model
draft-wbbpb-ivy-network-inventory-location-00
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Bo Wu , Sergio Belotti , Jean-Francois Bouquier , Fabio Peruzzini , Phil Bedard | ||
| Last updated | 2024-02-07 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Yang Validation | 10 errors, 2 warnings | ||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-wbbpb-ivy-network-inventory-location-00
IVY B. Wu
Internet-Draft Huawei
Intended status: Standards Track S. Belotti
Expires: 10 August 2024 Nokia
J.-F. Bouquier
Vodafone
F. Peruzzini
TIM
P. Bedard
Cisco
7 February 2024
A Network Inventory Location Model
draft-wbbpb-ivy-network-inventory-location-00
Abstract
This document defines a Yang data model for Network Inventory
location, e.g. site, room, rack, geo-location data, which is used to
provide location information with different granularities for network
inventory items (such as Network Elements, device components).
Accurate location information is useful for network planning,
deployment, and maintenance. However, such information cannot be
obtained or verified from Network Elements and therefore is not
included in the base Network Inventory model defined in draft-ietf-
ivy-network-inventory-yang. The purpose of this document is to
define a location model for network inventory that extends the base
inventory with comprehensive location data.
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 10 August 2024.
Wu, et al. Expires 10 August 2024 [Page 1]
Internet-Draft Network Inventory Location February 2024
Copyright Notice
Copyright (c) 2024 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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology and Notations . . . . . . . . . . . . . . . . 3
1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Hierarchical Locations of of Network Inventory . . . . . . . 3
3. Rack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Network Inventory Location Tree . . . . . . . . . . . . . . . 6
5. YANG Data model for Network Inventory Location . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction
During the discussion of base Network Inventory (NI) model
[I-D.ietf-ivy-network-inventory-yang], it is agreed that the
definition of the equipment room and rack can be a separate location
model and support manual configuration, while the NI model aggregates
the inventory data of the Network Elements (NEs) on the network.
Usually the information about sites or equipment rooms is not
detectable by domain controller and configured manually.
NEs can be grouped by location to provide more information for
network planning, deployment, and maintenance (e.g. Locate
problematic NEs and optimize network resources). The location could
be outdoors or indoors. The indoor location may be represented as a
building, room, or similar organizational identifier. Outdoor
locations can be walls, poles, or other mount places.
Wu, et al. Expires 10 August 2024 [Page 2]
Internet-Draft Network Inventory Location February 2024
Network Inventory location model allows you to create physical
locations, such as sites, building, equipment rooms, racks, and so
on. The location information can be extended to the base network
inventory, rack-mounted or not. The model can also include a
physical address or geo-location data (geographic coordinates).
The model Network Inventory location conforms to the Network
Management Datastore Architecture (NMDA).
1.1. Terminology and Notations
The following terms are defined in [RFC7950] and are not redefined
here:
* client
* server
* augment
* data model
* data node
The following terms are defined in [RFC6241] and are not redefined
here:
* configuration data
* state data
1.2. Requirements Language
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 [RFC2119][RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. Hierarchical Locations of of Network Inventory
The "location" list is generalized to support abstract locations,
such as sites, as well as concrete type of location, such as room,
building.
A site represents a abstract geographic location to group a set of
Network Elements (NEs) and corresponding inventory components. NEs,
racks, equipment rooms, and buildings can be grouped within a site.
Wu, et al. Expires 10 August 2024 [Page 3]
Internet-Draft Network Inventory Location February 2024
A room is a facility, a centralized space for network elements and
other equipment (such as servers, storage) with power supply system,
air conditioning system, etc.
Locations can be nested to form a hierarchy. For example, buildings
can be within a site and rooms in a building.
The "location-type" is defined as a YANG identity to describe the
type of the inventory location, which could be site, equipment room,
or building.
+--rw location* [id]
| +--rw id yang:uri
| +--rw name? string
| +--rw description? string
| +--rw alias? string
| +--rw location-type? identityref
| +--rw parent -> ../../location/id
| +--rw child* -> ../../location/id
| +--rw physical-address
| | ...
| +--rw geo-location
| ...
...................................
Figure 1: YANG Subtree of Location
3. Rack
"racks" represent physical equipment racks in which Network Elements
(NEs) can be installed, which facilitate device maintenance. Through
"rack-location", each rack can be assigned to a site or a specific
location within the site, such as a equipment room.
Each rack is assigned a unique ID and a name. A rack could have some
specific attributes, such as appearance-related attributes and
electricity-related attributes. The height, depth and width are
described by Figure 2 (please consider that the door of the rack is
facing the user).
Note: Further discussion is needed to decide whether to separate
"racks" from the list of "location".
Wu, et al. Expires 10 August 2024 [Page 4]
Internet-Draft Network Inventory Location February 2024
---------------- ---
/| /| |
/ | / | |
/ | / | |
----|-----------| | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | height
| | | | |
| | | | |
| | | | |
| | Door Q | | |
| | Q | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| /-----------|---- ---
| / | / /
| / | / depth
|/ | / /
----------------- ---
|______width____|
| |
Figure 2: height, width and depth of rack
The rack attributes include:
+--ro racks
+--ro rack* [id]
...................................
+--rw height? uint16
+--rw width? uint16
+--rw depth? uint16
+--rw max-voltage? uint16
+--rw max-allocated-power? uint16
...................................
Figure 3: YANG Subtree of Rack
Max-voltage: the maximum voltage supported by the rack.
Wu, et al. Expires 10 August 2024 [Page 5]
Internet-Draft Network Inventory Location February 2024
4. Network Inventory Location Tree
The following tree diagram [RFC8340] provides an overview of the data
model for "ietf-ni-location" module.
module: ietf-ni-location
+--rw locations
+--rw location* [id]
| +--rw id yang:uri
| +--rw name? string
| +--rw description? string
| +--rw alias? string
| +--rw location-type? identityref
| +--rw parent? -> ../../location/id
| +--rw child* -> ../../location/id
| +--rw physical-address
| | +--rw address? string
| | +--rw postal-code? string
| | +--rw state? string
| | +--rw city? string
| | +--rw country-code? string
| +--rw geo-location
| +--rw reference-frame
| | +--rw alternate-system? string
| | | {alternate-systems}?
| | +--rw astronomical-body? string
| | +--rw geodetic-system
| | +--rw geodetic-datum? string
| | +--rw coord-accuracy? decimal64
| | +--rw height-accuracy? decimal64
| +--rw (location)?
| | +--:(ellipsoid)
| | | +--rw latitude? decimal64
| | | +--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? yang:date-and-time
| +--rw valid-until? yang:date-and-time
+--rw racks
+--rw rack* [id]
+--rw id yang:uri
Wu, et al. Expires 10 August 2024 [Page 6]
Internet-Draft Network Inventory Location February 2024
+--rw name? string
+--rw description? string
+--rw alias? string
+--rw rack-location
| +--rw location-ref? -> /locations/location/id
| +--rw row-number? uint32
| +--rw column-number? uint32
+--rw height? uint16
+--rw width? uint16
+--rw depth? uint16
+--rw max-voltage? uint16
+--rw max-allocated-power? uint16
+--rw contained-chassis* [ne-ref component-ref]
+--rw ne-ref
| -> /nwi:network-elements/network-element/id
+--rw component-ref leafref
+--rw relative-position? uint8
augment /nwi:network-elements/nwi:network-element:
+--rw locations
+--rw location* -> /locations/location/id
+--rw rack? -> /locations/racks/rack/id
5. YANG Data model for Network Inventory Location
The "ietf-ni-location" module uses types defined in [RFC9179],
[I-D.ietf-ivy-network-inventory-yang].
<CODE BEGINS>
file="ietf-ni-location@2024-02-07.yang"
module ietf-ni-location {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-ni-location";
prefix nil;
import ietf-network-inventory {
prefix nwi;
reference
"RFCXXXX: A YANG Data Model for Network Inventory";
}
import ietf-geo-location {
prefix geo;
reference
"RFC 9179: A YANG Grouping for Geographic Locations";
}
organization
"IETF Network Inventory YANG (ivy) Working Group";
Wu, et al. Expires 10 August 2024 [Page 7]
Internet-Draft Network Inventory Location February 2024
contact
"WG Web: <https://datatracker.ietf.org/wg/ivy>
WG List: <mailto:inventory-yang@ietf.org>
Editor: Bo Wu
<lana.wubo@huawei.com>
Editor: Sergio Belotti
<sergio.belotti@nokia.com>
Editor: Jean-Francois Bouquier
<jeff.bouquier@vodafone.com>
Editor: Fabio Peruzzini
<fabio.peruzzini@telecomitalia.it>
Editor: Phil Bedard
<phbedard@cisco.com>";
description
"This YANG module defines a model for Network Inventory
location.
Copyright (c) 2024 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 Revised 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; see
the RFC itself for full legal notices.";
revision 2024-02-07 {
description
"Initial version";
reference
"RFC XXXX: A YANG Data Model for Network Inventory location.";
//RFC Editor: Please replace XXXX with actual RFC number,
//update date information and remove this note
}
identity inventory-location-type {
description
"Base identity for network inventory location types.";
}
identity site {
base inventory-location-type;
description
Wu, et al. Expires 10 August 2024 [Page 8]
Internet-Draft Network Inventory Location February 2024
"Indicates site as location type.";
}
identity room {
base inventory-location-type;
description
"Indicates equipment room as location type.";
}
identity building {
base inventory-location-type;
description
"Indicates building as location type.";
}
grouping locations-grouping {
description
"The grouping of the locations.";
list location {
key "id";
description
"The list of sites within the network.";
uses nwi:common-entity-attributes;
leaf location-type {
type identityref {
base inventory-location-type;
}
description
"The type of network inventory location, e.g.
equipment room, building, or site.";
}
leaf parent {
type leafref {
path "../../location/id";
}
description
"The name of the parent locations.";
}
leaf-list child {
type leafref {
path "../../location/id";
}
description
"The name of the child locations.";
}
uses physical-address-grouping;
uses geo:geo-location;
}
Wu, et al. Expires 10 August 2024 [Page 9]
Internet-Draft Network Inventory Location February 2024
}
grouping physical-address-grouping {
description
"The grouping of the physical address.";
container physical-address {
description
"Top level container for the physical address.";
leaf address {
type string;
description
"Address (number and street) of the site.";
}
leaf postal-code {
type string;
description
"Postal code of the site.";
}
leaf state {
type string;
description
"State of the site. This leaf can also be
used to describe a region for a country that
does not have states.";
}
leaf city {
type string;
description
"City of the site.";
}
leaf country-code {
type string {
pattern '[A-Z]{2}';
}
description
"Country of the site.
Expressed as ISO ALPHA-2 code.";
}
}
}
grouping rack-grouping {
description
"The attributes of the rack.";
container racks {
description
"Top level container for the list of racks.";
list rack {
Wu, et al. Expires 10 August 2024 [Page 10]
Internet-Draft Network Inventory Location February 2024
key "id";
description
"The list of racks within an equipment room.";
uses nwi:common-entity-attributes;
container rack-location {
description
"The location information of the rack, which
comprises the name of the location, row number, and
column number.";
leaf location-ref {
type leafref {
path "/nil:locations/nil:location/nil:id";
}
description
"Name of location where this rack is located.";
}
leaf row-number {
type uint32;
description
"Identifies the row within the equipment room where
the rack is located.";
}
leaf column-number {
type uint32;
description
"Identifies the physical location of the rack within
the column.";
}
}
leaf height {
type uint16;
units "millimeter";
description
"Rack height.";
}
leaf width {
type uint16;
units "millimeter";
description
"Rack width.";
}
leaf depth {
type uint16;
units "millimeter";
description
"Rack depth.";
}
leaf max-voltage {
Wu, et al. Expires 10 August 2024 [Page 11]
Internet-Draft Network Inventory Location February 2024
type uint16;
units "volt";
description
"The maximum voltage could be supported by the rack.";
}
leaf max-allocated-power {
type uint16;
units "watts";
description
"The maximum allocated power to the rack.";
}
list contained-chassis {
key "ne-ref component-ref";
description
"The list of chassis within a rack.";
leaf ne-ref {
type leafref {
path "/nwi:network-elements/nwi:network-element"
+ "/nwi:id";
}
description
"The reference to the network element containing
the chassis component.";
}
leaf component-ref {
type leafref {
path "/nwi:network-elements/nwi:network-element"
+ "[nwi:id=current()/../ne-ref]/nwi:components"
+ "/nwi:component/nwi:id";
}
description
"The reference to the chassis component within
the network element and contained by the rack.";
}
leaf relative-position {
type uint8;
description
"A relative position of chassis within
the rack";
}
}
}
}
}
grouping locations-ref-grouping {
description
"The attributes of the locations.";
Wu, et al. Expires 10 August 2024 [Page 12]
Internet-Draft Network Inventory Location February 2024
container locations {
description
"The container for the location.";
leaf-list location {
type leafref {
path "/nil:locations/nil:location/nil:id";
}
description
"The reference of the location.";
}
leaf rack {
type leafref {
path "/nil:locations/nil:racks"
+ "/nil:rack/nil:id";
}
description
"The reference to the rack.";
}
}
}
container locations {
description
"The top-level container for the NE location information.";
uses locations-grouping;
uses rack-grouping;
}
augment "/nwi:network-elements/nwi:network-element" {
description
"Provides location information for network inventory.";
uses locations-ref-grouping;
}
}
<CODE ENDS>
6. Security Considerations
The YANG module specified in this document defines a data schema
designed to be accessed through network management protocols such as
NETCONF [RFC6241]or RESTCONF [RFC8040]. The lowest NETCONF layer is
the secure transport layer, and the required secure transport is
Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS,
and the required secure transport is TLS [RFC8446].
Wu, et al. Expires 10 August 2024 [Page 13]
Internet-Draft Network Inventory Location February 2024
The Network Configuration Access Control Model (NACM) [RFC8341]
provides a means of restricting access to specific NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and contents. Thus, NACM SHOULD be used
to restrict the NSF registration from unauthorized users.
There are a number of data nodes defined in this YANG module that are
writable, creatable, and deletable (i.e., config true, which is the
default). These data nodes may be considered sensitive or vulnerable
in some network environments. Write operations to these data nodes
could have a negative effect on network and security operations.
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:
<<<to be completed>>>
7. IANA Considerations
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-ni-location
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
This document registers a YANG module in the "YANG Module Names"
registry[RFC7950] .
name: ietf-ni-location
namespace: urn:ietf:params:xml:ns:yang:ietf-ni-location
prefix: nil
maintained by IANA: N
reference: RFC xxxx
8. Acknowledgements
The authors of this document would like to thank the authors and
contributors of [I-D.ietf-ccamp-network-inventory-yang] to trigger
this work.
Wu, et al. Expires 10 August 2024 [Page 14]
Internet-Draft Network Inventory Location February 2024
9. Contributors
The following authors contributed significantly to this document:
Italo Busi
Huawei Technologies
Email: italo.busi@huawei.com
Chaode Yu
Huawei Technologies
Email: yuchaode@huawei.com
10. References
10.1. Normative References
[I-D.ietf-ivy-network-inventory-yang]
Yu, C., Belotti, S., Bouquier, J., Peruzzini, F., and P.
Bedard, "A YANG Data Model for Network Inventory", Work in
Progress, Internet-Draft, draft-ietf-ivy-network-
inventory-yang-00, 5 December 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-ivy-
network-inventory-yang-00>.
[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>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[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,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
Wu, et al. Expires 10 August 2024 [Page 15]
Internet-Draft Network Inventory Location February 2024
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[RFC9179] Hopps, C., "A YANG Grouping for Geographic Locations",
RFC 9179, DOI 10.17487/RFC9179, February 2022,
<https://www.rfc-editor.org/info/rfc9179>.
10.2. Informative References
[I-D.ietf-ccamp-network-inventory-yang]
Yu, C., Belotti, S., Bouquier, J., Peruzzini, F., and P.
Bedard, "A YANG Data Model for Network Hardware
Inventory", Work in Progress, Internet-Draft, draft-ietf-
ccamp-network-inventory-yang-02, 9 July 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-ccamp-
network-inventory-yang-02>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
Authors' Addresses
Bo Wu
Huawei
101 Software Avenue, Yuhua District
Nanjing
Jiangsu, 210012
China
Email: lana.wubo@huawei.com
Sergio Belotti
Nokia
Wu, et al. Expires 10 August 2024 [Page 16]
Internet-Draft Network Inventory Location February 2024
Email: sergio.belotti@nokia.com
Jean-Francois Bouquier
Vodafone
Email: jeff.bouquier@vodafone.com
Fabio Peruzzini
TIM
Email: fabio.peruzzini@telecomitalia.it
Phil Bedard
Cisco
Email: phbedard@cisco.com
Wu, et al. Expires 10 August 2024 [Page 17]