在研究netconf的时候，YANG(RFC6020)是一定绕不过的。花了一些时间看RFC6020，有一点初步的理解，记录下来方便后面查看。
1 为什么要有YANG
netconf需要对设备的配置(configuration)和状态(state)做操作，例如编辑配置，获取状态，因此需要一种语言来对configuration和state进行建模，甚至连“操作”也可以通过YANG来建模。建好的模型，最后以XML的形式进行实例化。打个比方，我需要向领导请假，领导说你写个请假单，包含请假人的姓名，请假的起止时间，请假事由和代理人。于是我做了一个表格，包含了上述要求，并根据实际情况填入了真实信息。那么领导的描述，就可以理解为“建模”，而我最后提交的填好内容的表格，就是将模型实例化了。
2 建模需要什么呢
如果要建模，一定需要一些基础架构，然后将要建立的模型用这些基础架构拼接出来。那么YANG提供了哪些架构呢？
2.1 module和submodule
module的header主要是一些描述信息，而body就是data model定义的地方。module可以分为submodule。模块化的好处就是方便引用。
2.2 Data Modeling Basics
这时候要敲敲黑板，因为重点来喽。这里介绍最最基本的四种建模架构。
2.2.1 Leaf Nodes
一个leaf node包含且只包含一个value，可以是数字或是字符串，具体是什么，看关键字"type"后面跟什么。leaf node下面不能挂子节点。
例如：
YANG Example:
leaf host-name {
type string;
description "Hostname for this system";
}
-----------------------
NETCONF XML Example:
<host-name>my.example.com</host-name>
此处用YANG定义了一个名为host-name的leaf，它包含对自己的description，有一个string类型的值。那么当用XML实例化这个leaf的时候，就需要对host-name进行具体的赋值。换句话说，YANG是挖坑的，XML是填坑的，但是XML填坑用的材料的“形状”，要和YANG定义的一样。
2.2.2 Leaf-List Nodes
与上面的Leaf Nodes“一字之差”，多了一个“-list”。可以认为Leaf-List Nodes表示的是一个“数组”，“数组”中的元素的值的type必须保持一致，而且不能重复。
例如：
YANG Example:
leaf-list domain-search {
type string;
description "List of domain names to search";
}
-----------------------
NETCONF XML Example:
<domain-search>high.example.com</domain-search>
<domain-search>low.example.com</domain-search>
<domain-search>everywhere.example.com</domain-search>
和leaf node一样，它也只定义一个value，但是可以有一系列同类型的值。例子中<domain-serarch>的值有多个，但是定义和类型都是统一的。
2.2.3 Container Nodes
“Container”可以翻译成“集装箱”。真正有价值的，是集装箱里面装的货物，而不是集装箱本身。但是如果没有集装箱，那么里面的货物就散了。
Container的作用就是将数据层次化组织起来，呈现出subtree的样式。特别需要注意的是：
(1)一个空的集装箱也是能“卖钱”的，因为毕竟是铁皮做的，但是一个container自身是没有“value”的；
(2)一个集装箱容量是有限的，但是一个container可以装多少node并没有限制，而且这些node可以在leaf/list/leaf-list甚至是container(想起了俄罗斯套娃)中任意选取。
例如：
YANG Example:
container system {
container login {
leaf message {
type string;
description
"Message given at start of login session";
}
}
}
-----------------------
NETCONF XML Example:
<system>
<login>
<message>Good morning</message>
</login>
</system>
container system里面装了一个container login，然后login里面有一个leaf node，就是类型为string的“message”。
2.2.4 List Nodes
一个List node可以包含多个child node，而且这些node可以在leaf/leaf-list/container中任意选取。List必须指明这些child中的一个node为key。
例如:
YANG Example:
list user {
key "name";
leaf name {
type string;
}
leaf full-name {
type string;
}
leaf class {
type string;
}
}
-----------------------
NETCONF XML Example:
<user>
<name>glocks</name>
<full-name>Goldie Locks</full-name>
<class>intruder</class>
</user>
<user>
<name>snowey</name>
<full-name>Snow White</full-name>
<class>free-loader</class>
</user>
<user>
<name>rzell</name>
<full-name>Rapun Zell</full-name>
<class>tower</class>
</user>
定义了一个名为“user”的list，这个list中包含三个leaf：name/full-name/class。其中name被指定为key。实例化的时候，key的值(也就是"name"的值)是必须不同的，其它的值(full-name/class)没有这个要求。随后xml实例化了三个user，都包含YANG定义的name/full-name/class，而且name都是不同的。
2.2.5 Combined Module
RFC中给出了一个综合上述四种node的混合模式的例子如下：
// 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.";
}
container system {
leaf host-name {
type string;
description "Hostname for this system";
}
leaf-list domain-search {
type string;
description "List of domain names to search";
}
container login {
leaf message {
type string;
description
"Message given at start of login session";
}
list user {
key "name";
leaf name {
type string;
}
leaf full-name {
type string;
}
leaf class {
type string;
}
}
}
}
}
-----------------------
NETCONF XML Example:
<system>
<host-name>myyang.com</host-name>
<domain-search>high.example.com</domain-search>
<domain-search>low.example.com</domain-search>
<domain-search>everywhere.example.com</domain-search>
<login>
<message>Good Morning</message>
<user>
<name>glocks</name>
<full-name>Goldie Locks</full-name>
<class>intruder</class>
</user>
<user>
<name>snowey</name>
<full-name>Snow White</full-name>
<class>free-loader</class>
</user>
<user>
<name>rzell</name>
<full-name>Rapun Zell</full-name>
<class>tower</class>
</user>
</login>
</system>
对YANG module的解读：
- module的名字是acme-system
- namespace是用来唯一标识这个YANG模型与其它YANG模型不同
- prefix是namespace的一种简写
- organization/contact/description都是用来描述相关信息
- revison描述版本信息，可以有多个revision(一般记录版本更新的内容)
- module中包含一个container system
- container system包含一个leaf(host-name)，一个leaf-list(domain-search)和一个container login
- container login包含一个leaf(message)，和一个list(user)
下面的XML只要按照YANG Module的规定，实例化即可。
2.3 State Data
netconf需要区分configuration data和state(状态) data，在YANG建模的时候，对于state data需要加上"config false".例如：
list interface {
key "name";
leaf name {
type string;
}
leaf speed {
type enumeration {
enum 10m;
enum 100m;
enum auto;
}
}
leaf observed-speed {
type uint32;
config false;
}
}
好吧，10m/100m确实暴露了这篇RFC的“年龄”，现在交换机的端口带宽已经可以达到100G甚至更高了。在list interface中。speed的value type是枚举类型，就是说实例化的时候只能从这里列出的三种中选择一个。对于leaf observed-speed,因为包含"config false"，因此这个leaf记录的是state value，不可以配置。对应于netconf的操作，leaf speed可以<get-config>，而leaf observed-speed只能<get>。
2.4 Build-in Type
前面给leaf或是leaf-list定义类型的时候举的例子，type后面跟的都是string。实际上string只是YANG build-in(内建)数据类型中的一种。下面罗列一下YANG所有的build-in types
+---------------------+-------------------------------------+
| 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 |
+---------------------+-------------------------------------+
2.5 Derived Type
在实际建模中，上述的type肯定是不够的。YANG允许用户使用typedef来定义自己需要的type，可以基于build-in type或是另外一个派生的type。
例如需要一个描述百分比的type：
YANG Example:
typedef percent {
type uint8 {
range "0 .. 100";
}
description "Percentage";
}
leaf completed {
type percent;
}
-----------------------
NETCONF XML Example:
<completed>20</completed>
- 通过typedef定义了新的type"percent",基于uint8(0-255的无符号整数)，并进一步限制取值范围为[0,100]
- 定义了leaf completed(完成百分比)，使用的type正是上面定义的percent
- XML实例化completed时候给出的数值是20，符合percent的type定义
- 如果netconf交互的时候，completed传的数值如果不符合YANG的描述(例如小数/负数/200)，会因为无法通过模型check而被拒绝
2.6 Reusable Node Groups (grouping)
grouping其实不是一种数据类型，它存在的意义只是方便在“编程”的时候被引用。所以它本身是没有value的。grouping可以在本module被引用，或是被其它module引用。
grouping可以包含
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
+--------------+---------+-------------+
例如：
YANG Example:
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;
}
}
-----------------------
NETCONF XML Example:
<peer>
<destination>
<address>192.0.2.1</address>
<port>830</port>
</destination>
</peer>
回想一下，当一台主机对外提供服务的时候，客户端需要知道提供服务主机的的IP和端口信息。所以这边可以定义一个grouping target，在里面定义leaf address和leaf port。下面的container peer来uses(调用grouping的关键字)这个grouping。当对<peer>实例化的时候，就需要将grouping target中包含的address和port都进行赋值。这里的830端口，是在RFC6242(Using the NETCONF Protocol over Secure Shell)中定义的基于ssh的netconf服务端口。
这里的users可以理解为copy，即把grouping的整个内容都复制到了这个schema tree。grouping本身是没有绑定到任何namespace的，直到某个module uses了这个grouping，那么这个grouping就被绑定到这个module了。
grouping还有一个非常好用的特性就是refine，例如要建立连接，既需要server的IP+port，也需要client的IP+port。因为这两个的数据结构是完全一样的，所以可以复用，并用更准确的description来覆盖grouping定义时候设置的description。
YANG Example:
container connection {
container source {
uses target {
refine "address" {
description "Source IP address";
}
refine "port" {
description "Source port number";
}
}
}
container destination {
uses target {
refine "address" {
description "Destination IP address";
}
refine "port" {
description "Destination port number";
}
}
}
}
2.7 Choices
"choice"+"case"用来描述互斥的内容。一个choice可以包含多个case，每个case可以包含多个node。一般来说在一个choice里，一个case下面的node不应该和其他case下面的node重复。
在YANG模型和schema中可以看到choice下的所有case，而当对它实例化之后，只会出现一个case下面的nodes了。例如
YANG Example:
container food {
choice snack {
case sports-arena {
leaf pretzel {
type empty;
}
leaf beer {
type empty;
}
}
case late-night {
leaf chocolate {
type enumeration {
enum dark;
enum milk;
enum first-available;
}
}
}
}
}
-----------------------
NETCONF XML Example:
<food>
<pretzel/>
<beer/>
</food>
2.8 Extending Data Models (augment)
YANG允许向data module插入新的节点。这是一个非常有用的特性，例如厂商想在公共yang上插入自己的特殊参数，那么augment就可以实现这个需求。"when"后面跟的是条件，即为满足这个条件，就插入新的node。例如
YANG Example:
augment /system/login/user {
when "class != 'wheel'";
leaf uid {
type uint16 {
range "1000 .. 30000";
}
}
}
-----------------------
NETCONF XML Example 1:
<user>
<name>alicew</name>
<full-name>Alice N. Wonderland</full-name>
<class>drop-out</class>
<other:uid>1024</other:uid>
</user>
-----------------------
NETCONF XML Example 2:
<user>
<name>jerryr</name>
<full-name>Jerry K. Roma</full-name>
<class>wheel</class>
</user>
Example 1中因为class不是"wheel"，因此插入uid; Example 2中class是"wheel"，所以不插入uid。
2.9 RPC Definitions
YANG可以用来定义netconf的rpc，包括rpc输入的参数，输出的参数，例如：
YANG Example:
rpc activate-software-image {
input {
leaf image-name {
type string;
}
}
output {
leaf status {
type string;
}
}
}
-----------------------
NETCONF XML Example:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<activate-software-image xmlns="http://acme.example.com/system">
<image-name>acmefw-2.3</image-name>
</activate-software-image>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<status xmlns="http://acme.example.com/system">
The image acmefw-2.3 is being installed.
</status>
</rpc-reply>
定义一种叫做"activate-software-image"的rpc。当Client发送rpc的时候，需要加上image-name，交换机发回rpc-reply的时候，需要加上activate的结果，本例中可以看到操作是成功了。
2.10 Notification Definitions
Notification是一种通告机制，当交换机上出现特性event(事件)，交换机会主动发给已经建立netconf连接并订阅了Notification的client。YANG可以定义notification，例如
YANG Example:
notification link-failure {
description "A link failure has been detected";
leaf if-name {
type leafref {
path "/interface/name";
}
}
leaf if-admin-status {
type admin-status;
}
leaf if-oper-status {
type oper-status;
}
}
-----------------------
NETCONF XML Example:
<notification
xmlns="urn:ietf:params:netconf:capability:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system">
<if-name>so-1/2/3.0</if-name>
<if-admin-status>up</if-admin-status>
<if-oper-status>down</if-oper-status>
</link-failure>
</notification>
这样无论是接口的admin状态(shutdown或是no shutdonw)，还是链路状态(down/up)发送改变的时候，都可以发送notification给client，并且带上了当前的状态信息。
3 学以致用
上面罗列了很多YANG语言建模的细节，但是还远远没有列全。但是如果仔细看了上面的内容，见到yang模型应该不会完全手足无措了。例如下面列一个华为的huawei-netconf.yang来体会一下
/*
Copyright (C) 2013-2017 Huawei Technologies Co., Ltd. All rights reserved.
*/
module huawei-netconf {
namespace "http://www.huawei.com/netconf/vrp/huawei-netconf";
prefix netconf;
include huawei-netconf-type;
include huawei-netconf-authorization;
include huawei-netconf-notification;
include huawei-netconf-authorization-type;
include huawei-netconf-notification-type;
organization
"Huawei Technologies Co.,Ltd.";
contact
"Huawei Industrial Base Bantian, Longgang Shenzhen 518129
People's Republic of China
Website: http://www.huawei.com Email: support@huawei.com";
description
"The NETCONF protocol defines a simple mechanism through which a network device can be managed, configuration data information can be retrieved, and new configuration data can be uploaded and manipulated.";
revision 2017-03-23 {
description
"Functions supported by the schema are added to the YANG file.";
reference
"Huawei private.";
}
revision 2013-01-01 {
description
"Init revision";
reference
"Huawei private.";
}
container netconf {
description
"The NETCONF protocol defines a simple mechanism through which a network device can be managed, configuration data information can be retrieved, and new configuration data can be uploaded and manipulated.";
container netconfCapabilitys {
config false;
description
"NETCONF capability list.";
list netconfCapability {
key "capabilityName version";
config false;
description
"NETCONF capability.";
leaf capabilityName {
type netconfNcaCapability;
config false;
description
"Name of the NETCONF capability.";
}
leaf version {
type netconfCapabilityVersion;
config false;
description
"Capability version number.";
}
leaf scope {
type netconfCapabilityScope;
config false;
description
"Scope of the capability.";
}
}
}
container authorization {
description
"NETCONF authorization.";
uses netconf:netconf_authorization_type;
}
container notification {
config false;
description
"notification";
uses netconf:netconf_notification_type;
}
container operationLogSwitch {
description
"Switch for RPC oper log.";
leaf get {
type boolean;
description
"Get oper type.";
}
}
}
}
