YANG Tutorial part 1

hello welcome to yang tutorial part 1 in this module we'll begin a detailed look at the yang data modeling language with a tutorial on all of the basic statements of yang this will be continued in yang tutorial part 2 where we'll get into more some more advanced yang statements first we'll take a look at the concept of yang modules we'll see that when you write yang data models you write some number of modules or modules can also be decomposed into sub modules so let's take a look at the module concept first here we see a example of a yang module header we'll see that they start first with this module declaration or module and then there's a name of the module when working with Comp D your file name should equal your module name so Acme - module should be contained an Acme - module dot yang each module begins with a namespace declaration which forms a unique identifier to distinguish this yang model from other yang models that may be in the system because when you're working with any Netcom base system and also with CAF d you will typically have some number of different yang models they form the entire model set for the system each yang module is uniquely identified in its own namespace after the namespace declaration we have the prefix statement this is used as a shorthand notation to refer to this namespace if we need to later in in this module so in that case we'd use Acme : and then something and that namespace is used to disambiguate references as needed if you have worked with XML schema previously the idea of namespaces and prefix are the same as in XML schema because remember Yang is an XML schema definition language it Maps one two one two XML after your module and namespace declarations you'll have some number of imports and includes that are used to bring in definitions from other gangs or to include sub modules there's an important difference between import and include that we'll talk about in a couple of slides your module header will also include identifying information such as the organization contact a description of the module and then some number of revision statements to uniquely identify the revision of this module using the revision information in yang gives you a powerful tool because when working with something like net comp in that hello exchange of net Kampf the net comp server and the device will advertise all the yang data models ie the yang modules which it has available in the revision of those modules that are present so that the management station knows exactly what a device has in it here is a basic sketch of what your typical contents of a gang module will be you'll have header information in the module you'll have some number of important include statements followed by local type definitions then any configuration or operational state data declarations and then also any action or RPC definitions or notification definitions for the import and include statements there's a subtle but important difference to keep in mind about import and include import is used to refer to definitions in another yang module it pulls in references from that file it does not pull in the body of the file that's being imported so you may have typed offs or groupings in another module which you wish to refer to it's very common when you're doing data modeling to write a module in which you have some common type definitions or groupings that you use across multiple yang modules the include statement is used to pull in sub modules into a main module a module does not have to be contained within one file you can decompose it as necessary for ease of maintenance design etc and the include statement totally pulls in that yang file so a yang import is similar to including a header file in your C code an include statement is similar to when you're writing C applications that are in multiple files you can pie them all each to object files and then finally link them into the final executable the ma and yang the include statement pulls the sub modules into the module so that then you've at the end have your fully formed namespace for that module for sub modules we have an example here on this slide on the left we have part of the main module Acme module which we see doesn't include of Acme system on the right we see the sub module Acme system so Acme module would be in the file Acme module yang the sub-module Acme system would be in the file Acme system dot yang you'll see the sub module does not have a namespace declaration instead it has a belongs to statement that it uniquely identifies what module this sub module belongs to a sub module belong specifically to only one module because it's part of that namespace also a sub module cannot reference definitions back in the main module which is including it you can only refer downwards you can't refer upwards so that's a basic introduction to the idea of modules now let's start talking about data types and then later on we'll see how the types actually get used as we pull together a full module yang has a rich set of base types all of these are defined in the yang RFC RFC number six zero to zero there are quite a few base types there there's a sampling of them here on the right there's various signed and unsigned integers strings boolean's enumerations etc a type that you use on an element that stores data such as a gang leaf or leaf list will have a type that can either be a base type or a derived type derived types might be a simple type or it might be a grouping a simple type such as a type def is an individual data item a grouping you can sort of think of as a structure it's a grouping of multiple data items that can be pulled together we'll show an example of a grouping later on during this module for derive types the yang type def statement is used so it defines a new simple type you take a type either one of the yang base types or a previously declared type tough derive from it and add some restrictions this is very similar to how a simple type works in XML schema so here we have an example where we're defining a type def called percent it's based on the unsigned 16 bit integer base type but has added a restriction where it can take a range of 0 to 100 so when we have this leaf called completed it has a type called percent so completed can be take the values of 0 to 100 as a salt in cough D the sort of syntactic constraint of zero to 100 is automatically enforced by comedy when you enter your data you don't have to write any syntactic validation code for your system when using comedy because we automatically enforce that from the yang definitions so a bit more on the types of restrictions you can use when you using a yang type def here we show a couple examples using integers on the left now Matt my bass int32 type is based on a 32-bit signed integer and then it can take on the values of 1 2 4 or 10 to 20 so that vertical bar is used for or just like in many programming languages from the C family below that we see another type def of derived in 32 which is based on that my base in 32 type we previously declared derived in 32 can take on the range of 11 to max so what this restriction does is take the restrictions of the base type and then apply the derived restrictions on top of it so in this case derived in 32 may take on the values from 11 to 20 since on the base taper deriving from its maximum value is 20 on the right we see an example of strings so we have my base string type which can be a string and that string is restricted to be the length of 1 to 255 you can enter any data in that string as long as there's 1 to 255 characters in it now below that we make type def derive string that we derive from my base string type here we're adding 2 restrictions now the length restriction is 11 or 42 to max so our string may contain 11 character or it may contain 42 to 255 characters it may not contain 25 characters that would be a violation in addition we've used the pattern attribute on this type so that it must meet this regular expression of this can only be an alphanumeric entry into the string again these syntactic restrictions since we can formally and precisely declare them in yang cough D will enforce for us next we have the Union statement sometimes we have values that we want to have that may be a number or a string depending on what the user enters in what we want to use in our program that is where the yang Union statement comes into play it allows the creation of these special types it works much like the idea of a union in the C programming language here we see that we've declared a type called threshold and we use type Union within threshold so Union can be an unsigned 16-bit integer which takes the values of zero to a hundred or it can be an enumeration with one e new value of disabled so this means the user can enter the value of zero to a hundred or disabled in for example the Comedie CLI this will be rendered then where when they're setting the value of something which has type threshold they can enter you know any number between 0 or 100 or the word disabled past the base types defined in the yang RFC there are also a number of common type deaths especially for the world of networking defined by the IETF in RFC 6:02 1 so to pull in these common type definitions and use them in our module that is where we knew is the import statement so RFC 6:02 one is contained in a module called IETF yang types so we import it most commonly by convention people use the prefix yang when they're importing the standards-based module there is no requirement for you to do so but it is a common convention and can prevent confusion so here also is the first time we've seen a use of the prefix earlier we had talked about defining a namespace and having a prefix or when you do an import declaring a prefix if you need to refer to something so here we see if someone wants to use for example the counter 64 type def from IETF yang types they'll say type yang : counter 64 on the right in this table you see a list of some of the types defined in IETF yang types but you can see a number of things that are very commonly used when doing network devices you have the idea of things like MAC addresses IP addresses prefixes etc so this is certainly a yang module that you should take a look through in fact any of the IETF standard based modules such as 60 21 there are a number of them out there now are good gang models to look through when you're getting started to see examples of real world production use of yang the grouping statement the grouping statement allows us to form a grouping of common types that we often use in our data model for example oftentimes you'll use an IP address and port number in combination instead of having two during our yang module right you know leaf address leaf port constantly all over our models we can instead declare a grouping that we later reuse in some way this console is similar to a structure definition in the C programming language but here we see an example a grouping called target that contains a leaf called address a leaf called port the grouping can contain any yang structure doesn't just have to be a list of leaves there could be containers there could be you know a hierarchical structure in there which then gets inserted at the point that it's actually used here we see that the types are IP address and port number that come in from some module we've imported previously and given the prefix of inet and hence the use of inet colon there after that grouping definition we see below it use of that actual grouping we have a couple of yang containers and then uses target container and yang organizes our tree or hierarchy so we see sort of a pictorial representation of that on the right we've got peer and destination in our tree and then after destination both address and port show up from having the grouping we look at the tree there's no sign of the grouping once it's been used there is simply the content of the grouping shows up at that location you will commonly have groupings you use across all your gang models you'll commonly have type deaths you use all across your gang models those should be gathered together in a yang module very often times people will do a module that is company name - command yang for example tail laughs - comm and yang you'll see a lot when you're working with comedy in there you can put type deaths and groupings and then use them in other yang modules you can also refine a grouping statement when you use it you may have a common grouping but you want to tweak it a little bit when you actually use it in particular places there yang refine statement allows you to do this so here we see on the left a grouping definition of called target that provides leaf address and leaf port and then on the right we see an example of a use of it we've got a couple containers and then uses target but within uses target we say refine port default 80 so what this does is take the leaf port and add the default 80 attribute to that leaf so in this case when under server's HTTP the port number will have a default value of 80 so if someone hasn't entered a value we've defined its default port value to be 80 so we finished looking at basic yang types let's look more now at the yang data definitions that will use these types where we'll define and organize our actual hierarchy of data so first we have the leaf statement a leaf holds a single value of a particular type we've seen a couple uses of leaf already as we were talking about types but here we see the formal definition of leaf there will be leaf a leaf will have a name it will have no children you know if you think of your yang hierarchy or tree it is a graph that graph has interior nodes and final terminal nodes in the tree a leaf node is a terminal node in that tree there is nothing below it it simply has a type it holds data so a leaf must have a type attribute to declare its type and then pass that there are a number of different attributes that may be applied to a leaf many of these attributes if not present have a default value is defined in the RFC so here we see a couple of examples we have a leaf called hostname that's of type string it's declared mandatory true so it must be present its config true meaning its configuration data in fact actually the default value of config is true so if config true was not there it would actually be as if it was there as an attribute and then of course a description secondly we see a leaf called CPU temp it has a type it has a units attribute it's declared config faults meaning it is not configuration data it is operational state data here we see a list of the attributes of that a leaf can have and then definitions some of the main ones you'll work with our config primarily config faults to declare your operational data default will give a default value for a leaf so if someone doesn't enter the value that default value will be used mandatory you know when the user is entering this data or it's coming in from something like Netcom does that data have to be present or is it optional must we'll see later on it it's a way of declaring integrity constraints or relationships between our data type etc through the rest of these attributes again you can get the full formal definition of all these attributes in the yang RFC container is our first organizational yang statement it is used to organize our Leafs into that hierarchy or tree if you think of your yang hierarchy as being you know a graph of a tree a container is an interior node of the tree it is only used for organizing the tree it doesn't have a type it doesn't hold data so here we see an example ample of container hierarchy of system contains services which contains a container called SSH now hear this SSH container has an attribute called presence a presence container is something special in yang a regular container is always there that structure always exists presence gives you the ability to have think of it as a dynamic or optional container it may or may not be there one technique you can use in data modeling is remember that things can sometimes have a meaning just by being present or not present so there are some cases in your data modeling where instead of having something be a boolean with true/false values it may be more natural to use something like presence to say you know if it is there or if it is not and that has meaning so here although container SSH may or may not have something in it most typically it probably does but if you haven't populated it that whole container doesn't have to be there in storage or in our hierarchy now leaf isn't the only data containing statement in yang there are some others that actually have types and hold data first is a leaf list a leafless has a type it holds data but it actually holds multiple data items so in this case our leaf list called domain search has a type of string this domain search can contain any number of distinct strings in a list a common mistake when people are first working with yang is to think of a leaf list as an array it really isn't it's a list it is a list of items now here in this domain search we see the attribute ordered by user ordered by kin also have the value of system by default leafless are ordered by system meaning you can populate items in that list and the system can decide what order to store them in or present them back to you so you may enter them in one order but later on when you show them they may be shown to you in a different order than entry because the system is free to order them and store them however it thinks is most efficient ordered by user allows the user to get to can control the order they are always presented if you do a show or if you access them from your applications ordered by user could be useful so for example this leafless that's called domain search this is a list of domain names that we want to search and we also want to make sure that they are searched in a particular order so may be most specific to most general closest server to furthest server so here they've been declared ordered by user to control that order next is the list statement the list statement you can think of as being analogous to a table definition by the strictest definition a list is not a table it is a list that contains entries but oftentimes when you're first learning yang if you think of a list as a table and the entries of the list is rows in that table using that conceptual analogy makes it easier to understand and initially work with so here we see a definition of a basic list it's a user list much like we'd have a user list say in a password file on a UNIX system a list will have a key statement to declare which of the list entries are the key values there can be multiple keys so these are essentially I'll think of as the key columns of your list by convention you should declare any of your key Leafs first in your list entry right after the key statement so after a key declaration we see the Leafs name UID full name class which you can think of as the columns of our row declared here and we see up top now kind of a pictorial representation of this list entry lists are similar to leafless they could be ordered by system or ordered by user most commonly unless you have a real need to control the order you just leave it at its default value of ordered by system since ordered by doesn't show up here in this definition its default value of system is used now lists and leafless have some attributes that you can declare for them in your data model we've already talked about ordered by in previous slides you can also have mid elements and max elements to bound how many entries may be in the table perhaps you have a table that can contain 0 to 1,024 entries in that case your mid elements could just use its default value of 0 and you just say max elements 1024 this is an integrity constraint of our data which will automatically be enforced by comedy comedy if you have that limit of 1024 maximum elements comedy will enforce that for you and to prevent the user from creating more entries from that lists have key entries the key is we mentioned earlier there can be one or more keys if there are multiple keys it's the combination of the keys which must be unique the key field is used to specify which list entry ie row we're referring to and so as a result Keys must be uniqueness and again uniqueness of keys is automatically enforced by county now an important thing that we see in the lower right here are what is called key paths in yang if you need to refer to specific data items you'll use an XML XPath when working with comp'ny we use a simplified variant of XPath which we call key paths to refer to items a key path is simply a separated list of names which is the path within the tree so much like when you're working with a file system and you have a directory path down to a file you have in yang a path to a data item in the comedy API s we will see that these key paths are used to specify items when we're interacting with comedy from our application code if you need to specify specific key values to get to specific rows that is when this curly brace notation is used so user and name come from our yang hierarchy where we had the list user and a leaf called name but if we need to get say name UID from a specific row we need to provide the key value or values for that row so in this case we see a populated sample table so using the user name yang we want to say what is the U ID of the user yang this key path slash user curly yang curly slash UID is used to refer to it if you had multiple keys in a gang list you would space separate the key values within the curly braces you could have different keys based on your declaration as well depending on what you want to have in your in your yang file we also do have and comedy the concept of what we call secondary indexes where you may have one key or set of keys declared in your yang module but you often want to traverse the yang list and you know ordered by based on some other field so you can use the secondary index concept in comfort II as well now I previously had mentioned keys we have uniqueness and forced on them however sometimes in your yang lists or tables you have some non key entries or columns that you want to be unique perhaps you have a list of server names and you want the combination of IP address and port number for that server to be unique across all rows of that table that is where the unique statement comes into play you can form uniqueness groups like in this slide one field so name we've changed our key to be user ID and then we have the name column but we want all user even though UID is our key we want all user names to be unique so we add the unique attribute to the list to have that uniqueness group there can be multiple uniqueness groups and within a uniqueness group the combination of items must be unique here we see some examples of multiple keys in a table here we have a simple route table which is keyed by an IP address and a prefix value so the combination of IP and prefix is what must be unique across our table so here we see in our list declaration the key statement having both IP and prefix present and then also an example of a key path where in the curly braces we have the values of the IP address and the prefix separated by a space within the curly brackets note that that key order is significant the values of keys within the curly brackets of a key path must match the order that those keys appear in the yang data model next we have leaf ref leaf ref is used to model relationships or constraints among different parts of our data model if you have worked with XML schema previously and are familiar with XML schemas concept of a key Ralph a leaf ref in yang works similarly however in XML schema a key ref can only refer to a key field a leaf ref is more generalized and can refer to any leaf in the model so effectively what me it means is when we get to that point of a leaf ref the only values that can be selected our values from what is being pointed at by the leaf ref so here we first have in our model somewhere an interface table as shown in the upper left but then we also somewhere else in our model some rip routing information so we see the model for that rip information is a list of network interface names that are that we're using rip over and any interface name we put into this list is of type leaf ref pointing to the path and in this case the path since we're in yang is actually an axe path of slash interface slash name so what this means is what I'm populating that rip network interface name table when I select values for I F name it is only valid for them to be existing values in the interface table the interface name path that's pointed to from that path argument so since here I have 3 interface names defined when I populate if' name those are my only valid choices when you're working with cough D and any of the auto rendered human-machine interfaces you'll see that the user is constrained to only entering those values cough D automatically enforces those leaf wraps for you similarly for things such as net comp that enforcement is done as well now also in this case so say I F name is pointing to e 0.19 someone cannot go into the interface table and delete e 0 19 because there is a existing leaf ref that is pointing to it that referential integrity is maintained if someone tries to delete eat 0 19 from the interface table they'll get an error because it's being referred to so this prevents creation of dangling references they'd first have to remove the reference to eat 0 19 from their rip I F name then they could remove it from the interface table so again LD sorts of integrity constraints etc are all examples of the automatic validation that cough D does for you just based on having defined it in the yang data model now there are cases where you may want to do a leaf Ralf to another list but that list has multiple key values and so you need to refer to both of them and keep that combination unique so that is where a proper use of ax paths and your leaf ref definitions comes into play so here in our example we have a container called video that has a a IP address and a port number that needs to be selected from the client table so declaring the first key of VIP is simple we do a typed up or a type of leaf ref that has the path of client IP now we if you look at that populated example you see client IP 12 36 219 appears twice with two different port numbers so once we've pointed to an IP we want to constrain the user so that they can only select ports that come from the selected IP so then when we declare this leaf V port its leaf ref type has an X path of you know you can see the main parts on the left and right of client and port but within square brackets which is used to select a node set within X path we see IP equals current meaning the value of the the current node slash dot dot slash VIP so this allows us to kind of go up the tree back down and what this X path incantation does is say take the value starting at the current node which is pointing at V port dot dot takes us up to video and then finally the slash of e IP takes us to VIP so in the video list in this row entry taking the IP value that is in this row entry and then using that to look up in the client table to get the ports that are valid for that IP so by writing this X path we've gotten that extra integrity constraints so we can do a multiple key leaf run we'll see more about key paths in subsequent modules in this training video series there is one thing though in comedy that helps with XPath that is a tail F extension to XPath which is the DRF operator so I just sat and explained how these key references work of IP equals current blah blah blah if you start having say three keys like we show in this example on the left by the time we get to that third key the XPath gets a little bit more convoluted to declare so as syntactic sugar we've introduced this D ref operator that allows you to more easily refer to these paths so you know if you look on the yellow highlights here on the slide you can see the standard XPath statement and then the simplified version using the DRF operator which makes it much easier to implement now let's talk about the idea of actions and notifications to wrap up this module in yang you can declare actions also known as our pcs indebt Kampf net comp is an extensible protocol you can add new operations ie are PCs to the Netcom protocol which will then allow you to trigger something to happen specific in your device and this can be done via the RPC declaration this is the yang declaration of a new Netcom RPC in cough D we will also render these as actions you can trigger from other interfaces or API s so here we show a simple RPC definition our pcs have a name this will be the actual RPC name used in the Netcom protocol when the RPC request comes from the management station and the RPC can have both input and output parameters declared for it here we have a simple parameter declaration we have one input leaf called image 1 output leaf called status you can have any sort of yang hierarchy within those input and output parameter declarations they could be a container could be lists whatever meets your actual needs now when defining a new RPC keep in mind that if you are using it over net cough your device will accept that our PC process it provide the returns but then your net cough client and with your management station must also know about this RPC and be able to use it by having it declared in the yang module this gives your manager the knowledge that that RPC exists and if the management stations been implemented to actually then take that from the Yang and use it you may do so also yang is used to declare any of our net cough notifications net cough notifications are a way of having the device be able to Sun event information to the management station much like in SNMP we have traps we've talked about net cough notifications in a separate module of this training series but to declare the notifications that your device might send they are declared in your yang data model so here we see an example of a notification definition there's a notification a name and then some sort of contents for the payload that will be sent with that notification this payload can be any sort of yang higher gear structure there here we're sending a notification called config change the notification contains two parameters a leaf that here is the operator name and then a leaf list which is a list of the changes they've made so for example in the XML that comes out that change list would look like what appears here at the bottom of the slide so that brings us to the end of gangue tutorial part 1 this has given you a introduction to the very basics of Yang types data definitions are PCs and notifications in the follow-on module yang tutorial part 2 we'll take a look at some of the more advanced statements in the yang data modeling language thank you

Channel: Tail-f Systems

Views: 50,113

Rating: 4.9573336 out of 5

Keywords:

Id: AdIcYrz3AjU

Length: 44min 15sec (2655 seconds)

Published: Wed Mar 04 2015