--- 1/draft-ietf-opsawg-nat-yang-16.txt 2018-09-27 01:13:10.934991373 -0700 +++ 2/draft-ietf-opsawg-nat-yang-17.txt 2018-09-27 01:13:11.094995203 -0700 @@ -1,26 +1,26 @@ Network Working Group M. Boucadair, Ed. Internet-Draft Orange Intended status: Standards Track S. Sivakumar -Expires: March 28, 2019 Cisco Systems +Expires: March 31, 2019 Cisco Systems C. Jacquenet Orange S. Vinapamula Juniper Networks Q. Wu Huawei - September 24, 2018 + September 27, 2018 A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT) - draft-ietf-opsawg-nat-yang-16 + draft-ietf-opsawg-nat-yang-17 Abstract This document defines a YANG module for the Network Address Translation (NAT) function. Network Address Translation from IPv4 to IPv4 (NAT44), Network Address and Protocol Translation from IPv6 Clients to IPv4 Servers (NAT64), Customer-side transLATor (CLAT), Stateless IP/ICMP Translation (SIIT), Explicit Address Mappings for Stateless IP/ICMP @@ -49,21 +49,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 March 28, 2019. + This Internet-Draft will expire on March 31, 2019. Copyright Notice Copyright (c) 2018 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 @@ -84,40 +84,40 @@ 2.4. Other Transport Protocols . . . . . . . . . . . . . . . . 7 2.5. IP Addresses Used for Translation . . . . . . . . . . . . 8 2.6. Port Set Assignment . . . . . . . . . . . . . . . . . . . 8 2.7. Port-Restricted IP Addresses . . . . . . . . . . . . . . 8 2.8. NAT Mapping Entries . . . . . . . . . . . . . . . . . . . 9 2.9. Resource Limits . . . . . . . . . . . . . . . . . . . . . 12 2.10. Binding the NAT Function to an External Interface . . . . 15 2.11. Relationship to NATV2-MIB . . . . . . . . . . . . . . . . 15 2.12. Tree Structure . . . . . . . . . . . . . . . . . . . . . 16 3. NAT YANG Module . . . . . . . . . . . . . . . . . . . . . . . 22 - 4. Security Considerations . . . . . . . . . . . . . . . . . . . 72 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 - 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 74 + 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 - 7.1. Normative References . . . . . . . . . . . . . . . . . . 75 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 74 7.2. Informative References . . . . . . . . . . . . . . . . . 77 - Appendix A. Sample Examples . . . . . . . . . . . . . . . . . . 79 + Appendix A. Sample Examples . . . . . . . . . . . . . . . . . . 78 A.1. Traditional NAT44 . . . . . . . . . . . . . . . . . . . . 79 - A.2. Carrier Grade NAT (CGN) . . . . . . . . . . . . . . . . . 81 - A.3. CGN Pass-Through . . . . . . . . . . . . . . . . . . . . 84 - A.4. NAT64 . . . . . . . . . . . . . . . . . . . . . . . . . . 85 - A.5. Stateless IP/ICMP Translation (SIIT) . . . . . . . . . . 85 + A.2. Carrier Grade NAT (CGN) . . . . . . . . . . . . . . . . . 80 + A.3. CGN Pass-Through . . . . . . . . . . . . . . . . . . . . 83 + A.4. NAT64 . . . . . . . . . . . . . . . . . . . . . . . . . . 84 + A.5. Stateless IP/ICMP Translation (SIIT) . . . . . . . . . . 84 A.6. Explicit Address Mappings for Stateless IP/ICMP - Translation (EAM SIIT) . . . . . . . . . . . . . . . . . 86 - A.7. Static Mappings with Port Ranges . . . . . . . . . . . . 89 - A.8. Static Mappings with IP Prefixes . . . . . . . . . . . . 90 - A.9. Destination NAT . . . . . . . . . . . . . . . . . . . . . 91 - A.10. Customer-side Translator (CLAT) . . . . . . . . . . . . . 94 - A.11. IPv6 Network Prefix Translation (NPTv6) . . . . . . . . . 94 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 97 + Translation (EAM SIIT) . . . . . . . . . . . . . . . . . 85 + A.7. Static Mappings with Port Ranges . . . . . . . . . . . . 88 + A.8. Static Mappings with IP Prefixes . . . . . . . . . . . . 89 + A.9. Destination NAT . . . . . . . . . . . . . . . . . . . . . 90 + A.10. Customer-side Translator (CLAT) . . . . . . . . . . . . . 93 + A.11. IPv6 Network Prefix Translation (NPTv6) . . . . . . . . . 93 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 96 1. Introduction This document defines a data model for Network Address Translation (NAT) and Network Prefix Translation (NPT) capabilities using the YANG data modeling language [RFC7950]. Traditional NAT is defined in [RFC2663], while Carrier Grade NAT (CGN) is defined in [RFC6888]. Unlike traditional NAT, the CGN is used to optimize the usage of global IP address space at the scale of @@ -199,25 +199,25 @@ Datastore Architecture (NMDA). The meaning of the symbols in tree diagrams is defined in [RFC8340]. 2. Overview of the NAT YANG Data Model 2.1. Overview The NAT YANG module is designed to cover dynamic implicit mappings and static explicit mappings. The required functionality to instruct dynamic explicit mappings is defined in separate documents such as - [I-D.boucadair-pcp-yang]. Considerations about instructing explicit - dynamic means (e.g., [RFC6887], [RFC6736], or [RFC8045]) are out of - scope. As a reminder, REQ-9 of [RFC6888] requires that a CGN must - implement a protocol giving subscribers explicit control over NAT - mappings; that protocol should be the Port Control Protocol + [I-D.boucadair-pcp-yang]. Considerations about instructing by + explicit dynamic means (e.g., [RFC6887], [RFC6736], or [RFC8045]) are + out of scope. As a reminder, REQ-9 of [RFC6888] requires that a CGN + must implement a protocol giving subscribers explicit control over + NAT mappings; that protocol should be the Port Control Protocol [RFC6887]. A single NAT device can have multiple NAT instances; each of these instances can be provided with its own policies (e.g., be responsible for serving a group of hosts). This document does not make any assumption about how internal hosts or flows are associated with a given NAT instance. The NAT YANG module assumes that each NAT instance can be enabled/ disabled, be provisioned with a specific set of configuration data, @@ -841,22 +841,22 @@ | | | +--rw start-port-number? inet:port-number | | | +--rw end-port-number? inet:port-number | | +--rw src-transport-port | | | +--rw start-port-number? inet:port-number | | | +--rw end-port-number? inet:port-number | | +--rw status? boolean | +--rw all-algs-enable? boolean | +--rw notify-pool-usage | | {basic-nat44 or napt44 or nat64}? | | +--rw pool-id? uint32 - | | +--rw high-threshold? percent | | +--rw low-threshold? percent + | | +--rw high-threshold? percent | | +--rw notify-interval? uint32 | +--rw external-realm | +--rw (realm-type)? | +--:(interface) | +--rw external-interface? if:interface-ref +--rw mapping-limits {napt44 or nat64}? | +--rw limit-subscribers? uint32 | +--rw limit-address-mappings? uint32 | +--rw limit-port-mappings? uint32 | +--rw limit-per-protocol* [protocol-id] @@ -962,47 +962,49 @@ | {napt44 or nat64}? | +--ro protocol-id uint8 | +--ro total? yang:gauge32 +--ro pools-stats {basic-nat44 or napt44 or nat64}? +--ro addresses-allocated? yang:gauge32 +--ro addresses-free? yang:gauge32 +--ro ports-stats {napt44 or nat64}? | +--ro ports-allocated? yang:gauge32 | +--ro ports-free? yang:gauge32 +--ro per-pool-stats* [pool-id] - {basic-nat44 or napt44 or nat64}? + | {basic-nat44 or napt44 or nat64}? +--ro pool-id uint32 +--ro discontinuity-time yang:date-and-time +--ro pool-stats | +--ro addresses-allocated? yang:gauge32 | +--ro addresses-free? yang:gauge32 +--ro port-stats {napt44 or nat64}? +--ro ports-allocated? yang:gauge32 +--ro ports-free? yang:gauge32 notifications: +---n nat-pool-event {basic-nat44 or napt44 or nat64}? | +--ro id -> /nat/instances/instance/id | +--ro policy-id? | | -> /nat/instances/instance/policy/id - | +--ro pool-id leafref + | +--ro pool-id + | | -> /nat/instances/instance/policy/ + | | external-ip-address-pool/pool-id | +--ro notify-pool-threshold percent +---n nat-instance-event {basic-nat44 or napt44 or nat64}? +--ro id | -> /nat/instances/instance/id +--ro notify-subscribers-threshold? uint32 +--ro notify-addresses-threshold? percent +--ro notify-ports-threshold? percent 3. NAT YANG Module - file "ietf-nat@2018-06-28.yang" + file "ietf-nat@2018-09-27.yang" module ietf-nat { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-nat"; prefix "nat"; import ietf-inet-types { prefix inet; reference "Section 4 of RFC 6991"; @@ -1057,24 +1061,23 @@ 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 (http://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 2018-06-28 { + revision 2018-09-27 { description "Initial revision."; - reference "RFC XXXX: A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT)"; } /* * Definitions */ typedef percent { @@ -1259,21 +1262,21 @@ reference "RFC 6296: IPv6-to-IPv6 Network Prefix Translation"; } /* * Grouping */ grouping port-number { description - "Individual port or a range of ports. + "An individual port number or a range of ports. When only start-port-number is present, it represents a single port number."; leaf start-port-number { type inet:port-number; description "Beginning of the port range."; reference "Section 3.2.9 of RFC 8045."; } @@ -1289,25 +1292,25 @@ } description "End of the port range."; reference "Section 3.2.10 of RFC 8045."; } } grouping port-set { description - "Indicates a set of ports. + "Indicates a set of port numbers. It may be a simple port range, or use the Port Set ID (PSID) algorithm to represent a range of transport layer - ports which will be used by a NAPT."; + port numbers which will be used by a NAPT."; choice port-type { default port-range; description "Port type: port-range or port-set-algo."; case port-range { uses port-number; } @@ -1316,21 +1319,21 @@ type uint8 { range 0..15; } description "The number of offset bits (a.k.a., 'a' bits). Specifies the numeric value for the excluded port range/offset bits. - Allowed values are between 0 and 15 "; + Allowed values are between 0 and 15."; reference "Section 5.1 of RFC 7597"; } leaf psid-len { type uint8 { range 0..15; } mandatory true; @@ -1360,21 +1363,21 @@ "Section 7597: Mapping of Address and Port with Encapsulation (MAP-E)"; } } grouping mapping-entry { description "NAT mapping entry. If an attribute is not stored in the mapping/session table, - this means the corresponding fields of a packet that + this means the corresponding field of a packet that matches this entry is not rewritten by the NAT or this information is not required for NAT filtering purposes."; leaf index { type uint32; description "A unique identifier of a mapping entry. This identifier can be automatically assigned by the NAT instance or be explicitly configured."; } @@ -1396,44 +1399,45 @@ enum "dynamic-explicit" { description "This mapping is created as a result of an explicit request, e.g., a PCP message."; } } description "Indicates the type of a mapping entry. E.g., - a mapping can be: static, implicit dynamic + a mapping can be: static, implicit dynamic, or explicit dynamic."; } leaf transport-protocol { type uint8; description "Upper-layer protocol associated with this mapping. - Values are taken from the IANA protocol registry. + Values are taken from the IANA protocol registry:: + https://www.iana.org/assignments/protocol-numbers/ + protocol-numbers.xhtml For example, this field contains 6 for TCP, 17 for UDP, 33 for DCCP, or 132 for SCTP. If this leaf is not instantiated, then the mapping applies to any protocol."; } leaf internal-src-address { type inet:ip-prefix; description "Corresponds to the source IPv4/IPv6 address/prefix - of the packet received on an internal - interface."; + of the packet received on an internal interface."; } container internal-src-port { description "Corresponds to the source port of the packet received on an internal interface. It is used also to indicate the internal source ICMP identifier. @@ -1464,21 +1468,21 @@ leaf internal-dst-address { type inet:ip-prefix; description "Corresponds to the destination IP address/prefix of the packet received on an internal interface of the NAT. For example, some NAT implementations support the translation of both source and destination - addresses and ports, sometimes referred to + addresses and port numbers, sometimes referred to as 'Twice NAT'."; } container internal-dst-port { description "Corresponds to the destination port of the IP packet received on the internal interface. It is used also to include the internal destination ICMP identifier."; @@ -1620,41 +1625,34 @@ description "List of supported protocols."; leaf protocol-id { type uint8; mandatory true; description "Upper-layer protocol associated with a mapping. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml + Values are taken from the IANA protocol registry. For example, this field contains 6 for TCP, 17 for UDP, 33 for DCCP, or 132 for SCTP."; } leaf protocol-name { type string; description "The name of the Upper-layer protocol associated with this mapping. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml - For example, TCP, UDP, DCCP, and SCTP."; } - } leaf restricted-port-support { type boolean; description "Indicates source port NAT restriction support."; reference "RFC 7596: Lightweight 4over6: An Extension to the Dual-Stack Lite Architecture."; } @@ -2173,39 +2168,32 @@ the translator. TCP and UDP are supported by default."; leaf protocol-id { type uint8; mandatory true; description "Upper-layer protocol associated with this mapping. - Values are taken from the IANA protocol registry: - - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml + Values are taken from the IANA protocol registry. For example, this field contains 6 for TCP, 17 for UDP, 33 for DCCP, or 132 for SCTP."; } leaf protocol-name { type string; description "The name of the Upper-layer protocol associated with this mapping. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml - For example, TCP, UDP, DCCP, and SCTP."; } } leaf subscriber-mask-v6 { type uint8 { range "0 .. 128"; } description @@ -2588,23 +2575,21 @@ type inet:port-number; description "A port number."; } leaf protocol { type uint8; description "Upper-layer protocol associated with this port. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml. + Values are taken from the IANA protocol registry. If no protocol is indicated, this means 'any protocol'."; } leaf timeout { type uint32; units "seconds"; mandatory true; description @@ -2629,33 +2614,21 @@ between old and new mappings and sessions. It ensures that all established sessions are broken instead of redirected to a different peer."; reference "REQ#8 of RFC 6888."; } leaf hold-down-max { type uint32; description - "Maximum ports in the Hold down timer pool. - - Ports in the hold down pool are not reassigned - until hold-down-timeout expires. - - The length of time and the maximum - number of ports in this state must be - configurable by the administrator. - This is necessary in order - to prevent collisions between old - and new mappings and sessions. It ensures - that all established sessions are broken - instead of redirected to a different peer."; + "Maximum ports in the hold down port pool."; reference "REQ#8 of RFC 6888."; } } leaf fragments-limit{ when "../fragment-behavior='out-of-order'"; type uint32; description "Limits the number of out of order fragments that can @@ -2700,67 +2674,71 @@ leaf status { type boolean; description "Enable/disable the ALG."; } } leaf all-algs-enable { type boolean; description - "Enable/disable all ALGs. + "Disable/enable all ALGs. When specified, this parameter overrides the one that may be indicated, eventually, by the 'status' of an individual ALG."; } container notify-pool-usage { if-feature "basic-nat44 or napt44 or nat64"; description "Notification of pool usage when certain criteria are met."; leaf pool-id { type uint32; description "Pool-ID for which the notification criteria is defined"; } - leaf high-threshold { + leaf low-threshold { type percent; description - "Notification must be generated when the defined high + "Notification must be generated when the defined low threshold is reached. For example, if a notification is required when the - pool utilization reaches 90%, this configuration - parameter must be set to 90. + pool utilization reaches below 10%, this + configuration parameter must be set to 10. - 0% indicates that no high threshold is enabled."; + 0% indicates that low-threshold notification is + disabled."; } - leaf low-threshold { + leaf high-threshold { type percent; - must ". >= ../high-threshold" { + must ". >= ../low-threshold" { error-message - "The upper port number must be greater than or - equal to lower port number."; + "The high threshold must be greater than or equal + to the low threshold."; } description - "Notification must be generated when the defined low + "Notification must be generated when the defined high threshold is reached. For example, if a notification is required when the - pool utilization reaches below 10%, this - configuration parameter must be set to 10"; + pool utilization reaches 90%, this configuration + parameter must be set to 90. + + Setting the same value as low-threshold is equivalent + to disabling high-threshold notification."; } leaf notify-interval { type uint32 { range "1 .. 3600"; } units "seconds"; default '20'; description "Minimum number of seconds between successive @@ -2844,27 +2822,26 @@ description "Configure limits per transport protocol"; leaf protocol-id { type uint8; mandatory true; description "Upper-layer protocol. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml + Values are taken from the IANA protocol registry. For example, this field contains 6 for TCP, 17 for UDP, 33 for DCCP, or 132 for SCTP."; } + leaf limit { type uint32; description "Maximum number of protocol-specific NAT mappings per instance."; } } } container connection-limits { @@ -2894,32 +2871,30 @@ key protocol-id; description "Configure limits per transport protocol"; leaf protocol-id { type uint8; mandatory true; description "Upper-layer protocol. - Values are taken from the IANA protocol registry: - https://www.iana.org/assignments/protocol-numbers/ - protocol-numbers.xhtml + Values are taken from the IANA protocol registry. For example, this field contains 6 for TCP, 17 for UDP, 33 for DCCP, or 132 for SCTP."; } leaf limit { type uint32; description - "Rate-limit the number of protocol-specific mappings + "Limit the number of protocol-specific mappings and sessions per instance."; } } } container notification-limits { description "Sets notification limits."; leaf notify-interval { if-feature "basic-nat44 or napt44 or nat64"; @@ -3484,22 +3462,22 @@ This document requests IANA to register the following YANG module in the "YANG Module Names" registry [RFC7950]. name: ietf-nat namespace: urn:ietf:params:xml:ns:yang:ietf-nat prefix: nat reference: RFC XXXX 6. Acknowledgements - Many thanks to Dan Wing, Tianran Zhou, Tom Petch, and Warren Kumari - for the review. + Many thanks to Dan Wing, Tianran Zhou, Tom Petch, Warren Kumari, and + Benjamin Kaduk for the review. Thanks to Juergen Schoenwaelder for the comments on the YANG structure and the suggestion to use NMDA. Mahesh Jethanandani provided useful comments. Thanks to Lee Howard and Jordi Palet for the CLAT comments, Fred Baker for the NPTv6 comments, Tore Anderson for EAM SIIT review, and Kristian Poscic for the CGN review. Special thanks to Maros Marsalek and Marek Gradzki for sharing their @@ -4089,21 +4068,21 @@ 192.0.2.224/31 64:ff9b::/127 - EAMs may be enabled jointly with statefull NAT64. This example shows + EAMs may be enabled jointly with stateful NAT64. This example shows a NAT64 function that supports static mappings: nat64 true