idnits 2.17.1 draft-xia-nai-modeling-language-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 24, 2014) is 3744 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'NAI-ARCH' is mentioned on line 101, but not defined Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Y. Xia 2 Internet Draft S. Jiang 3 Intended status: Standards Track X. Wang 4 Expires: July 28, 2014 B. Liu 5 Huawei Technologies 6 January 24, 2014 8 Network Abstract Interface (NAI) Modeling Language 9 draft-xia-nai-modeling-language-00.txt 11 Abstract 13 This document introduces a modeling language used to model network 14 services by network operators and customers to create specific 15 network service instances through the standardized Network Abstract 16 Interface (NAI) and processed automatically by the network. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six 29 months and may be updated, replaced, or obsoleted by other documents 30 at any time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 28, 2014. 35 Copyright Notice 37 Copyright (c) 2011 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with 45 respect to this document. Code Components extracted from this 46 document must include Simplified BSD License text as described in 47 Section 4.e of the Trust Legal Provisions and are provided without 48 warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction ................................................. 3 53 2. Requirements Language and Terminology ........................ 3 54 3. Requirements for a NAI Modeling Language ..................... 3 55 4. NAI Modeling Language Overview ............................... 3 56 5. NAI Modeling Language Syntax and Statements .................. 5 57 5.1. Lexical Rules ........................................... 5 58 5.1.1. Comments ........................................... 5 59 5.1.2. Tokenization ....................................... 5 60 5.2. Identifiers ............................................. 6 61 5.3. NML Statements .......................................... 6 62 5.4. Typedef Statements ...................................... 7 63 6. NAI Modeling Language Blocks Definition ...................... 7 64 6.1. Entity Block ............................................ 7 65 6.2. Capability Block ....................................... 10 66 6.3. User Block ............................................. 12 67 6.4. Service Logic Block .................................... 14 68 6.5. Open Profiles Block .................................... 15 69 7. Security Considerations ..................................... 15 70 8. IANA Considerations ......................................... 15 71 9. References .................................................. 15 72 9.1. Normative References ................................... 15 73 9.2. Informative References ................................. 15 74 10. Acknowledgments ............................................ 15 75 Authors' Addresses ............................................. 17 77 1. Introduction 79 In [NAI-ARCH], a model-driven Network Abstract Interface 80 architecture is described. The models are customizable through a 81 model framework and described by network administrators using a NAI 82 modeling language (NML), which is introduced in this document. 84 The modeling language used to model network services by network 85 operators or customers to create specific network service instances 86 through the standardized Network Abstract Interface (NAI) and 87 processed automatically by the network. 89 2. Requirements Language and Terminology 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 93 "OPTIONAL" in this document are to be interpreted as described in 94 [RFC2119] when they appear in ALL CAPS. When these words are not in 95 ALL CAPS (such as "should" or "Should"), they have their usual 96 English meanings, and are not to be interpreted as [RFC2119] key 97 words. 99 3. Requirements for a NAI Modeling Language 101 For the characteristics of the NAI architecture in [NAI-ARCH], there 102 are some requirements for the modeling language: 104 o The language should provide different capabilities and visibility 105 of the network for different users. 107 o The language should be simple and easy to use for network 108 administrators. 110 o The syntax and keywords should be network related and intuitive. 112 o The language should support service logic description as well as 113 service content description. 115 4. NAI Modeling Language Overview 117 NML is used to design specific model for the specific network based 118 on the requirement of opening the network. And the specific model 119 automatically generates specific NAI for the network. The 120 application developer also uses NML to design service logic to 121 access network information and functions. 123 Different users can have different models to implement their 124 customized service requirement and innovative service application. 125 The common interface styles can be used, such as RESTFul style 126 [RESTFUL]. 128 An NAI model is constructed by five blocks: entity block, 129 capability block, user block, service logic block and open profile 130 block. The following figure depicts the relation between the blocks. 132 +-------+ +----------------+ +-------+ 133 | |<--->| User Block |<--->| | 134 | | +----------------+ | | 135 |Service| | Open | 136 | | +----------------+ | | 137 | Logic |<--->|Capability Block|<--->|Profile| 138 | | +----------------+ | | 139 | Block | || | Block | 140 | | +----------------+ | | 141 | |<--->| Entity Block |<--->| | 142 +-------+ +----------------+ +-------+ 144 Figure 1 NAI Modeling Language Blocks 146 Entity Block: describes the network entity that is opened to the 147 user, e.g. network device, device group, port, virtual network 148 device and so on. The property of entity describes the static 149 information of entity, and the statistics of entity describes the 150 statistics and runtime information of entity. 151 NML provides an inheritance mechanism to define the reusable 152 information about each entity. An inherited entity can be defined in 153 another entity to include its definition information so as to avoid 154 repetition. 156 Capability Block: describes the capability that is opened to the 157 user. Capability is a set of network functions and operations that 158 encapsulated together and provided to the users e.g. VPN. 160 User Block: describes the information about the user group, 161 including the basic user group information, authentication and 162 account information. It distinguishes the user group classified 163 profiles. 165 Service Logic Block: describes a set of network management functions 166 based on the user's requirement. A service logic block provides the 167 ability to specify automatic, logic control, monitoring, 168 configuration and maintenance for the administrator and NAI 169 application designer. For example, a NAI application can modify the 170 VPN routing automatically in response to the network load of 171 specified network link, or configure different links for one 172 important enterprise customer between two sites in day or night to 173 meet the SLA requirement. A service logic block designed by one 174 designer can be opened to others to reuse its features, improve NAI 175 ecosystem, support and accelerate growing and innovative network 176 applications. 178 Open Profile Block: describes the different authorization and 179 visibility of entity and capability opened for different user. 181 The following section will introduce syntax and keywords for the 182 five blocks. 184 5. NAI Modeling Language Syntax and Statements 186 The NML syntax is similar to the programming languages like C 187 because of the support of service logic. 189 5.1. Lexical Rules 191 5.1.1. Comments 193 A comment is text that the compiler ignores but that is useful for 194 programmers. Comments are normally used to annotate code for future 195 reference. The compiler treats them as white space. The comment is 196 written in one of the following ways: 198 - The /* (slash, asterisk) characters, followed by any sequence of 199 characters (including new lines), followed by the */ characters. 200 This syntax is the same as ANSI C. Therefore, it is commonly called 201 a "block comment." 202 - The // (two slashes) characters, followed by any sequence of 203 characters. A new line not immediately preceded by a backslash 204 terminates this form of comment. Therefore, it is commonly called a 205 "single-line comment." 207 5.1.2. Tokenization 209 A token is the smallest element of a NML that is meaningful to the 210 compiler. The NML parser recognizes these kinds of tokens: 211 identifiers, keywords, literals, operators, punctuators, and other 212 separators. A stream of these tokens makes up a translation unit. 213 Tokens are usually separated by "white space." White space can be 214 one or more: Blanks, Horizontal or vertical tabs, New lines, Form 215 feeds. 217 5.2. Identifiers 219 An identifier is a sequence of characters used to denote different 220 kinds of NML items by name. Each identifier starts with an uppercase 221 or lowercase ASCII letter or an underscore character, followed by 222 zero or more ASCII letters, digits, underscore characters, hyphens, 223 and dots. 225 Each identifier has its namespace. Each identifier is valid in a 226 namespace that depends on the type of the NML item being defined. 227 All identifiers defined in a namespace MUST be unique. 229 - All entity names share the same global entity identifier 230 namespace. 232 - All capability names share the same global capability 233 identifier namespace. 235 - All user names share the same global user identifier namespace. 237 - All service-logic-names share the same global service logic 238 identifier namespace. 240 - All property-names share the same identifier namespace defined 241 in the entity's property statement. 243 - All statistics-names share the same identifier namespace 244 defined in the entity's statistics statement. 246 - All para-names share the same identifier namespace defined in 247 the capability parameters statement. 249 - All output-names share the same identifier namespace defined 250 in the capability outputs statement. 252 5.3. NML Statements 254 A NML model file contains a sequence of statements. Each statement 255 starts with a keyword, followed by zero or one argument, followed 256 either by a semicolon (";") or a block of substatements enclosed 257 within braces ("{ }"): 259 statement = keyword [argument] (";" / "{" *statement "}") 261 Expression statements, Selection Statements, Compound Statements, 262 Iteration Statements are used in NML-script-logic statement body. 264 5.4. Typedef Statements 266 The typedef Statement defines a new derived type from base data type. 267 It is followed by the derived type name immediately. 269 - The description statement 271 The "description" statement provides the human-readable descriptive 272 string by the modeler for the NBI application designer to understand 273 the new derived type. 275 - The basetype statement 277 The basetype statement defines the base type name from which the new 278 type is derived. The base type can be primitive type or derived type. 280 - The default statement 282 The default statement defines the default value for the new derived 283 type. There may be default value conflict between the base type and 284 derived type. Only the default value with conforming to the type 285 definition is valid. The valid derived type default has higher 286 priority than that of base type. If base type is provided with 287 default value and derived type is not, the default value of base 288 type is used for derived type when it is valid for derived type. 290 6. NAI Modeling Language Blocks Definition 292 6.1. Entity Block 294 Entity block contains the following statements: 296 o Class: defines entity's classification. It is enumeration type. 298 o Description: takes a string that contains a human-readable textual 299 description of this definition. The text is provided in a language 300 (or languages) chosen by the module developer. 302 o Version: defines the version number of current entity. 304 o Import: provides a reference mechanism to refer the property and 305 statistics information of imported entity to the importing entity. 306 The data part of the imported data structure is stored in the 307 imported entity. 309 o Inherit: provides a include mechanism to combine the property and 310 statistics information of inherited entity into the inheriting 311 entity. 313 o Property: defines a data structure of property of the entity. Its 314 sub-statements include property-name, type, description, default. 315 The statements (property name, type, description, default) are 316 combined into one property data structure body. One "property" can 317 have one or more than one property data structure body. 319 - Property-Name: defines the name of the property item. The 320 property name must be unique in one "property" statement. This 321 document does not define its naming rule, but it recommends that 322 the name should be simple, human-readable and human- 323 understandable. 324 - Type: defines the data type of the property in property data 325 structure body. The built-In types and derived types can both be 326 used. 327 - Description: provides the human-readable descriptive 328 information by the modeler for the NAI application designer to 329 understand the property item in the property data structure body. 330 - Default: defines the default value for the property item in 331 the property data structure body. If no value for this property 332 is provided when the entity is instantiated or data record is 333 inserted into the entity, the default value will be used. One 334 property data structure body can have zero or one default 335 statement. If no default statement exists, no default value is 336 provided. 338 o Statistics: defines a data structure of statistics information of 339 the entity. Its sub-statements include statistics-name, type, 340 description, default. The statements (statistics-name, type, 341 description, default) are combined into one statistics data 342 structure body. One "statistics" can have one or more than one 343 statistics data structure body. 345 - Statistics-Name: defines the name of the statistics item. The 346 statistics-name must be unique in one "statistics" statement. 347 This document does not define its naming rule, but it recommends 348 that the name should be simple, human-readable and human- 349 understandable. 350 - Type: defines the data type of the statistics item in the 351 statistics data structure body. The built-In types and derived 352 types can be used in this statement. 353 - Description: provides the human-readable descriptive 354 information by the modeler for the NBI application designer to 355 understand the statistics item in the statistics data structure 356 body. 357 - Default: defines the default value for the statistics item in 358 the statistics data structure body. If no value for this 359 statistics item is provided when the entity is instantiated or 360 data record is inserted into the entity, the default value will 361 be used. One statistics data structure body can have zero or one 362 default statement. If no default statement exists, no default 363 value is provided. 365 o Description: takes a string that contains a human-readable textual 366 description of this definition. The text is provided in a language 367 (or languages) chosen by the module developer. 369 Following is an example of entity block definition. 371 enum class /*define some classes of entity*/ 372 { 373 ip_device; 374 optical_device; 375 ...; 376 } 378 entity DCI_PE // entity name 379 { 380 class ip_device; // class is enum type 381 description "this is a model for DCI PE device"; 382 version 1.0; 383 inherit device; 384 property 385 { 386 property_name loc;//the name of the property 387 { 388 type uchar; 389 description "the location of the entity"; 390 } 391 property_name ipaddr;//the name of the property 392 { 393 type ulong; 394 description "the ip address of the entity"; 395 } 396 ... ; 397 } 398 statistics 399 { 400 statistics_name inpacket_num;//the name of the property 401 { 402 type ulong; 403 description "the number of the inpacket"; 404 } 405 ... ; 406 } 407 } 409 6.2. Capability Block 411 Capability block contains the following statements: 413 o Class: defines capability's classification. It is enumeration type. 415 o Description: provides the human-readable descriptive string by the 416 modeler for the NAI application designer to understand the 417 capability. 419 o Version: defines the version number of current capability. 421 o Parameters: defines the input parameters for network to execute 422 the capability. It provides a mean for NAI application designer to 423 implement his special service requirement through customized network 424 parameters in his service case. Its sub-statements include para-name, 425 type, description, default. The statements (para-name, type, 426 description, default) are combined into one parameters structure 427 body. One "parameters" statement can have zero, one or more 428 parameters structure body. 430 - Para-Name: defines the name of the parameter. The parameters 431 must be unique in one parameters structure body. This document 432 does not define its naming rule, but it recommends that the name 433 should be simple, human-readable and human-understandable. 434 - Type: defines the data type of the parameter in the parameters 435 structure body. The built-In types and derived types can be used 436 in this statement. 437 - Description: provides the human-readable descriptive 438 information by the capability provider for the NAI application 439 designer to understand the parameter in the parameters structure 440 body. 441 - Default: defines the default value for the parameter in the 442 parameters structure body. If no value for this parameter is 443 provided when the capability is executed, the default value will 444 be used. One parameters structure body can have zero or one 445 default statement. If no default statement exists, no default 446 value is provided. 448 o Outputs: defines the output results from network after executing 449 the capability. It provides a mean for NAI application designer to 450 get the network entity property, statistics, or other response in his 451 service application case. Its sub-statements include output-name, 452 type, and description. The statements (output-name, type, description) 453 are combined into one outputs structure body. One "outputs" statement 454 can have zero, one or more outputs structure body. 456 - Output-Name: defines the name of the output. The output-name 457 must be unique in one outputs structure body. This document does 458 not define its naming rule, but it recommends that the name 459 should be simple, human-readable and human-understandable. 460 - Type: defines the data type of the output parameter in the 461 outputs structure body. The built-In types and derived types can 462 be used in this statement. 463 - Description: provides the human-readable descriptive 464 information by the capability provider for the NAI application 465 designer to understand the output parameter in the outputs 466 structure body. 468 o Execution-Link: takes one argument of string as the name of the 469 execution link and two other statement to define its type and 470 description. 472 - Type: defines the type of the execution link in the capability. 473 It is enumeration type. 474 - Description: provides the human-readable descriptive 475 information by the capability provider for the NAI application 476 designer to understand the execution link. 478 Following is an example of capability block definition. 480 enum class /*define some classes of capability*/ 481 { 482 network cap; 483 Service cap; 484 ...; 485 } 487 capability vpn // capability name 488 { 489 class network cap; // class is enum type 490 description "this is a model for creating vpn capability"; 491 version 1.0; 492 parameter 493 { 494 para name pe;//the name of the property 495 { 496 type ulong; 497 description "the IP address of the PE"; 498 } 499 para name connection;//the name of the property 500 { 501 para name src; 502 { 503 type ulong; 504 description "the source ip address of the connection"; 505 } 506 para name dst; 507 { 508 type ulong; 509 description "the destination ip address of the 510 connection"; 511 } 512 ... 513 } 514 ... ; 515 } 516 output 517 { 518 output name http link; 519 { 520 type string; 521 description "the output is a http link"; 522 } 523 ... 524 } 525 execution link 526 { 527 exec name exec link; 528 { 529 type string; 530 description "the name of execution body"; 531 } 532 parameter pe; 533 parameter connection; 534 ... 535 } 536 } 538 6.3. User Block 540 User block contains the following statements: 542 o Usergrp: defines user group classification to which administrator 543 wants to open entities and capabilities. The "usrgrp" statement 544 takes one argument of string as the name of the entity and one 545 usrgrp structure body to describe the details of the usrgrp. 547 o Description: takes a string that contains a human-readable textual 548 description of this definition. The text is provided in a human 549 language (or languages) chosen by the module developer. 551 o Information: defines a data structure of information of the usrgrp. 552 Its sub-statements include info_name, type, description, default. 553 The statements (info_name, type, description, default) are combined 554 into one information data structure body. One "information" 555 statement can have one or more than one information data structure 556 body. 558 - info_name: defines the name of the information item. The 559 info_name must be unique in one "information" statement. This 560 document does not define its naming rule, but it recommends that 561 the name should be simple, human-readable and human- 562 understandable. 563 - type: defines the data type of the information in information 564 data structure body. The built-In types and derived types can be 565 used in this statement. 566 - default: defines the default value for the information item in 567 the information data structure body. If no value for this 568 information is provided when the usrgrp is instantiated or data 569 record is inserted into the usrgrp, the default value will be 570 used. One information data structure body contains zero or one 571 default statement. If no default statement exists, no default 572 value is provided. 574 o Authentication: defines the authentication mode of the usrgrp, 575 which is followed by an "enum" variable. So administrator needs to 576 define all the allowed authentication mode with an "enum" variable 577 ahead. 579 o Charge: defines the charge mode of the usrgrp, which is followed 580 by an "enum" variable. So administrator needs to define all the 581 allowed charge mode with an "enum" variable ahead. 583 Following is an example of user block definition. 585 enum authes 586 { 587 non; 588 ipsec; 589 ...; 590 } 592 enum charges 593 { 594 buflow; 595 plan1; 596 ...; 597 } 599 usergrp OTT user // usergrp 600 { 601 description "this is a model for OTT user"; 602 information 603 { 604 info name name;//the name of the property 605 { 606 type uchar; 607 description "the name of the entity"; 608 } 609 ... ; 610 } 611 authentication authes; 612 charge charges; 613 } 615 6.4. Service Logic Block 617 Service logic block contains the following statements: 619 o Selection: mainly includes "if-else" and "switch". 621 o Expression: causes expressions to be evaluated. No transfer of 622 control or iteration takes place as a result of an expression 623 statement. 625 o Compound statement consists of zero or more statements. A compound 626 statement can be used anywhere a statement is expected. 628 o Iteration: causes statements (or compound statements) to be 629 executed zero or more times, subject to some loop-termination 630 criteria. When these statements are compound statements, they are 631 executed in order. NML provides three iteration statements -"while", 632 "do" and "for". 634 o Break: causes the innermost enclosing loop or a switch statement 635 to exit immediately. 637 o Continue: is similar to the "break" statement. Instead of exiting 638 a loop, however, "continue" restarts a loop in a new iteration. 640 o Operators: NML support binary arithmetic operators, assignment 641 operators, comparison operators, bitwise operators and string 642 operators. 644 (An example needs to be filled in the future.) 646 6.5. Open Profiles Block 648 The open model is a bit map which the manager pictures based on open 649 requirements, which is fixed and needn't to be modeled. 651 7. Security Considerations 653 Since customers can order services directly through the NAI 654 interface, authentication and authorization is strongly needed. 656 8. IANA Considerations 658 None. 660 9. References 662 9.1. Normative References 664 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 665 Requirement Levels", BCP 14, RFC 2119, March 1997. 667 9.2. Informative References 669 [NAI-ARCH]Xia Y., Jiang S., and X. Wang, "Customizable Network 670 Abstract Interface (NAI) Architecture based on Model 671 Description", Work in Progress, January 2014 673 [RESTFUL] Roy Thomas Fielding, "Architectural Styles and the Design 674 of Network-based Software Architectures", 675 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_ar 676 ch_style.htm, 2000 678 10. Acknowledgments 680 Valuable comment was received from Brian E Carpenter. 682 This document was prepared using 2-Word-v2.0.template.dot. 684 Authors' Addresses 686 Yinben Xia (editor) 687 Huawei Technologies Co., Ltd 688 Q14, Huawei Campus, No.156 Beiqing Road 689 Hai-Dian District, Beijing, 100095 690 P.R. China 692 Email: xiayinben@huawei.com 694 Sheng Jiang (editor) 695 Huawei Technologies Co., Ltd 696 Q14, Huawei Campus, No.156 Beiqing Road 697 Hai-Dian District, Beijing, 100095 698 P.R. China 700 Email: jiangsheng@huawei.com 702 Xuewei Wang 703 Huawei Technologies Co., Ltd 704 Q14, Huawei Campus, No.156 Beiqing Road 705 Hai-Dian District, Beijing, 100095 706 P.R. China 708 Email: wangxuewei@huawei.com 710 Bing Liu 711 Huawei Technologies Co., Ltd 712 Q14, Huawei Campus, No.156 Beiqing Road 713 Hai-Dian District, Beijing, 100095 714 P.R. China 716 Email: leo.liubing@huawei.com