idnits 2.17.1 draft-schoenw-netmod-yang-pattern-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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 23, 2014) is 3565 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder 3 Internet-Draft Jacobs University 4 Intended status: Standards Track M. Bjorklund 5 Expires: January 24, 2015 Tail-f Systems 6 July 23, 2014 8 A Collection of YANG Design Patterns 9 draft-schoenw-netmod-yang-pattern-00 11 Abstract 13 YANG is a data modeling language used to model configuration and 14 state data, remote procedure calls and notifications. This memo 15 documents a number of YANG design patterns. These design patterns 16 aim at providing general reusable solutions to commonly occurring 17 problems in the design of YANG data models. 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 http://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 24, 2015. 36 Copyright Notice 38 Copyright (c) 2014 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Listening Endpoints . . . . . . . . . . . . . . . . . . . . . 2 55 2.1. Pattern . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.3. Design Background . . . . . . . . . . . . . . . . . . . . 5 58 3. Outbound Connections . . . . . . . . . . . . . . . . . . . . 6 59 3.1. Pattern . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.3. Design Background . . . . . . . . . . . . . . . . . . . . 9 62 4. Presence Containers and Enabled Leafs . . . . . . . . . . . . 9 63 4.1. Pattern . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 4.3. Design Background . . . . . . . . . . . . . . . . . . . . 10 66 5. Config vs. Operational State . . . . . . . . . . . . . . . . 11 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 68 7. Informative References . . . . . . . . . . . . . . . . . . . 11 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 YANG is a data modeling language used to model configuration and 74 state data, remote procedure calls and notifications [RFC6020]. A 75 YANG design pattern is a general reusable solution to a commonly 76 occurring problem in the design of YANG data models. The aim of this 77 memo is to document some of the design patterns that have been found 78 useful and to also capture the reasoning behind the design pattern. 80 This collection of design pattern is intended to complement the 81 general usage guidelines documented in [RFC6087]. Some of the 82 examples may refer to common data types defined in [RFC6991]. 84 2. Listening Endpoints 86 A common problem is to model configuration of the endpoints a certain 87 application or service is listening on. 89 2.1. Pattern 91 The best current practice design pattern looks like this: 93 list listen { 94 key name; 96 leaf name { 97 type string; 98 description 99 "An arbitrary name for the listen endpoint."; 100 } 102 choice transport { 103 mandatory true; 104 case PROTOCOL { 105 container PROTOCOL { 106 // protocol specific endpoint information, for example: 107 leaf address { 108 type inet:ip-host; 109 mandatory true; 110 } 111 leaf port { 112 type inet:port-number; 113 default DEFPORT; 114 } 115 } 116 } 117 } 118 } 120 The PROTOCOL cases may designate a transport layer protocol (e.g., 121 tcp or sctp) or they may designate higher layer secure transports 122 (e.g., tls). The DEFPORT indicates a default port number that is 123 used if no explicit value is provided. 125 2.2. Example 127 Below is an example for the configuration of an HTTP server. 129 list listen { 130 key name; 131 leaf name { 132 type string; 133 description 134 "An arbitrary name for the listen endpoint."; 135 } 136 choice transport { 137 mandatory true; 138 case tcp { 139 container tcp { 140 leaf address { 141 type inet:ip-host; 142 mandatory true; 143 } 144 leaf port { 145 type inet:port-number; 146 default 80; 147 } 148 } 149 } 150 case tls { 151 container tls { 152 leaf address { 153 type inet:ip-host; 154 mandatory true; 155 } 156 leaf port { 157 type inet:port-number; 158 default 443; 159 } 160 } 161 } 162 } 163 } 165 This leads to XML configurations of the following form: 167 168 tcp-any-ipv6-default-port 169 170
::
171 172 173 174 tcp-any-ipv6-port-8080 175 176
::
177 8080 178 179 180 181 tls-any-ipv4-port-4443 182 183
0.0.0.0
184 4443 185 186 188 2.3. Design Background 190 Using a name leaf as the list key makes the endpoints extensible 191 since the name does not establish any constraints such as all IP 192 addresses must be unique. Furthermore, using names enables future 193 extensions dealing with multiple routing instances (where identical 194 IP addresses may be assigned to different routing instances) or where 195 link-local addresses are used on different explicitly identified 196 interfaces. 198 Alternatives that have been considered but found too limiting: 200 container listen { 201 leaf address { 202 type inet:ip-host; 203 mandatory true; 204 } 205 leaf port { 206 type inet:port-number; 207 mandatory true; 208 } 209 } 211 Using a simple container prevents the configuration of multiple 212 listening endpoints for a given service. 214 list listen { 215 key address; 216 leaf address { 217 type inet:ip-host; 218 } 219 leaf port { 220 type inet:port-number; 221 } 222 } 224 This alternative does not allow to configure the service on two 225 different ports on the same IP address. It also does not allow to 226 configure the same IP address with extensions such as support for 227 multiple routing instances. Furthermore, this configuration is not 228 extensible to support additional future transports. 230 container listen { 231 list PROTOCOL { 232 key name; 233 leaf name { 234 type string; 235 } 236 leaf ip { 237 type inet:ip-host; 238 mandatory true; 239 } 240 leaf port { 241 type inet:port-number; 242 default DEFPORT; 243 } 244 } 245 // ... 246 } 248 This solution uses several protocol specific lists instead of using a 249 choice in the common list. This has the disadvantage that it is not 250 possible to generically refer to a listening endpoint, e.g., using a 251 simple leafref. Furthermore, the lists mandate a partial order in 252 which listening endpoints appear on configurations. By using a 253 single list, entries for endpoints using different protocols can be 254 ordered arbitrarily. 256 3. Outbound Connections 258 For certain serives (like for example a DNS resolver), it is 259 necessary to configure to which endpoint a service should connect to. 260 In many cases, a service can be provided over multiple transport 261 protocols and it is (a) possible that additional transports are added 262 over time and (b) that transports require additional information to 263 identify an endpoint. Furthermore, it is often desirable to 264 provision multiple endpoints in order to provide fallback options. 266 3.1. Pattern 268 The best current practice design pattern looks like this: 270 list server { 271 key name; 272 ordered-by user; 274 leaf name { 275 type string; 276 description 277 "An arbitrary name for the endpoint to connect to."; 278 } 280 choice transport { 281 mandatory true; 282 case PROTOCOL { 283 container PROTOCOL { 284 // protocol specific endpoint information, for example: 285 leaf address { 286 type inet:ip-host; 287 mandatory true; 288 } 289 leaf port { 290 type inet:port-number; 291 default DEFPORT; 292 } 293 } 294 } 295 } 296 } 298 The PROTOCOL cases may designate a transport layer protocol (e.g., 299 tcp or sctp) or they may designate higher layer secure transports 300 (e.g., tls). The DEFPORT indicates a default port number that is 301 used if no explicit value is provided. 303 3.2. Example 304 list server { 305 key name; 306 ordered-by user; 308 leaf name { 309 type string; 310 description 311 "An arbitrary name for the endpoint to connect to."; 312 } 314 choice transport { 315 mandatory true; 316 case tcp { 317 container tcp { 318 leaf address { 319 type inet:ip-host; 320 mandatory true; 321 } 322 leaf port { 323 type inet:port-number; 324 default 80; 325 } 326 } 327 } 328 case tls { 329 container tls { 330 leaf address { 331 type inet:ip-host; 332 mandatory true; 333 } 334 leaf port { 335 type inet:port-number; 336 default 443; 337 } 338 } 339 } 340 } 341 } 343 This leads to XML configurations of the following form: 345 346 foo-over-tls 347 348
foo.example.org
349 350 351 352 foo-over-tcp-port-1224 353 354
foo.example.org
355 1234 356 357 359 3.3. Design Background 361 Using a name leaf as the list key makes the endpoints extensible 362 since the name does not establish any constraints such as all IP 363 addresses must be unique. Furthermore, using names enables future 364 extensions dealing with multiple routing instances (where identical 365 IP addresses may be assigned to different routing instances). 367 The pattern allows to provision fallback endpoints (note that the 368 list is ordered-by user) and it allows new transports to be augmented 369 into the data model by adding additional choices. 371 4. Presence Containers and Enabled Leafs 373 It is sometimes desirable to have a container representing a certain 374 functionality that can be enabled or disabled. In some situations, 375 the the functionality is by default enabled and the container should 376 be present while in other situations the functionality is by default 377 disabled and the container should not be present. 379 4.1. Pattern 381 For a container modeling an optional functionality that should be 382 enabled by default, the following pattern can be used: 384 container FUNCTION { 385 leaf enabled { 386 type boolean; 387 default "true"; 388 } 389 } 391 This container will always exist and the boolean enabled leaf 392 defaults to true. Hence, the FUNCTION will by default be enabled. 394 For a container modeling an optional functionality that should be 395 disabled by default, the following pattern can be used: 397 container FUNCTION { 398 presence "Enabled FUNCTION unless the 'enabled' leaf 399 (which defaults to 'true') is set to 'false'"; 400 leaf enabled { 401 type boolean; 402 default "true"; 403 } 404 } 406 This presence container may be absent. If it does not exist, the 407 functionality is disabled. If it exists, then the functionality will 408 be enabled. 410 4.2. Example 412 The following example can be found in the system data model. 414 container ntp { 415 if-feature ntp; 416 presence 417 "Enables the NTP client unless the 'enabled' leaf 418 (which defaults to 'true') is set to 'false'"; 419 description 420 "Configuration of the NTP client."; 422 leaf enabled { 423 type boolean; 424 default true; 425 description 426 "Indicates that the system should attempt 427 to synchronize the system clock with an 428 NTP server from the 'ntp/server' list."; 429 } 430 } 432 4.3. Design Background 434 In both pattern, the 'enabled' leaf has been designed to be largely 435 invisible in trim and explicit with-defaults mode [RFC6243]. In the 436 first case, since the non-presence container is always visible and 437 the functionality by default enabled, the 'enabled' leaf will not 438 show up in a data tree. In the second case, since the presence 439 container controls whether the 'enabled' leaf exists, it is by 440 default not present even though the default is true. Once the 441 presence container has been created, the 'enabled' leaf will still be 442 invisible due to its default value. 444 5. Config vs. Operational State 446 [Should we document what we currently have?] 448 6. Security Considerations 450 TBD 452 7. Informative References 454 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 455 Network Configuration Protocol (NETCONF)", RFC 6020, 456 October 2010. 458 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 459 Data Model Documents", RFC 6087, January 2011. 461 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 462 NETCONF", RFC 6243, June 2011. 464 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 465 July 2013. 467 Authors' Addresses 469 Juergen Schoenwaelder 470 Jacobs University 472 Email: j.schoenwaelder@jacobs-university.de 474 Martin Bjorklund 475 Tail-f Systems 477 Email: mbj@tail-f.com