YANG语言.docx

YANG -NETCONF数据建模语言YANG是一种被用来为NETCONF协议建模的语言。一个YANG module定义了具有垂直结构的数据，这些数据可以被用做基于NETCONF的operations，比如configuration，state date，RPCs，以及notifications。它使得NETCONF的client和server之间能有完整的数据描述。YANG建模得到的数据具备树形结构。其中每一个节点都有一个名字，都有一个值或者一些子节点。YANG为这些节点，以及节点之间的交互提供明确清晰的描述。YANG使用modules和submodule进行数据建模。一个module能够从其他外部的modules中导入数据，也可以从submodules中包含数据。YANG定义的垂直结构可以扩展，使得一个module能够增加数据节点给另一个module。这种扩展是有条件的，只有特定条件满足，新的数据节点才会出现。YANG模型还能描述数据之上增加的约束，基于垂直结构中其他节点的出现与否，值为多少等等来限制一些节点的出现与赋值。这些约束可以被client或者server强制执行。不过如果要使得内容有效，MUST双方都要遵守特定的约定。YANG定义了一系列的内建数据类型，也有定义新数据类型的类型命名机制。派生数据类型可以通过像range，pattern这样的声明限制其原生数据类型的取值范围，这样的声明在client或者server端都可以执行。它们还能为派生数据类型定义常用用法，比如定义一个string-based类型，包含主机名。YANG允许对可重用的grouping中节点的定义。这些groupings中的实例能够通过特定的增强以满足特殊的需求。派生类型以及groupings能够定义在一个module或者submodule中，能够被本地，其他module/submodule导入和使用。YANG的垂直数据结构包括了对list的定义。list中包含的每一项都有唯一的key以区分彼此。这样的lists有可能被用户自定义排序或者由系统进行默认排序。对于用户自定义排序的lists来说，operations是为了对列表项进行排序定义的。YANG modules可以被转换为等价的XML格式，称为YANG Independent Notation（YIN）（Section 11），这使得相关的应用可以通过XML解析器或者XSLT脚本进行操作。从YANG到YIN的转换是无损的，因此也可以从YIN格式转换为YANG文件。YANG试图在高层的数据建模和底层的比特数据编码（bits-on-the-wire encoding）之间追求平衡。YANG module的reader可以查看数据模型的高层视图，同时也能理解在NETCONF operations中，这些数据如何编码。YANG是一种可扩展语言，允许标准制定者，设备商，以及个人定义新的声明（statement）。声明的语法使得这些扩展能够以一种自然的方式和标准的YANG 声明共存，同时使得reader能够有效得认知这些新扩展。YANG resists the tendency to solve all possible problems, limiting the problem space to allow expression of NETCONF data models, not arbitrary XML documents or arbitrary data models. The data models described by YANG are designed to be easily operated upon by NETCONF operations.为了扩大使用范围，YANG和SNMP协议的SMIv2（Structure of Management Information，RFC2578和RFC2579）保持了兼容。基于SMIv2的MIB modules能够以只读的方式自动转换为YANG modules。然而，YANG并不关心如何从YANG转换为SMIv2。和NETCONF相似，YANG致力于和设备本身自带的管理机制进行平滑集成。这就使得需要利用设备当前的访问控制机制去保护/暴露数据模型的相应元素。1 语言总览1.1数据建模基础(Data Modeling Basics)YANG定义了四种用于数据建模的节点类型。在下面的每一个小节中，都有例子展示YANG语法以及相应的NETCONF XML表达。1.1.1 Leaf Nodes一个leaf node包含了像integer或者string这样的简单数据。它有且仅有一个特定类型的值，并且没有子节点。YANG 示例: leaf host-name type string; description Hostname for this system; NETCONF XML 示例: /host-name leaf声明“leaf”声明被用来在schema tree中定义一个leaf node。它只有一个参数，是identifier，后面跟着详细描述该leaf信息的一块substatements。一个leaf node有一个值，但是在data tree中没有child nodes。概念上讲，data tree中的值总是以canonical form存在的。在data tree中存在0个或者1个leaf node。“leaf”声明被用来定义一个特定类型的标量变量。 leaf的默认值（default value）一个leaf的默认值是当在data tree中没有该leaf存在时，服务端采用的值。使用默认值的取决于schema tree中离该leaf最近的并且是presence的container的祖先节点： 如果在schema tree中没有这样的祖先节点，则默认值MUST被使用 否则，如果这个祖先节点是一个case node，则如果data tree中有任何该case的node存在，或者这个case node就是choice的默认case，并且data tree中没有任何其它的case存在，这样一来就必须使用默认值。 再否则，如果在data tree中有这样的祖先节点存在，则默认值MUST被使用。当默认值被使用的时候，服务端MUST表现得好像这个值为默认值的这个leaf node就存在于data tree中一样。如果一个leaf有一个“default”声明，则该leaf的默认值就是“default”声明指定的值。否则，如果leaf的type有一个默认的值，并且该leaf不是强制出现(mandatory)的，则该leaf的默认值就是该type的默认值。在所有其它情况下，这个leaf没有一个默认值。 leaf的substatements +-+-+-+ | substatement | section | cardinality | +-+-+-+ | config | 7.19.1 | 0.1 | | default | 7.6.4 | 0.1 | | description | 7.19.3 | 0.1 | | if-feature | 7.18.2 | 0.n | | mandatory | 7.6.5 | 0.1 | | must | 7.5.3 | 0.n | | reference | 7.19.4 | 0.1 | | status | 7.19.2 | 0.1 | | type | 7.6.3 | 1 | | units | 7.3.3 | 0.1 | | when | 7.19.5 | 0.1 | +-+-+-+ leaf的type声明“type”声明MUST出现，有一个参数，是当前已有的内置或派生类型。在这个type上有可选的substatements指定了相关的restrictions。 leaf的default声明“default”声明，是可选的，其参数是一个字符串，包含了leaf的默认值。“default”声明的值MUST是有效可用的，不能违背对应type的规则。如果“mantory”为true，则“default”声明MUST NOT不能出现在nodes中。 leaf的mandatory声明The “mandatory” statement, which is optional, takes as an argumentthe string “true” or “false”, and puts a constraint on valid data.If not specified, the default is “false”.If “mandatory” is “true”, the behavior of the constraint depends onthe type of the leafs closest ancestor node in the schema tree thatis not a non-presence container: If no such ancestor exists in the schema tree, the leaf MUSTexist. Otherwise, if this ancestor is a case node, the leaf MUST exist ifany node from the case exists in the data tree. Otherwise, the leaf MUST exist if the ancestor node exists in thedata tree.This constraint is enforced according to the rules in Section .7 XML映射规则 A leaf node is encoded as an XML element. The elements local name is the leafs identifier, and its namespace is the modules XMLnamespace.The value of the leaf node is encoded to XML according to the type,and sent as character data in the element.A NETCONF server that replies to a get or get-config request MAYchoose not to send the leaf element if its value is the defaultvalue. Thus, a client that receives an rpc-reply for a get orget-config request, MUST be prepared to handle the case that a leafnode with a default value is not present in the XML. In this case,the value used by the server is known to be the default value. NETCONF OperationsWhen a NETCONF server processes an edit-config request, theelements of procedure for the leaf node are: If the operation is merge or replace, the node is created if it does not exist, and its value is set to the value found in the XML RPC data. If the operation is create, the node is created if it does not exist. If the node already exists, a data-exists error is returned. If the operation is delete, the node is deleted if it exists. If the node does not exist, a data-missing error is returned. 使用实例给定下面的“leaf”声明，放到之前定义的 “ssh”的container中（可见Section 7.5.9）： leaf port type inet:port-number; default 22; description The port to which the SSH server listens 对应的XML实例为： port2022/port在edit-config中设置leaf的值： rpc message-id=101 xmlns=urn:ietf:params:xml:ns:netconf:base:1.0 xmlns:nc=urn:ietf:params:xml:ns:netconf:base:1.0 edit-config target running/ /target config system xmlns=/schema/config services ssh port2022/port /ssh /services /system /config /edit-config /rpc1.1.2 Leaf-List Nodes一个leaf-list是一系列的leaf nodes，每个leaf都有特定类型的值。YANG 示例: leaf-list domain-search type string; description List of domain names to search; NETCONF XML 示例: /domain-search /domain-search /domain-search leaf-list声明“leaf”声明是被用来定义一个简单的特定类型的标量变量，而“leaf-list”声明被用来定义特定类型的一个数组。“leaf-list”声明有一个参数，是一个identifier，后面跟着描述具体内容的一块substatements。“leaf-list”的值MUST是唯一的。概念上来讲，data tree中的值总是以canonical form存在的。如果“leaf-list”引用的type有默认值，默认值对leaf-list不产生影响。 排序对于“list”和“leaf-list”声明，YANG支持两种风格的排序方式。在很多lists中，为了使被排列的列表项不影响列表配置的具体实现，设备能够以任何合理的顺序给list的列表项进行排序。不过在“description”中可能会有关于排序的建议。YANG称这种风格为“system ordered”，这种排序的声明为“ordered-by system”。YANG为NETCONF的操作提供了丰富的特性集以便列表能够以用户规定的方式进行排序。列表项可能会被插入，或重新排列到列表的第一项或最后一项，或者放到某一个特定列表项的前面或者后面。 leaf-list的substatements +-+-+-+ | substatement | section | cardinality | +-+-+-+ | config | 7.19.1 | 0.1 | | description | 7.19.3 | 0.1 | | if-feature | 7.18.2 | 0.n | | max-elements | 7.7.4 | 0.1 | | min-elements | 7.7.3 | 0.1 | | must | 7.5.3 | 0.n | | ordered-by | 7.7.5 | 0.1 | | reference | 7.19.4 | 0.1 | | status | 7.19.2 | 0.1 | | type | 7.4 | 1 | | units | 7.3.3 | 0.1 | | when | 7.19.5 | 0.1 | +-+-+-+ min-elements声明“min-elements”声明，是可选的，取值为一个非负的整型，是对有效列表项的一个约束。一个可用的“leaf-list”或者“list”MUST至少有min-elements个列表项。如果该声明不存在，则默认为0。The behavior of the constraint depends on the type of the leaf-listsor lists closest ancestor node in the schema tree that is not a non-presence container (see Section 7.5.1): If this ancestor is a case node, the constraint is enforced if anyother node from the case exists. Otherwise, it is enforced if the ancestor node exists.The constraint is further enforced according to the rules inSection .5 max-elements声明The “max-elements” statement, which is optional, takes as an argumenta positive integer or the string “unbounded”, which puts a constrainton valid list entries. A valid leaf-list or list always has at mostmax-elements entries.If no “max-elements” statement is present, it defaults to“unbounded”.The “max-elements” constraint is enforced according to the rules inSection .6 ordered-by声明“ordered-by”声明定义了列表中列表项的顺序是用户定义还是系统自定义。其参数是“system”和“user”中的一个。如果该声明没有出现，默认值是“system”。如果列表表达的是state date，RPC output parameters，或者notification content，则这个声明会被忽略，因为对以上三种数据，都没有排序的必要。.1 ordered-by systemThe entries in the list are sorted according to an unspecified order.Thus, an implementation is free to sort the entries in the mostappropriate order. An implementation SHOULD use the same order forthe same data, regardless of how the data were created. Using adeterministic order will make comparisons possible using simple toolslike “diff”.This is the default order..2 ordered-by user列表项的排序是用户通过edit-config中的特殊XML属性控制的。 XML映射规则A leaf-list node is encoded as a series of XML elements. Eachelements local name is the leaf-lists identifier, and its namespaceis the modules XML namespace.The value of each leaf-list entry is encoded to XML according to thetype, and sent as character data in the element.The XML elements representing leaf-list entries MUST appear in theorder specified by the user if the leaf-list is “ordered-by user”;otherwise, the order is implementation-dependent. The XML elementsrepresenting leaf-list entries MAY be interleaved with other siblingelements, unless the leaf-list defines RPC input or outputparameters. NETCONF 操作Leaf-list entries can be created and deleted, but not modified,through edit-config, by using the “operation” attribute in theleaf-list entrys XML element.In an “ordered-by user” leaf-list, the attributes “insert” and“value” in the YANG XML namespace (Section 5.3.1) can be used tocontrol where in the leaf-list the entry is inserted. These can beused during “create” operations to insert a new leaf-list entry, orduring “merge” or “replace” operations to insert a new leaf-listentry or move an existing one.The “insert” attribute can take the values “first”, “last”, “before”,and “after”. If the value is “before” or “after”, the “value”attribute MUST also be used to specify an existing entry in the leaf-list.If no “insert” attribute is present in the “create” operation, itdefaults to “last”.If several entries in an “ordered-by user” leaf-list are modified inthe same request, the entries are modified one at thetime, in the order of the XML elements in the request.In a copy-config, or an edit-config with a “replace” operationthat covers the entire leaf-list, the leaf-list order is the same asthe order of the XML elements in the request.When a NETCONF server processes an request, theelements of procedure for a leaf-list node are: If the operation is merge or replace, the leaf-list entry is created if it does not exist.If the operation is create, the leaf-list entry is created if it does not exist. If the leaf-list entry already exists, a data-exists error is returned.If the operation is delete, the entry is deleted from the leaf-list if it exists. If the leaf-list entry does not exist, a data-missing error is returned. 使用用例 leaf-list allow-user type string; description A list of user name patterns to allow; 对应的XML实例： allow-useralice/allow-user allow-userbob/allow-user为了在列表中增加一个新元素，使用edit-config中默认的操作“merge”： rpc message-id=101 xmlns=urn:ietf:params:xml:ns:netconf:base:1.0 xmlns:nc=urn:ietf:params:xml:ns:netconf:base:1.0 edit-config target running/ /target config system xmlns=/schema/config services ssh allow-usereric/allow-user /ssh /services /system /config /edit-config /rpc给定下面的用户排序的例子： leaf-list cipher type string; ordered-by user; description A list of ciphers; 下面的语句是要在“3des-cbc”后面插入一条新的cipher “blowfish-cbc”： rpc message-id=101 xmlns=urn:ietf:params:xml:ns:netconf:base:1.0 xmlns:nc=urn:ietf:params:xml:ns:netconf:base:1.0 xmlns:yang=urn:ietf:params:xml:ns:yang:1 edit-config target running/ /target config system xmlns=/schema/config services ssh cipher nc:operation=create yang:insert=after yang:value=3des-cbcblowfish-cbc/cipher /ssh /services /system /config /edit-config /rpc1.1.3 Container Nodes一个container node用来将相关的节点归总到一个subtree中。一个container node只有子节点，没有值。一个container可能会包含任何类型、任何数量的子节点(包括leafs，lists，leaf-lists以及containers)。YANG 示例: container system container login leaf message type string; description Message given at start of login session; NETCONF XML 示例: system login messageGood morning/message /login /system container声明“container”声明被用来定义一个schema tree中包含的内部数据节点(interior data node)。它有一个参数，是一个identifier，后面跟着一块描述详细信息的substatements。一个container节点没有一个值，但是在data tree中有一个列表的子节点。子节点都定义在container的substatements中。 Containers with PresenceYANG支持两种风格的containers，一种仅仅用于组织data nodes的垂直结构，一种出现在configuration中，有明确的意义。第一种风格中，container本身没有任何意义，它的存在仅仅是为了包含子节点。这是默认的风格。比如，同步光网络(SONET)的scrambling options的集合能被放到一个名为“scrambling”的container中，以增强配置结构的层次化，将这些节点整合到一起。这个“scrambling”节点本身没有意义，所以在它变成空的时候可以移除该节点。在第二种风格中，container本身就是配置型数据(configuration data)，表示配置型数据的一个简单bit。The container acts as both a configuration knob and a means of organizing related configuration. 这些containers的创建和删除操作都必须是明确无误的。YANG称这种风格的container为一个“presence container”，这意味着要使用“presence”声明，作为它的参数。比如，一个“ssh”的container可能会启动使用ssh方式将日志写进设备的能力，不过也能包含任何和ssh相关的configuration knobs，比如连接速率和重试次数限制。“presence”声明用来在data tree中给container的存在以语义。 container的substatements +-+-+-+ | substatement | section | cardinality | +-+-+-+ | anyxml | 7.10 | 0.n | | choice | 7.9 | 0.n | | config | 7.19.1 | 0.1 | | container | 7.5 | 0.n | | description | 7.19.3 | 0.1 | | grouping | 7.11 | 0.n | | if-feature | 7.18.2 | 0.n | | leaf | 7.6 | 0.n | | leaf-list | 7.7 | 0.n | | list | 7.8 | 0.n | | must | 7.5.3 | 0.n | | presence | 7.5.5 | 0.1 | | reference | 7.19.4 | 0.1 | | status | 7.19.2 | 0.1 | | typedef | 7.3 | 0.n | | uses | 7.12 | 0.n | | when | 7.19.5 | 0.1 | +-+-+-+ must声明“must”声明是可选的，其参数是一个字符串包含了一个XPath表达式。它被用来正式声明有效数据上的约束。当一个datastore可用时，所有的“must”约束都会对data tree中的每个data node，对于使用默认值的所有leafs进行概念上的评估。如果一个data node在data tree中并不存在，并且没有一个默认值，则它的“must”声明不会被评估。所有这样的约束MUST评估为true，这样data才是有效的。 The context node is the node in the data tree for which the “must” statement is defined. The accessible tree is made up of all nodes in the data tree, and all leafs with default values in use.可访问的tree取决于context node： If the context node represents configuration, the tree is the data in the NETCONF datastore where the context node exists. The XPath root node has all top-level configuration data nodes in all modules as children. If the context node represents state data, the tree is all state data on the device, and the running/ datastore. The XPath root node has all top-level data nodes in all modules as children. If the context node represents notification content, the tree is the notification XML instance document. The XPath root node has the element representing the notification being defined as the only child. If the context node represents RPC input parameters, the tree is the RPC XML instance