FORGE Course

Full Height |  Two columns |  Parts | 

Lecture 2: YANG model

Lecture 2: YANG model Apostolos Palladinos 12/05/2016 English
YANG model

YANG model

YANG model Apostolos Palladinos 12/05/2016 English
YANG model

YANG model is a language for data modeling. It is mainly used by NETCONF protocol in order to model its configuration and state data, remote procedure calls(rpcs) and notifications that are produced within this protocol. In addition, it models operation and content layers of the NETCONF protocol. The data of a YANG model are organized in a hierarchical  tree structure where every node has a name, and in addition it includes either a values or a child node(s). Furthermore, there is at least one module where the data model is defined, but there is also a choice of multiple module definitions of a YANG model. In latter model the main module can import the rest modules in order to complete the YANG model definition and apart from that it can also include submodules to add data nodes. An augmentation option is available for the main module in order to extend the nodes, and consequently the model, provided by an external imported module. The essence of a YANG model is to provide the node and the data constraints in a NETCONF configuration datastore. That is the network administator is limited and he must comply with the syntax of YANG model by the aspect of hierarchy of the nodes in the configuration and the datatypes in each node. YANG model supports an abundance of built-in datatypes in order to define the different types in NETCONF configuration and also provides the creation of new types, which can constrain even more the built-in types through properties like "range" or by using patterns. We are going to check most of them later. The mayor purpose of YANG model is to define the NETCONF configurations with a concise, comprehensive and conceivable way by the network administrator and this is what it does in compare with the other model languages. Finally, an important feature of this modeling language is that there is 1:1 correspodance between YANG  and YIN models. YIN model includes exactly the same information about the syntax structure of NETCONF configuration that complies with that specific YANG model but YIN's structure is written in the XML language which is more widespread in that moment. The widget that is going to be used in other courses utilizes a NETCONF server( netopeer server ) that uses a YIN model in the background for datastore configuration validation instead of a YANG model. But the users of the widgets are writing their models in YANG model, which is converted automatically in YIN model later by widget's commands. In the below section you can find the basic structures of the YANG model, their description and some simple examples for better understanding of them: 

  1. Modules and submodules: As previous described a module is the place where the data model is defined. Each model can be defined in multiple modules or at least in only one module. If is defined in multiple modules the main module of the model imports the rest modules of the modules. In addition, submodules can be defined in a module in order to be broken in more discrete parts. Then the network administrator can include them in this module or in other modules, if those modules have been imported from the main module, in order the main module to utilize the included from them submodules. A module contains three types of statements:
    • Module-header.
    • Revision.
    • Definition.

    The first category gives a small description about the module, that is basic information. The revision statement gives information about the version of the module, by using its date. Finally, definition statements constitute the body of each module where all the statements of the data model are defined. Additionally, the "import" statement allows a module to import other modules, whether the "include" statement allows modules to include a submodule in them. Two examples can be seen below:

    Import:

    module a { 
     revision 2016-02-10 { ... } 
     
     container c { 
       leaf d{type string; description "d element"; 
       } 
     } 

     module b { 
        import a { 
           prefix p; revision-date 2008-01-01; 
        } 
       container bee 
        { uses p:a; 
        } 
     }
    Include:

    module test { 
        namespace "http://example.com/test"; 
        prefix "tst"; 
        import test-types { 
           prefix "types"; 
        } 
        include acme-types-sub; 
        organization "Test"; 
        contact "Name Surname Test, Somewhere Street, Greece Phone: 1234567890 Email: test@example.com"; 
        description "Test module."; 
        revision "2016-02-03" { description "Version 2."; } 
        // definitions follow... 
        } 
    ------------------------------------------------------------------------------------------------------------------------------

    submodule test-types-sub { 
       //exists in test-types module 
       import other-definitions { 
           prefix "def"; 
        } 
        organization "Definitions"; 
        contact "Common name Definitions, Definitions street 20, Greece Phone: 9876543210 Email: definitiosn@somewhere.com"; 
        description "Test submodule"; 
        revision "2012-04-03" { 
           description "Initial revision."; 
        } // definitions follows... 
     }

  2. Leafs: A leaf element contains a simple YANG built-in datatype like integer. That is it has not child nodes and in addition it has only one value. An example can be seen below:

    leaf name { 
        type string; 
        description "Whatever name"; 
     }
  3. Leaf-Lists: This element is a sequence of leaf elements of the same type that each of them has a specific value of the defined built-in type. An example can be seen below:

    leaf-list name-list { 
        type string; 
        description "List of names"; 
     }
  4. Containers: By using this element we can group elements of any type in that element. In addition, this element can not contain values but only child elements of all the types that previously mentioned. An example of the container element is given below:

    container service { 
        container login { 
            leaf name { 
               type string; 
               description "Whatever name"; 
            } 
        } 
     }
  5. Lists: A list element includes a sequence of different element types. Each list element contains also at least a key element whose value defines uniquely each record(list elements are like the database records ). An example can be seen below:

    list record { 
        key "field1"; 
        leaf field1 { 
           type string; 
        } 
        leaf field2 { 
           type string; 
        } 
        leaf field3 { 
           type integer; 
        } 
     }
  6. Typedef: With that statement we can define derived types from built-in or already derived types. An example can be seen below:

    typedef grades { 
     type uint8 { 
        range "0 .. 10"; 
     } 
     description "Grades"; 
     } 
     leaf school-grades { 
        type grades; 
     }
  7. Grouping: By utilizing this element we can packet groups of elements and use them wherever we want to. An example can be found below:

    grouping elements-set {
       leaf first-element { 
          type string; 
          description "First element"; 
       } 
       leaf second-element { 
          type integer; 
          description "Second element"; 
       } 
     } 
     container test { 
        container test-internal { 
           uses elements-set; 
        } 
     }
  8. Choices: This element provide us a set of elements that can be chosen in a specific part of the configuration. We can choose only one of the provided elements in a NETCONF configuration. The choice element provide us the list of elements that we can choose and the case element defines all those cases. An example can be seen below:

    container drinks { 
       choice water { 
          case mineral { 
             leaf volume { 
                type integer; 
             } 
           leaf price { 
              type string; 
           } 
          } 
          case marine { 
             leaf area { 
                type string 
             } 
          } 
       } 
     }
  9. Augment: By using this element we can extend a YANG model to a specific level of hierarchy by using a condition.This condition is defined in when statement.An example can be seen below:

    augment /drinks/mineral { 
       //xpath 
       when "price != '10'"; 
          leaf suggested-price {            
             type int; 
          } 
     }
  10. Notifications: One important operation of NETCONF is notifications operation that are responsible to warn the network administrator for important events happening in that. An example of its utilization can be seen in the below example:

    notification congestion { 
        description "Warns when congestion is observed"; 
        leaf ip { 
           type string; 
        } 
     }


In order to declare a leaf element of the YANG model as NETCONF state data we use the "config false" command inside its structure. An example of this command can be seen below: 

container network { 
   leaf mac-address{ 
      type string; 
      config false;
   }
}
   

A mandatory node is one of the below cases:

  1. A leaf, choice, or anyxml node with a "mandatory" statement with the value "true".
  2. A list or leaf-list node with a "min-elements" statement with a value greater than zero.
  3. A container node without a "presence" statement, which has at least one mandatory node as a child.

An example can be seen below:

container user { 
   leaf name{ 
      type string; 
      mandatory true;
   }
}

Finally, a table which contains YANG model's built-in types is given below:
+---------------------+-------------------------------------+
| Name| Description|
+---------------------+-------------------------------------+
| binary | Any binary data |
| bits | A set of bits or flags |
| boolean | "true" or "false" |
| decimal64 | 64-bit signed decimal number |
| empty | A leaf that does not have any value |
| enumeration | Enumerated strings |
| identityref | A reference to an abstract identity |
| instance-identifier | References a data tree node |
| int8 | 8-bit signed integer |
| int16 | 16-bit signed integer |
| int32 | 32-bit signed integer |
| int64 | 64-bit signed integer |
| leafref | A reference to a leaf instance |
| string | Human-readable string |
| uint8 | 8-bit unsigned integer |
| uint16 | 16-bit unsigned integer |
| uint32 | 32-bit unsigned integer |
| uint64 | 64-bit unsigned integer |
| union | Choice of member types |
+---------------------+------------------------------------