[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                   J. Schoenwaelder
Internet-Draft                                         Jacobs University
Intended status: Standards Track                            M. Bjorklund
Expires: January 24, 2015                                 Tail-f Systems
                                                           July 23, 2014


                  A Collection of YANG Design Patterns
                  draft-schoenw-netmod-yang-pattern-00

Abstract

   YANG is a data modeling language used to model configuration and
   state data, remote procedure calls and notifications.  This memo
   documents a number of YANG design patterns.  These design patterns
   aim at providing general reusable solutions to commonly occurring
   problems in the design of YANG data models.

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 http://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 January 24, 2015.

Copyright Notice

   Copyright (c) 2014 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
   (http://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 Simplified BSD License text as described in Section 4.e of




Schoenwaelder & BjorklunExpires January 24, 2015                [Page 1]


Internet-Draft             YANG Design Pattern                 July 2014


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Listening Endpoints . . . . . . . . . . . . . . . . . . . . .   2
     2.1.  Pattern . . . . . . . . . . . . . . . . . . . . . . . . .   2
     2.2.  Example . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  Design Background . . . . . . . . . . . . . . . . . . . .   5
   3.  Outbound Connections  . . . . . . . . . . . . . . . . . . . .   6
     3.1.  Pattern . . . . . . . . . . . . . . . . . . . . . . . . .   7
     3.2.  Example . . . . . . . . . . . . . . . . . . . . . . . . .   7
     3.3.  Design Background . . . . . . . . . . . . . . . . . . . .   9
   4.  Presence Containers and Enabled Leafs . . . . . . . . . . . .   9
     4.1.  Pattern . . . . . . . . . . . . . . . . . . . . . . . . .   9
     4.2.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  10
     4.3.  Design Background . . . . . . . . . . . . . . . . . . . .  10
   5.  Config vs. Operational State  . . . . . . . . . . . . . . . .  11
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
   7.  Informative References  . . . . . . . . . . . . . . . . . . .  11
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction

   YANG is a data modeling language used to model configuration and
   state data, remote procedure calls and notifications [RFC6020].  A
   YANG design pattern is a general reusable solution to a commonly
   occurring problem in the design of YANG data models.  The aim of this
   memo is to document some of the design patterns that have been found
   useful and to also capture the reasoning behind the design pattern.

   This collection of design pattern is intended to complement the
   general usage guidelines documented in [RFC6087].  Some of the
   examples may refer to common data types defined in [RFC6991].

2.  Listening Endpoints

   A common problem is to model configuration of the endpoints a certain
   application or service is listening on.

2.1.  Pattern

   The best current practice design pattern looks like this:







Schoenwaelder & BjorklunExpires January 24, 2015                [Page 2]


Internet-Draft             YANG Design Pattern                 July 2014


     list listen {
       key name;

       leaf name {
         type string;
         description
           "An arbitrary name for the listen endpoint.";
       }

       choice transport {
         mandatory true;
         case PROTOCOL {
           container PROTOCOL {
              // protocol specific endpoint information, for example:
              leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default DEFPORT;
             }
           }
         }
       }
     }

   The PROTOCOL cases may designate a transport layer protocol (e.g.,
   tcp or sctp) or they may designate higher layer secure transports
   (e.g., tls).  The DEFPORT indicates a default port number that is
   used if no explicit value is provided.

2.2.  Example

   Below is an example for the configuration of an HTTP server.
















Schoenwaelder & BjorklunExpires January 24, 2015                [Page 3]


Internet-Draft             YANG Design Pattern                 July 2014


     list listen {
       key name;
       leaf name {
         type string;
         description
           "An arbitrary name for the listen endpoint.";
       }
       choice transport {
         mandatory true;
         case tcp {
           container tcp {
             leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default 80;
             }
           }
         }
         case tls {
           container tls {
             leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default 443;
             }
           }
         }
       }
     }

   This leads to XML configurations of the following form:














Schoenwaelder & BjorklunExpires January 24, 2015                [Page 4]


Internet-Draft             YANG Design Pattern                 July 2014


     <listen>
       <name>tcp-any-ipv6-default-port</name>
       <tcp>
         <address>::</address>
       </tcp>
     </listen>
     <listen>
       <name>tcp-any-ipv6-port-8080</name>
       <tcp>
         <address>::</address>
         <port>8080</port>
       </tcp>
     </listen>
     <listen>
       <name>tls-any-ipv4-port-4443</name>
       <tls>
         <address>0.0.0.0</address>
         <port>4443</port>
       </tls>
     </listen>

2.3.  Design Background

   Using a name leaf as the list key makes the endpoints extensible
   since the name does not establish any constraints such as all IP
   addresses must be unique.  Furthermore, using names enables future
   extensions dealing with multiple routing instances (where identical
   IP addresses may be assigned to different routing instances) or where
   link-local addresses are used on different explicitly identified
   interfaces.

   Alternatives that have been considered but found too limiting:

     container listen {
       leaf address {
         type inet:ip-host;
         mandatory true;
       }
       leaf port {
         type inet:port-number;
         mandatory true;
       }
     }

   Using a simple container prevents the configuration of multiple
   listening endpoints for a given service.





Schoenwaelder & BjorklunExpires January 24, 2015                [Page 5]


Internet-Draft             YANG Design Pattern                 July 2014


     list listen {
       key address;
       leaf address {
         type inet:ip-host;
       }
       leaf port {
         type inet:port-number;
       }
     }

   This alternative does not allow to configure the service on two
   different ports on the same IP address.  It also does not allow to
   configure the same IP address with extensions such as support for
   multiple routing instances.  Furthermore, this configuration is not
   extensible to support additional future transports.

     container listen {
       list PROTOCOL {
         key name;
         leaf name {
           type string;
         }
         leaf ip {
           type inet:ip-host;
           mandatory true;
         }
         leaf port {
           type inet:port-number;
           default DEFPORT;
         }
       }
       // ...
     }

   This solution uses several protocol specific lists instead of using a
   choice in the common list.  This has the disadvantage that it is not
   possible to generically refer to a listening endpoint, e.g., using a
   simple leafref.  Furthermore, the lists mandate a partial order in
   which listening endpoints appear on configurations.  By using a
   single list, entries for endpoints using different protocols can be
   ordered arbitrarily.

3.  Outbound Connections

   For certain serives (like for example a DNS resolver), it is
   necessary to configure to which endpoint a service should connect to.
   In many cases, a service can be provided over multiple transport
   protocols and it is (a) possible that additional transports are added



Schoenwaelder & BjorklunExpires January 24, 2015                [Page 6]


Internet-Draft             YANG Design Pattern                 July 2014


   over time and (b) that transports require additional information to
   identify an endpoint.  Furthermore, it is often desirable to
   provision multiple endpoints in order to provide fallback options.

3.1.  Pattern

   The best current practice design pattern looks like this:

     list server {
       key name;
       ordered-by user;

       leaf name {
         type string;
         description
           "An arbitrary name for the endpoint to connect to.";
       }

       choice transport {
         mandatory true;
         case PROTOCOL {
           container PROTOCOL {
             // protocol specific endpoint information, for example:
             leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default DEFPORT;
             }
           }
         }
       }
     }

   The PROTOCOL cases may designate a transport layer protocol (e.g.,
   tcp or sctp) or they may designate higher layer secure transports
   (e.g., tls).  The DEFPORT indicates a default port number that is
   used if no explicit value is provided.

3.2.  Example









Schoenwaelder & BjorklunExpires January 24, 2015                [Page 7]


Internet-Draft             YANG Design Pattern                 July 2014


     list server {
       key name;
       ordered-by user;

       leaf name {
         type string;
         description
           "An arbitrary name for the endpoint to connect to.";
       }

       choice transport {
         mandatory true;
         case tcp {
           container tcp {
             leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default 80;
             }
           }
         }
         case tls {
           container tls {
             leaf address {
               type inet:ip-host;
               mandatory true;
             }
             leaf port {
               type inet:port-number;
               default 443;
             }
           }
         }
       }
     }

   This leads to XML configurations of the following form:











Schoenwaelder & BjorklunExpires January 24, 2015                [Page 8]


Internet-Draft             YANG Design Pattern                 July 2014


     <server>
       <name>foo-over-tls</name>
       <tls>
         <address>foo.example.org</address>
       </tls>
     </server>
     <server>
       <name>foo-over-tcp-port-1224</name>
       <tcp>
         <address>foo.example.org</address>
         <port>1234</port>
       </tcp>
     </server>

3.3.  Design Background

   Using a name leaf as the list key makes the endpoints extensible
   since the name does not establish any constraints such as all IP
   addresses must be unique.  Furthermore, using names enables future
   extensions dealing with multiple routing instances (where identical
   IP addresses may be assigned to different routing instances).

   The pattern allows to provision fallback endpoints (note that the
   list is ordered-by user) and it allows new transports to be augmented
   into the data model by adding additional choices.

4.  Presence Containers and Enabled Leafs

   It is sometimes desirable to have a container representing a certain
   functionality that can be enabled or disabled.  In some situations,
   the the functionality is by default enabled and the container should
   be present while in other situations the functionality is by default
   disabled and the container should not be present.

4.1.  Pattern

   For a container modeling an optional functionality that should be
   enabled by default, the following pattern can be used:

     container FUNCTION {
       leaf enabled {
         type boolean;
         default "true";
       }
     }

   This container will always exist and the boolean enabled leaf
   defaults to true.  Hence, the FUNCTION will by default be enabled.



Schoenwaelder & BjorklunExpires January 24, 2015                [Page 9]


Internet-Draft             YANG Design Pattern                 July 2014


   For a container modeling an optional functionality that should be
   disabled by default, the following pattern can be used:

     container FUNCTION {
       presence "Enabled FUNCTION unless the 'enabled' leaf
                 (which defaults to 'true') is set to 'false'";
       leaf enabled {
         type boolean;
         default "true";
       }
     }

   This presence container may be absent.  If it does not exist, the
   functionality is disabled.  If it exists, then the functionality will
   be enabled.

4.2.  Example

   The following example can be found in the system data model.

     container ntp {
       if-feature ntp;
       presence
         "Enables the NTP client unless the 'enabled' leaf
          (which defaults to 'true') is set to 'false'";
       description
         "Configuration of the NTP client.";

       leaf enabled {
         type boolean;
         default true;
         description
           "Indicates that the system should attempt
            to synchronize the system clock with an
            NTP server from the 'ntp/server' list.";
       }
     }

4.3.  Design Background

   In both pattern, the 'enabled' leaf has been designed to be largely
   invisible in trim and explicit with-defaults mode [RFC6243].  In the
   first case, since the non-presence container is always visible and
   the functionality by default enabled, the 'enabled' leaf will not
   show up in a data tree.  In the second case, since the presence
   container controls whether the 'enabled' leaf exists, it is by
   default not present even though the default is true.  Once the




Schoenwaelder & BjorklunExpires January 24, 2015               [Page 10]


Internet-Draft             YANG Design Pattern                 July 2014


   presence container has been created, the 'enabled' leaf will still be
   invisible due to its default value.

5.  Config vs. Operational State

     [Should we document what we currently have?]

6.  Security Considerations

     TBD

7.  Informative References

   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", RFC 6020,
              October 2010.

   [RFC6087]  Bierman, A., "Guidelines for Authors and Reviewers of YANG
              Data Model Documents", RFC 6087, January 2011.

   [RFC6243]  Bierman, A. and B. Lengyel, "With-defaults Capability for
              NETCONF", RFC 6243, June 2011.

   [RFC6991]  Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
              July 2013.

Authors' Addresses

   Juergen Schoenwaelder
   Jacobs University

   Email: j.schoenwaelder@jacobs-university.de


   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com













Schoenwaelder & BjorklunExpires January 24, 2015               [Page 11]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/