Network Working GroupM. Bjorklund, Ed.
Internet-DraftTail-f Systems
Intended status: InformationalFebruary 18, 2008
Expires: August 21, 2008 


YANG's Compliance with Respect to Various Requirements Documents
draft-bjorklund-yang-requirements-00

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

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.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on August 21, 2008.

Copyright Notice

Copyright © The IETF Trust (2008).

Abstract

This draft addresses requirements for a NETCONF data modeling language and how the YANG Modeling Language proposes to fulfill these requirements or specifically chooses not to. Requirements have been gathered from multiple documents and each document's requirements are handled in a separate section in this draft.

This draft also explains some of the design choices behind YANG.

Table of Contents

1.  Introduction
2.  The case for YANG
    2.1.  YANG - Wir koennen nicht anders!
    2.2.  YANG - Solving "the configuration problem"
3.  Requirements
    3.1.  Requirements from draft-presuhn-rcdml-01
        3.1.1.  Agreed
        3.1.2.  "NOT Agreed" with which YANG complies
        3.1.3.  "NOT Agreed" with which YANG does not comply (or not determined)
    3.2.  Requirements from RFC 3139
    3.3.  Requirements from RFC 3216
        3.3.1.  Accepted objectives
        3.3.2.  Nice-to-have objectives
        3.3.3.  Rejected objectives
    3.4.  Requirements from draft-linowski-netconf-dml-requirements-00
4.  YANG DHCP Module
5.  IANA Considerations
6.  Security Considerations
7.  Contributors
8.  References
    8.1.  Normative References
    8.2.  Non-Normative References
§  Author's Address
§  Intellectual Property and Copyright Statements


1.  Introduction

This draft details YANG's [YANG] (Bjorklund, M., “YANG - A data modeling language for NETCONF,” February 2008.) compliance with respect to a list of requirements for a data modeling language for NETCONF. The requirements have been put together from multiple documents that represent the IETF's current collected understanding of what a data modeling language for NETCONF must be able to do.

2.  The case for YANG

On the last day of the 68th IETF in Prague, a small band of NETCONF veterans assembled over breakfast and talked about the need for a simple modeling language for NETCONF. This was an area where NETCONF was failing to make forward progress, putting the future of NETCONF at risk. We compared our experience implementing in-house tools for our proprietary NETCONF engines and found that we had all reached similar solutions to the problem. The areas of overlap and similarities were immense, and we began work on a proposal that built on our experiences, picking the "best of breed" feature from our existing solutions, and tailoring them into a consistent language that is as powerful as it is simple.

This document, together with the [YANG] (Bjorklund, M., “YANG - A data modeling language for NETCONF,” February 2008.) specification, explain the needs and benefits of this "second generation" data modeling language.

2.1.  YANG - Wir koennen nicht anders!

YANG is designed specifically for use with NETCONF. While it might be useful for data modeling in other contexts, that is not the focus of this work. Our perception is that there is a very serious problem to be solved: we have a protocol ([RFC4741] (Enns, R., “NETCONF Configuration Protocol,” December 2006.)) for configuration, but we have no standardized way to define the models for that which we are going to configure, much less models themselves. Without timely forward progress in this area, NETCONF cannot service the needs of the network management community, and will quickly move lose what momentum remains. YANG aims to fill that gap by providing NETCONF what the SMI ([RFC2578] (McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., “Structure of Management Information Version 2 (SMIv2),” April 1999.)) gives the SNMP-based framework.

YANG has a strong heritage. YANG is based on languages used actively for development of NETCONF-based management systems in products today. As such, the design of YANG is based heavily on requirements placed upon those languages by their users and the experience of writing NETCONF data models in the vendor-specific languages from which much of YANG was derived. Real world usage is the best way to understand requirements and YANG takes advantage of years of real world usage from these internal tools, building on their requirements and their solutions to complex issues in data modeling.

YANG is designed to give priority to data model readers. The readers and reviewers of data models need insight into the organization, constraints, and meaning of its elements. The reader of a YANG module can easily see the high-level view of the data model while seeing how the object will be encoded in NETCONF operations. While YANG models the data content, the XML rendering of this content is very apparent.

YANG has a history that demonstrates the need for a new language. During previous proprietary implementations that were input to YANG, developers realized that models written in existing languages (specifically XSD, RelaxNG) were very difficult both to read and write, so the languages were based on something "home grown" designed for the developers who would be writing models and implementing them on devices. Given that experience, YANG's syntax was chosen specifically for its readability, since YANG values the time and effort of the readers of models above those of modules writers and YANG tool-chain developers. Above all, the users of NETCONF models (operators) were given highest priority in YANG's design.

2.2.  YANG - Solving "the configuration problem"

NETCONF and YANG are all about solving "the configuration problem", a problem that is not simple. The history of network management (and configuration management in particular) over the last 20 years clearly demonstrates the industry's failure to provide interoperable, multi-vendor configuration tools. It is instructive to understand some of the factors that make configuration a difficult problem, as the modeling language for NETCONF should do all that it can to alleviate these difficulties.

In designing configuration for a complex device, you have a number of goals:

In striving for simplification, many of these goals are in conflict with one other. For example, in trying to be flexible, one must decide when an odd configuration is an error and when the user is just doing something clever (which may be an error, but is an intentional one).

In standardization, the goals are often completely different. Expressiveness and accuracy win over simplicity. A single complex method of configuration wins over a dual "common" and "advanced" approach. The model for a standard must be something that can support all platforms, which leads to complexity, and the translation between the standard's complex model and the unique abilities of individual platforms is non-trivial.

An example is packet filtering, where the device configuration is more often dictated by the hardware architecture and the layout of that hardware (in terms of where packets can be filtered, what can be filtered on, what can be done to them at that layer, and what resources are consumed) is often directly visible in the configuration in order for the customer to express their desired setup.

A standard, on the other hand, needs a model that is "bigger" than one vendor's solution, where any sort of filtering can be done at any place with any outcome without concern for resource impact. No vendor will implement such a model, and the translation between the model and the device configuration requires understanding the performance versus resource utilization tradeoffs that the customer is willing to make.

For example, some functionality may be available in hardware at wire rate, other in hardware at lower speed, other in dedicated CPUs, and still other in the main CPU. Choosing the proper filtering point is a matter of both the speed and abilities of that point, plus chip memory and other contention issues. And getting a correct assignment will still be wrong if it's not the assignment the customer wanted.

This translation must be performed in a way that avoids letting small changes in the configuration turn into large configuration changes on the device. This is not an easy problem, but is key to device-independent configuration.

The problem isn't getting a few knobs to configure basic functionality, but getting a solution that's complete enough to give folks sufficient faith to move toward it. If it solved 20% of the problem, it's worthless. When it solves 80-90% of the problem, it's interesting.

NETCONF gives us the ability to manipulate configuration in XML, which is a good first step. With YANG, we now have the ability to define that XML in a way that allows extensibility and the expression of device-specific content, which is a good second step. The next step will be a translation framework that allows robust translation between a standard view and a device-specific view.

3.  Requirements

The following sections address requirements from various internet drafts and RFCs. For each document, the requirements are named by section and title (if available) or with a short summary of the requirement. For a full explanation of the requirement, see the source document.

For each requirement, we state:

3.1.  Requirements from draft-presuhn-rcdml-01

[PRESUHN] (Presuhn, R., “Requirements for a Configuration Data Modeling Language,” February 2008.), "Requirements for a Configuration Data Modeling Language", has the following requirements. They are listed by section number in [PRESUHN] (Presuhn, R., “Requirements for a Configuration Data Modeling Language,” February 2008.) and divided into two lists. The first list is all of the requirements that the requirements design team reached rough consensus on. The second list is those where rough consensus was NOT reached. For both of these lists, YANG states its compliance with respect to the requirement and provides additional commentary as deemed necessary. The text explaining the requirements themselves are not reproduced here.

RFC 3139 and RFC 3216 Considerations are handled separately.

3.1.1.  Agreed

YANG complies with all Agreed requirements.

Supported with the "notification" statement.

  notification link-failure {
      description "A link failure has been detected";
      leaf if-index {
          type int32 { range "1 .. max"; }
      }
      leaf if-name {
          type keyref {
              path "/interfaces/interface/name";
          }
      }
  }

YANG does not impose any restrictions for partial locking.

The YANG specification explicitly details how all <edit-config> operations work for the data definition statements.

All YANG data definition statements define either configuration or non-configuration data, supporting the <get-config> and <get> operations of NETCONF.

New NETCONF operations, vendor-specific or standard, are defined with the "rpc" statement. This statement covers input parameters, the result and semantics of the operation.

  rpc activate-software-image {
      description "Activate a new software image "
                + "(upgrade or downgrade)";
      input {
          leaf image-name {
            description "Local file name of the incoming image";
              type string;
          }
      }
      output {
          leaf status {
              description "Status string returned by the new software";
              type string;
          }
      }
  }

Operations defined in YANG can be extended by vendors with extra information with the "augment" statement.

  augment /rpc/activate-software-image/input {
      vend1:custom-flag true;
  }

The "rpc" statement is clearly separated from the data definition statements in YANG.

The operation name appears as the argument to the "rpc" statement, while the input payload appears in the "input" statement. Output payload appears in the "output" statement.

YANG allows the user to define the error-app-tag and the error-message NETCONF elements both for common constraints like range and for specific constraints defined using the "must" statement.

  leaf cell-count {
      type uint32;
      must "ifType == 'atm'" {
          error-message "'cell-count' is only valid for ATM interfaces";
          error-app-tag invalid-interface-type;
      }
  }

NETCONF-specific error information (error-message and error-app-tag) can be assigned to statements that put syntactic and semantic restrictions on the data model.

YANG does not provide a mechanism to define mixed XML content.

The YANG syntax is similar to that of SMIng [RFC3780] (Strauss, F. and J. Schoenwaelder, “SMIng - Next Generation Structure of Management Information,” May 2004.) and programming languages like C and C++. This C-like syntax was chosen specifically for its readability and conciseness, since YANG values the time and effort of the readers of models above those of modules writers and YANG tool-chain developers.

YANG has a few, simple syntactical rules which are easy to parse for tools. YANG also supports an equivalent XML-based syntax called YIN, which can be used to feed into standard XML tools such as XSLT script.

All YANG statements are of the following format:

    stmt -> keyword argument? ( ';' | '{' stmt-list '}' )
    stmt-list -> null | stmt-list stmt

This simple syntax allows the creation of parsers using a trivial state machine, rather than needing traditional compiler tools.

YANG models are represented as text. They can be built in a normal editor, sent via email, saved in cvs or svn repositories, diffed, grepped, or handled in any manner used on MIBs.

YANG supports a string concatenation operator which can be used to split long strings into multiple lines, supporting inclusion of YANG model in 72 column RFCs. An example is the IPv4 regular expression:

  pattern
      '(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}'
    + '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])'
    + '(%[\p{N}\p{L}]+)?';

YANG supports the "organization", "contact", "revision", "description", and "reference" statements for modules.

  // Contents of "acme-system.yang"
  module acme-system {
      namespace "http://acme.example.com/system";
      prefix "acme";

      organization "ACME Inc.";
      contact "joe@acme.example.com";
      description
          "The module for entities implementing the ACME system.";

      revision 2007-06-09 {
          description "Initial revision.";
      }
      ...
  }

YANG is owned and defined by IETF. It depends on some W3C technologies - XML basics, namespaces - and IEEE data types.

YANG depends only on a limited set of stable external standards to avoid problems with future versions of these specifications e.g. XSD 1.1.

YANG has minimal dependencies on external standards. The exact revisions of the standards are specified in the YANG specification.

Because of its simple syntax, a YANG module is diff- and email-friendly.

  @@ -62,10 +62,12 @@
     }

     typedef direction-type {
  +    description "Which direction of traffic is requested?";
       type enumeration {
         enum ingress;
         enum egress;
         enum both;
  +      enum neither;
       }
     }

YANG supports Unicode text in the data model definitions.

YANG supports UTF-8. YANG modules are written in the UTF-8 [RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) character set.

While many YANG text statements ("description", "reference", etc) are targeted at the reader and implementer, not the end user, the reality is that these strings are commonly placed before users in generic browsers. Internationalization of these strings can be performed using extensions, such as:

    leaf trunk-status {
        type string;
        description "The status of the trunk";
        i18n:description "en_GB:The condition of the boot";
        i18n:description "sv_SE:Trunkens nuvarande tillstånd";
    }

YANG explicitly lists the app-tags and messages of generated messages, allowing applications to translate between the values sent over the wire and catalogs of localized messages.

YANG supports a flexible modularization mechanism. YANG structures data models into modules and submodules. A module can import data from other external modules, and include data from submodules. The hierarchy can be extended, allowing one module to add data nodes to the hierarchy defined in another module. This augmentation can be conditional, with new nodes to appearing only if certain conditions are met.

YANG supports reusable simple (scalar) types with the "typedef" statement, and reusable structures with the "grouping" statement.

  typedef percent {
      type uint16 {
          range "0 .. 100";
      }
      description "Percentage";
  }

  leaf completed {
      type percent;
  }

  grouping target {
      leaf address {
          type inet:ip-address;
          description "Target IP address";
      }
      leaf port {
          type inet:port-number;
          description "Target port number";
      }
  }

  container peer {
      container destination {
          uses target;
      }
  }

A published YANG module can be extended from another module with the "augment" statement. This statement allows for very flexible extensions, where the original module does not have to be explicitly designed for specific extensibility.

With the "augment" statement, YANG fully utilizes the flexible extensibility of XML with namespaces.

A module can extend the data model defined in another module using the "augment" statement. Augmentation allows flexible extensions to existing modules without forcing the original module to explicitly allow for such extensibility. Augmented nodes are encoded in the XML namespace of the augmenting module, avoiding ambiguity and conflicts.

In YANG modules, leafs can have default values. YANG supports NETCONF protocol extensions such as "with-defaults" which control how defaults are sent over the wire.

In YANG modules, leafs can have default values. Defaults need not be transmitted on the wire since both client and server understand the impact of such defaults.

YANG supports NETCONF protocol extensions such as "with-defaults" which control how defaults are sent over the wire.

Lists can be declared as "ordered-by user" which specifies that the order has semantic significance, or "ordered-by system" which specifies that the order of the list entries has no semantic meaning.

The ABNF grammar and general tokenization rules specifies what a valid module looks like on a syntactic level. The semantic meaning is defined in the description of the statements.

This is work to be done. Canonicalization of the XML follows the rules defined in [RFC3076] (Boyer, J., “Canonical XML Version 1.0,” March 2001.).

YANG supports models defined in UTF-8.

YANG supports the "description" statement as a way to describe additional semantics to a definition. The "description" statement is supported on almost all statements, including individual enumerated values and bits (which was a problem in SMI). Furthermore, the statement is supported in YANG extensions.

YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special requirements from the management information model. Most built-in types have a direct mapping to XSD types.

Non-YANG XML data is supported with the "anyxml" statement.

  anyxml contents {
      description "Contains the unfiltered contents of some XML thing";
  }

A list used for configuration data must have keys in YANG.

    list user {
        key "name";
        leaf name {
            type string;
        }
        leaf full-name {
            type string;
        }
        leaf class {
            type string;
        }
    }

The "keyref" statement is used to formally define 1:1 and 1:n relationships in YANG models. These formal machine readable relationships can cross module boundaries.

  notification link-failure {
      description "A link failure has been detected";
      leaf if-index {
          type int32 { range "1 .. max"; }
      }
      leaf if-name {
          type keyref {
              path "/interfaces/interface/name";
          }
      }
  }

YANG supports the definition of hierarchical data.

Each data object in a YANG module is either defined as configuration or non-configuration, with the "config" statement.

      leaf observed-speed {
          type uint32;
          config false;
      }

Constraints local to scalar objects are supported with restrictions on the type. YANG supports "range", "length" and "pattern" restrictions.

   type union {
      type int {
          range 0..15;
      }
      type string {
          length 5..10;
          pattern "full.*";
      }
  }

Uniqueness is controlled with the "unique" statement, as discussed in the next section.

A common type of constraint is uniqueness constraints, i.e. the ability to specify that within some context, the values of some objects must be unique across all instances.

YANG supports this with the "unique" statement.

  list server {
      key "name";
      unique "ip port";
      leaf name {
          type string;
      }
      leaf ip {
          type inet:ip-address;
      }
      leaf port {
          type inet:port-number;
      }
  }

YANG supports associating units with values or derived types with the "units" statement.

  leaf max-lease-time {
      type uint32;
      units seconds;
  }

The YANG language is versioned with the "yang-version" statement.

  yang-version 1;

A YANG module has a revision, and the revision number is reported as part of the schema discovery process.

  revision "2007-06-09" {
      description "Initial revision.";
  }

YANG uses the well-known STATUS clause from SMI, with the "status" statement. The meaning is the same as in the SMI.

  status deprecated;

YANG supports module revisions while allowing backwards compatibility. The rules controlling such changes remains work to be done.

In the current version of YANG, conformance is on the module level.

Support for finer-grained conformance is work to be done. In designing this feature, it is important to learn from the experience with AGENT-CAPABILITIES in SMIv2.

Since the conformance in YANG is on module level, a server that claims conformance to a module must implement the entire module.

YANG models can be translated to XSD or RelaxNG, if needed. The XSD translation is implemented in one open source tool. Since a YANG module contains much more information than the XML grammar supported by these languages, the transformation to standard XSD or RelaxNG will be lossy. As a simple example, the information if an object represents configuration can not be expressed in standard XSD and RelaxNG. Since both these languages support user-defined annotations, the missing information can be encoded in non-standard user-defined annotations.

3.1.2.  "NOT Agreed" with which YANG complies

YANG complies with the following "NOT Agreed" requirements.

There is currently one open-source tool available to validate YANG modules, and at least two more open-source tools are being worked upon.

YANG supports default values. Any leaf node can specify a static default using the "default" statement.

  default 1024;

We believe that there is a value in having formal descriptions of integrity constraints. One reason is that with formal descriptions, interoperability is easier to achieve. Another reason is that tools can reduce the implementation effort of data models. We also believe that there is a balance between the expressiveness and usefulness of formal descriptions - if the formal definition of a constraint is too complex to read, a textual description might be more appropriate.

YANG supports XPath based constraints. XPath is a fairly simple language (in its expressiveness), but covers many common use cases. More complex constraints are defined in description clauses.

      must "ifType != ethernet or " +
           "(ifType = ethernet and ifMTU = 1500)" {
          error-message "An ethernet MTU must be 1500";
      }

YANG supports formal referential integrity constraints with the "keyref" statement.

  leaf mgmt-interface {
      type keyref {
          path "../interface/name";
      }
  }

YANG supports user-defined extensions to the language itself.

To define an extension:

  module my-extensions {
    ...

    extension c-define {
      description
        "Takes as argument a name string.
        Makes the code generator use the given name in the
        #define.";
      argument "name";
    }
  }

To use the extension:

  module my-interfaces {
    ...
    import my-extensions {
      prefix "myext";
    }
    ...
    container interfaces {
      ...
      myext:c-define "MY_INTERFACES";
    }
  }

We believe that this is a bad idea, since it will break backwards compatibility. Marking an extension as "must-understand" would be necessary when the existing semantics of a definition has been altered in a backwards incompatible way. We believe it is a feature to not allow extensions that modifies the semantics in such a way.

See above.

To the extent possible, YANG maintains compatibility with SNMP's SMIv2 (Structure of Management Information version 2 [RFC2578] (McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., “Structure of Management Information Version 2 (SMIv2),” April 1999.), [RFC2579] (McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., “Textual Conventions for SMIv2,” April 1999.)). SMIv2-based MIB modules can be automatically translated into YANG modules for read-only access. However YANG is not concerned with reverse translation from YANG to SMIv2.

3.1.3.  "NOT Agreed" with which YANG does not comply (or not determined)

This section lists those "NOT Agreed" requirements with which YANG either does not comply or no determination of compliance has yet been made.

3.2.  Requirements from RFC 3139

[RFC3139] (Sanchez, L., McCloghrie, K., and J. Saperia, “Requirements for Configuration Management of IP-based Networks,” June 2001.), "Requirements for Configuration Management of IP-based Networks", lists requirements in Section 3.0, "Requirements for an IP-based Configuration Management System". In this document, only the number in that section and a brief summary are reproduced.

Network-wide configuration is very difficult to achieve. Many system components beyond the data modeling language impact the design of such an application. YANG provides a consistent and interoperable definition of NETCONF content independent of any one device, which is an important component of a network-wide configuration management system.

YANG supports language extensions, which can be added by an application to data model files to identify conceptual data definitions which vary in implementation on specific platforms. YANG will soon support NETCONF capabilities, which can be used to partition data model definitions in device-specific ways. YANG can also be translated to YIN, and then manipulated with XSLT scripts, to construct device-specific variants of network-wide configurations.

This is an application requirement, not related to the data modeling language. YANG does not have any specific constructs that differentiate between network-wide and device-specific configurations.

This is a protocol requirement, not related to the data modeling language. Transfer of configuration data in this manner is supported by the NETCONF protocol.

This is a protocol requirement, not related to the data modeling language. Transfer of configuration data in this manner is supported by the NETCONF protocol.

This is a protocol requirement, supported by the NETCONF protocol.

This is an application requirement, supported by the NETCONF protocol.

This is a protocol requirement, supported by the NETCONF protocol.

This is a transport requirement, supported by the NETCONF protocol stack.

This is a protocol and possibly data model requirement. NETCONF does not support configuration expire times.

NETCONF provides extensive error information, which can include content-layer specific fields. YANG supports the definition of data-model specific error information, which an agent can return in these fields.

This is a protocol requirement, supported by the NETCONF protocol.

This is a protocol and possibly data model requirement. NETCONF does not support configuration change history traceback explicitly, but the mechanisms exist in the protocol to support this feature.

This is a platform-specific feature, not related to the data modeling language.

YANG supports language extensions, language versioning, and augmentation of data models defined in existing documents.

YANG is based in part on SMIng and SMIv2, and includes as many familiar concepts from SNMP data modeling as possible. YANG is designed to extend SMIv2, not throw it out and start over.

3.3.  Requirements from RFC 3216

[RFC3216] (Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., and W. Weiss, “SMIng Objectives,” December 2001.), "SMIng Objectives", divides its objectives into three categories: accepted, nice-to-have, and rejected.

3.3.1.  Accepted objectives

YANG is specified in one document.

YANG uses a textual representation.

It is easy for humans to read and write YANG modules. Many features, such as string formatting, string concatenation, and small set of language tokens, are included for ease-of-use.

The YANG language is fully specified using ABNF.

Protocol accessibility is built into certain YANG constructs, such as 'rpc' or 'notification'. NETCONF data access is controlled with several language constructs, such as the 'config' and 'mandatory' statements.

YANG supports language extensions.

YANG provides full support of UTF-8 strings and many special characters can be inserted in strings.

YANG supports complete instance naming using the Xpath language. Indexed lists are supported as well.

YANG allows full control of XML namespace usage within a data model.

YANG supports modular definitions, and self-consistent sub-modules as well.

YANG only supports full module conformance at this time. Work is under-way to add NETCONF capability based conformance and other mechanisms to support partial module conformance.

YANG includes the 'instance-identifier' built-in data-type, which can be used for XML the way an OBJECT IDENTIFIER is used in SNMP.

YANG is not protocol independent. It is designed to fully support definition of the NETCONF content layer, allowing interoperable manipulation of network configuration data. YANG does not support SNMP or COPS-PR.

YANG does not provide mechanisms to manually map data model constructs to arbitrary protocols. Experience gained in the SMING WG suggests that it is too difficult to maintain separate data model files, or sections within a file, in order to split definitions into a protocol independent section and 1 or more protocol-dependent sections,

YANG builds complete NETCONF protocol support into the language, increasing human ease-of-use, and reducing the chance of errors introduced by additional complicated language constructs to define protocol mappings.

The YANG specification defines NETCONF / XML Encoding Rules in separate sections, which allows a possible later mapping to other protocols.

YANG can be translated to XSD or RelaxNG. It cannot be translated to SMIv2 or SPPI, without loss of semantics.

YANG supports all of the listed data types. All are built into the language, except OID, which is a derived type.

SMIv2 style enumerations are fully supported in YANG.

YANG includes the 'union' data type, which is a non-discriminated union. It is trivial to construct a discriminated union with data modeling constructs (i.e, container with a leaf as the discriminator, plus a union leaf.)

YANG supports instance pointers with the 'instance-identifier built-in data type. A well-established and industry accepted method is used to identify NETCONF data model objects, and named instances of those objects.

The YANG instance-identifier is used to identify all conceptual data model nodes, including conceptual rows in YANG lists.

YANG supports constraints on object instances with the 'keyref' built-in data type. This data type uses an Xpath expression to identify specific object(s) or object instances that are valid for a particular object.

YANG supports a fixed type set, and does not include and extensible numeric base types. These data types are named similar to SMIv2 data types, starting with the kind of numeric type, followed by the number of bits in the data type (int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, and float64).

YANG fully supports derived types for leafs and leaf-lists, which can be based on a built-in type or another derived type. YANG supports global derived types which can be exported, and nested in-line local derived types which are private, and limited to a local (private) inline scope,

YANG contains a 'units' clause which is equivalent to the SMIv2 UNITS clause. Default values are mandatory-to-implement, and can be applied to a derived type or a leaf definition. The DISPLAY-HINT construct is supported with a language extension, and used by the smidump program to convert SMIv2 modules to SMIv2 files.

YANG supports an INDEX clause (key), AUGMENTS clause (augment), but not the SPPI table EXTENDS mechanism. YANG also SPARSE-AUGMENTS with an Xpath expression (when clause), and arbitrarily complex table relationship expressions (must clause). Non-key tuple uniqueness is also provided (unique clause).

The SPPI EXPAND and REORDERS mechanisms are not supported by YANG. They are needed in SPPI for protocol mappings, which are not required in YANG.

YANG has powerful groupings that can be reused, and refined for each use.

Groupings, data definitions, and augmentation of data can be mixed in arbitrarily complex ways. Unlimited nesting of any complex data construct (container, list, choice, uses, augment) is allowed.

Although YANG is not object-oriented, a simple form of single inheritance can be modeled with a grouping that extends an existing grouping.

YANG does not currently support a 'final' attribute. All typedef and grouping definitions can be refined.

YANG provides full support of NETCONF notification content definition.

YANG fully supports the create and delete operations in the NETCONF protocol, and includes additional support for user-controlled list or leaf-list insertion.

The YANG range (and length) clauses are almost identical to the SMIv2 SIZE clause, except it is better. In addition to the usual syntax, e.g., (1..10) or (1 | 3 5..10), the 'min' and 'max' keywords are allowed to indicate that the range boundary is derived from the parent, in the chain of derived types. In addition, float32 and float64 range definitions can contain the4 '-INF' and 'INF' keywords, which are synonyms for 'min' and 'max', traditionally used for floating point numbers.

The YANG 'unique' clause supports uniqueness constraint specification.

YANG defines rules for extending and updating modules in a compatible way (work to be done). The YANG "augment" statement allows extending a data model with the contents of a new module in a compatible way.

This requirement is not applicable to NETCONF.

YANG is designed with minimal data entry redundancy in mind. No data ever needs to be entered in multiple places, within a module, in order to define any construct.

YANG does not have any partial module conformance. Only full module conformance is supported at this time. Could be added, if needed.

This feature could be supported in YANG, if some sort of module variance mechanism is added.

YANG does not contain explicit support for SPPI subject categories. This could be achieved with a language extension, if needed in NETCONF.

YANG is similar to SPPI, in that no language keywords are ever imported, or built-in data types. Only user-defined identifiers are imported or included in YANG.

SPPI and SMIv2 instance naming is not relevant to NETCONF.

YANG defines a minimum value that all implementations must support as their maximum identifier length (63 characters). A hard-wired maximum identifier length is not used.

COPS-PR protocol mapping is not relevant to NETCONF.

3.3.2.  Nice-to-have objectives

YANG and NETCONF support methods with a remote procedure call construct. This is not the same as an object-oriented method, but YANG fully supports the mechanisms with NETCONF for this purpose.

YANG contains the 'union' built-in data type, which can contain an arbitrary mix of types, including other unions.

YANG supports IEEE floating point math with the 'float32' and 'float64' built-in data types. A range or default clause for these types can be specified in IEEE floating point syntax. [ed. reference].

YANG supports single line C++ style comments '// ...EOLN' as well as C-style multi-line comments (/* ... */).

SPPI instance tagging is not relevant to NETCONF.

YANG supports variable-length, multi-valued objects with the 'choice' construct, which provides extensible cases and some NETCONF protocol control (mandatory, default) for this type of flexible object definition.

Internationalization is possible in YANG. See bullets 3.2.8.2-3.2.8.4 in chapter Section 3.1.1 (Agreed).

Almost all NETCONF protocol details are hidden by YANG, allowing data modelers to focus on the domain-specific aspects of the data model, and not the language syntax. YANG clauses have a very flexible syntax, loose ordering, and relatively few language constructs, to allow users to concentrate on writing data definitions, not fixing MIB compiler errors.

3.3.3.  Rejected objectives

YANG supports some of the rejected requirements from SMING. Support is described below specifically if present in YANG.

Supported with the "must" statement.

Partly supported with the "must" statement and the keyref built-in type.

Supported with the "rpc" statement.

Supported with the "keyref" built-in type.

The "keyref" built-in type is used to formally define 1:1 and 1:n associations/relationships in YANG models.

YANG provides a recommendation for mapping to files.

Supported.

Supported.

3.4.  Requirements from draft-linowski-netconf-dml-requirements-00

[LINOWSKI] (Linowski, B., “NETCONF Data Modeling Language Requirements,” February 2008.), "NETCONF Data Modeling Language Requirements", has the following requirements:

Compliant.

Compliant.

Compliant. YANG supports extensions to the language in a compatible way.

Compliant, using the "module" and "submodule" statements.

Compliant, see bullets 4.1.13 and 4.1.14 in Section 3.3.1 (Accepted objectives).

Compliant. See bullet 3.8.2 in Section 3.1.1 (Agreed).

Compliant, see bullet 4.1.11 in Section 3.3.1 (Accepted objectives).

Partly compliant. YANG identifiers are case sensitive, and hyphens, dots and leading underscores are allowed as well.

Compliant. YANG provides a number of documentation and information elements that support UTF-8 characters.

Compliant. For localization/internationalization see bullet 3.2.8.1 through 3.2.8.4 in Section 3.1.1 (Agreed).

Compliant. See bullet 3.6.2.1. in Section 3.1.1 (Agreed).

Not compliant, disagree with the requirement. Handling multiple possibly incompatible versions of a model in one document would be confusing to the user. Keep the (sub)modules side by side, don't merge them. Incompatible versions of the (sub)modules must have different names as in SMI.

Not compliant. YANG is not object oriented. Groupings can be used as a proxy to classes. A grouping can define all attributes of a class.

Not compliant.

Partly compliant. Although YANG is not object-oriented, a simple form of single inheritance can be modeled with a grouping that extends an existing grouping.

Partly compliant. Classes and attribute groups can be modeled using the "grouping" statement.

Compliant using the "grouping" statement.

Partly compliant. The keyref built-in type can be used to describe references.

Compliant using the "container" or the "list" and the augment statement.

Compliant, based on a leaf-list of the keyref built-in type. Adding relationships without altering the source- or target-end class is possible with a keyref list stored externally to both ends of the relationship.

Compliant, but all constraints are combined with the AND operator that is all constraints must be met simultaneously.

Partly compliant based on the "extension" statement. The type, the placement and the optionality of an extension is intentionally not defined. If it is an extension then by definition it should allow free usage; most tools will anyway not understand it - will ignore it.

4.  YANG DHCP Module

The BOF proposal for the CANMOD BOF at the seventy-first IETF states: "Design teams have also prepared annotated examples of instance documents to illustrate many of the requirements." The example instance document is in Appendix C of [PRESUHN] (Presuhn, R., “Requirements for a Configuration Data Modeling Language,” February 2008.). This section shows the YANG modules written for that instance document.

module dhcp {
  namespace "http://example.com/ns/dhcp";
  prefix dhcp;

  import yang-types { prefix yang; }
  import inet-types { prefix inet; }
  import ieee-types { prefix ieee; }
  import interfaces { prefix if; }

  organization
    "yang-central.org";
  description
    "Partial data model for DHCP, based on the config of
     the ISC DHCP reference implementation.";

  container dhcp {
    description
      "configuration and operational parameters for a DHCP server.";

    leaf max-lease-time {
      type uint32;
      units seconds;
      default 7200;
    }

    leaf default-lease-time {
      type uint32;
      units seconds;
      must '$this <= ../max-lease-time' {
        error-message
          "The default-lease-time must be less than max-lease-time";
      }
      default 600;
    }

    uses subnet-list;

    container shared-networks {
      list shared-network {
        key name;

        leaf name {
          type string;
        }
        uses subnet-list;
      }
    }
  }

  grouping subnet-list {
    description "A reusable list of subnets";
    list subnet {
      key "network prefix-length";
      leaf network {
        type inet:ip-address;
      }
      leaf prefix-length {
        type uint8 {
          range "0..128";
        }
      }
      container range {
        presence "enables dynamic address assignment";
        leaf dynamic-bootp {
          type empty;
          description
            "Allows BOOTP clients to get addresses in this range";
        }
        leaf low {
          type inet:ip-address;
          mandatory true;
        }
        leaf high {
          type inet:ip-address;
          mandatory true;
        }
      }

      container dhcp-options {
        description "Options in the DHCP protocol";
        container router-list {
          leaf-list router {
            type inet:host;
            ordered-by user;
            reference "RFC 2132, sec. 3.8";
          }
        }
        container domain-list {
          leaf-list domain-name {
            type inet:domain-name;
            reference "RFC 2132, sec. 3.17";
          }
        }
        list custom {
          key option;
          leaf option {
            type uint32;
          }
          choice type {
            leaf ipv4-address {
              type inet:ipv4-address;
            }
            leaf string {
              type string;
            }
          }
        }
      }

      leaf max-lease-time {
        type uint32;
        units seconds;
        default 7200;
      }

      container leases {
        config false;
        description
          "Contains status information about active leases.";
        list lease {
          key address;

          leaf address {
            type inet:ip-address;
          }
          leaf starts {
            type yang:date-and-time;
          }
          leaf ends {
            type yang:date-and-time;
          }
          leaf mac-address {
            type yang:phys-address;
          }
        }
      }

      container interface-filter {
        description
          "The DHCP server will only respond to requests for this
           subnet when they come from one of these interfaces";
        leaf-list interface {
          type keyref {
            path "/if:interfaces/if:interface/if:ifName";
          }
        }
      }
    }
  }
}

The next module is an example of a YANG module that augments the existing dhcp module.

module calendar {

  namespace "http://example.com/ns/cal";
  prefix cal;

  import dhcp { prefix dhcp; }

  augment "/dhcp:dhcp/dhcp:subnet/dhcp:dhcp-options" {
    leaf timezone {
      type string;
    }
  }

  // more data definitions added here...

}

The interface module is an incomplete stub module for the keyref in dhcp.yang.

module interfaces {
  namespace "http://example.com/ns/int";
  prefix if;

  // This is a stub module to make sure the keyref in
  // dhcp module points to a real list.

  container interfaces {
    list interface {
      key ifName;
      leaf ifName {
        type string;
      }
    }
  }
}

5.  IANA Considerations

This document has no actions for IANA.

6.  Security Considerations

This document is only a statement of compliance to a set of requirements. It does not itself define any protocol or information content so security considerations are not applicable.

7.  Contributors

The following people all contributed significantly to this document:

 - Andy Bierman (andybierman.com)
 - Balazs Lengyel (Ericsson)
 - David Partain (Ericsson)
 - Juergen Schoenwaelder (Jacobs University Bremen)
 - Phil Shafer (Juniper Networks)

8.  References

8.1. Normative References

[LINOWSKI] Linowski, B., “NETCONF Data Modeling Language Requirements,” draft-linowski-netconf-dml-requirements-01 (work in progress), February 2008.
[PRESUHN] Presuhn, R., “Requirements for a Configuration Data Modeling Language,” draft-presuhn-rcdml-03 (work in progress), February 2008.
[RFC3076] Boyer, J., “Canonical XML Version 1.0,” RFC 3076, March 2001.
[RFC3139] Sanchez, L., McCloghrie, K., and J. Saperia, “Requirements for Configuration Management of IP-based Networks,” RFC 3139, June 2001.
[RFC3216] Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J., and W. Weiss, “SMIng Objectives,” RFC 3216, December 2001.
[RFC3629] Yergeau, F., “UTF-8, a transformation format of ISO 10646,” STD 63, RFC 3629, November 2003.
[RFC4741] Enns, R., “NETCONF Configuration Protocol,” RFC 4741, December 2006.
[YANG] Bjorklund, M., “YANG - A data modeling language for NETCONF,” draft-bjorklund-netconf-yang-02 (work in progress), February 2008.

8.2. Non-Normative References

[RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., “Structure of Management Information Version 2 (SMIv2),” STD 58, RFC 2578, April 1999.
[RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., “Textual Conventions for SMIv2,” STD 58, RFC 2579, April 1999.
[RFC3780] Strauss, F. and J. Schoenwaelder, “SMIng - Next Generation Structure of Management Information,” RFC 3780, May 2004.

Author's Address

  Martin Bjorklund (editor)
  Tail-f Systems
Email:  mbj@tail-f.com

Full Copyright Statement

Intellectual Property

Acknowledgment