opendaylight/netconf/models/ietf-netconf/src/main/yang/ietf-netconf@2011-06-01.yang

   1 module ietf-netconf {
   2
   3   // the namespace for NETCONF XML definitions is unchanged
   4   // from RFC 4741, which this document replaces
   5   namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
   6
   7   prefix nc;
   8
   9   import ietf-inet-types {
  10     prefix inet;
  11   }
  12
  13   organization
  14     "IETF NETCONF (Network Configuration) Working Group";
  15
  16   contact
  17     "WG Web:   <http://tools.ietf.org/wg/netconf/>
  18      WG List:  <netconf@ietf.org>
  19
  20      WG Chair: Bert Wijnen
  21                <bertietf@bwijnen.net>
  22
  23      WG Chair: Mehmet Ersue
  24                <mehmet.ersue@nsn.com>
  25
  26      Editor:   Martin Bjorklund
  27                <mbj@tail-f.com>
  28
  29      Editor:   Juergen Schoenwaelder
  30                <j.schoenwaelder@jacobs-university.de>
  31
  32      Editor:   Andy Bierman
  33                <andy.bierman@brocade.com>";
  34   description
  35     "NETCONF Protocol Data Types and Protocol Operations.
  36
  37      Copyright (c) 2011 IETF Trust and the persons identified as
  38      the document authors.  All rights reserved.
  39
  40      Redistribution and use in source and binary forms, with or
  41      without modification, is permitted pursuant to, and subject
  42      to the license terms contained in, the Simplified BSD License
  43      set forth in Section 4.c of the IETF Trust's Legal Provisions
  44      Relating to IETF Documents
  45      (http://trustee.ietf.org/license-info).
  46
  47      This version of this YANG module is part of RFC 6241; see
  48      the RFC itself for full legal notices.";
  49
  50   revision 2011-06-01 {
  51     description
  52       "Initial revision;";
  53     reference
  54       "RFC 6241: Network Configuration Protocol";
  55   }
  56
  57   extension get-filter-element-attributes {
  58     description
  59       "If this extension is present within an 'anyxml'
  60        statement named 'filter', which must be conceptually
  61        defined within the RPC input section for the <get>
  62        and <get-config> protocol operations, then the
  63        following unqualified XML attribute is supported
  64        within the <filter> element, within a <get> or
  65        <get-config> protocol operation:
  66
  67          type : optional attribute with allowed
  68                 value strings 'subtree' and 'xpath'.
  69                 If missing, the default value is 'subtree'.
  70
  71        If the 'xpath' feature is supported, then the
  72        following unqualified XML attribute is
  73        also supported:
  74
  75          select: optional attribute containing a
  76                  string representing an XPath expression.
  77                  The 'type' attribute must be equal to 'xpath'
  78                  if this attribute is present.";
  79   }
  80
  81   // NETCONF capabilities defined as features
  82   feature writable-running {
  83     description
  84       "NETCONF :writable-running capability;
  85        If the server advertises the :writable-running
  86        capability for a session, then this feature must
  87        also be enabled for that session.  Otherwise,
  88        this feature must not be enabled.";
  89     reference "RFC 6241, Section 8.2";
  90   }
  91
  92   feature candidate {
  93     description
  94       "NETCONF :candidate capability;
  95        If the server advertises the :candidate
  96        capability for a session, then this feature must
  97        also be enabled for that session.  Otherwise,
  98        this feature must not be enabled.";
  99     reference "RFC 6241, Section 8.3";
 100   }
 101
 102   feature confirmed-commit {
 103     if-feature candidate;
 104     description
 105       "NETCONF :confirmed-commit:1.1 capability;
 106        If the server advertises the :confirmed-commit:1.1
 107        capability for a session, then this feature must
 108        also be enabled for that session.  Otherwise,
 109        this feature must not be enabled.";
 110
 111     reference "RFC 6241, Section 8.4";
 112   }
 113
 114   feature rollback-on-error {
 115     description
 116       "NETCONF :rollback-on-error capability;
 117        If the server advertises the :rollback-on-error
 118        capability for a session, then this feature must
 119        also be enabled for that session.  Otherwise,
 120        this feature must not be enabled.";
 121     reference "RFC 6241, Section 8.5";
 122   }
 123
 124   feature validate {
 125     description
 126       "NETCONF :validate:1.1 capability;
 127        If the server advertises the :validate:1.1
 128        capability for a session, then this feature must
 129        also be enabled for that session.  Otherwise,
 130        this feature must not be enabled.";
 131     reference "RFC 6241, Section 8.6";
 132   }
 133
 134   feature startup {
 135     description
 136       "NETCONF :startup capability;
 137        If the server advertises the :startup
 138        capability for a session, then this feature must
 139        also be enabled for that session.  Otherwise,
 140        this feature must not be enabled.";
 141     reference "RFC 6241, Section 8.7";
 142   }
 143
 144   feature url {
 145     description
 146       "NETCONF :url capability;
 147        If the server advertises the :url
 148        capability for a session, then this feature must
 149        also be enabled for that session.  Otherwise,
 150        this feature must not be enabled.";
 151     reference "RFC 6241, Section 8.8";
 152   }
 153
 154   feature xpath {
 155     description
 156       "NETCONF :xpath capability;
 157        If the server advertises the :xpath
 158        capability for a session, then this feature must
 159        also be enabled for that session.  Otherwise,
 160        this feature must not be enabled.";
 161     reference "RFC 6241, Section 8.9";
 162   }
 163
 164   // NETCONF Simple Types
 165
 166   typedef session-id-type {
 167     type uint32 {
 168       range "1..max";
 169     }
 170     description
 171       "NETCONF Session Id";
 172   }
 173
 174   typedef session-id-or-zero-type {
 175     type uint32;
 176     description
 177       "NETCONF Session Id or Zero to indicate none";
 178   }
 179   typedef error-tag-type {
 180     type enumeration {
 181        enum in-use {
 182          description
 183            "The request requires a resource that
 184             already is in use.";
 185        }
 186        enum invalid-value {
 187          description
 188            "The request specifies an unacceptable value for one
 189             or more parameters.";
 190        }
 191        enum too-big {
 192          description
 193            "The request or response (that would be generated) is
 194             too large for the implementation to handle.";
 195        }
 196        enum missing-attribute {
 197          description
 198            "An expected attribute is missing.";
 199        }
 200        enum bad-attribute {
 201          description
 202            "An attribute value is not correct; e.g., wrong type,
 203             out of range, pattern mismatch.";
 204        }
 205        enum unknown-attribute {
 206          description
 207            "An unexpected attribute is present.";
 208        }
 209        enum missing-element {
 210          description
 211            "An expected element is missing.";
 212        }
 213        enum bad-element {
 214          description
 215            "An element value is not correct; e.g., wrong type,
 216             out of range, pattern mismatch.";
 217        }
 218        enum unknown-element {
 219          description
 220            "An unexpected element is present.";
 221        }
 222        enum unknown-namespace {
 223          description
 224            "An unexpected namespace is present.";
 225        }
 226        enum access-denied {
 227          description
 228            "Access to the requested protocol operation or
 229             data model is denied because authorization failed.";
 230        }
 231        enum lock-denied {
 232          description
 233            "Access to the requested lock is denied because the
 234             lock is currently held by another entity.";
 235        }
 236        enum resource-denied {
 237          description
 238            "Request could not be completed because of
 239             insufficient resources.";
 240        }
 241        enum rollback-failed {
 242          description
 243            "Request to roll back some configuration change (via
 244             rollback-on-error or <discard-changes> operations)
 245             was not completed for some reason.";
 246
 247        }
 248        enum data-exists {
 249          description
 250            "Request could not be completed because the relevant
 251             data model content already exists.  For example,
 252             a 'create' operation was attempted on data that
 253             already exists.";
 254        }
 255        enum data-missing {
 256          description
 257            "Request could not be completed because the relevant
 258             data model content does not exist.  For example,
 259             a 'delete' operation was attempted on
 260             data that does not exist.";
 261        }
 262        enum operation-not-supported {
 263          description
 264            "Request could not be completed because the requested
 265             operation is not supported by this implementation.";
 266        }
 267        enum operation-failed {
 268          description
 269            "Request could not be completed because the requested
 270             operation failed for some reason not covered by
 271             any other error condition.";
 272        }
 273        enum partial-operation {
 274          description
 275            "This error-tag is obsolete, and SHOULD NOT be sent
 276             by servers conforming to this document.";
 277        }
 278        enum malformed-message {
 279          description
 280            "A message could not be handled because it failed to
 281             be parsed correctly.  For example, the message is not
 282             well-formed XML or it uses an invalid character set.";
 283        }
 284      }
 285      description "NETCONF Error Tag";
 286      reference "RFC 6241, Appendix A";
 287   }
 288
 289   typedef error-severity-type {
 290     type enumeration {
 291       enum error {
 292         description "Error severity";
 293       }
 294       enum warning {
 295         description "Warning severity";
 296       }
 297     }
 298     description "NETCONF Error Severity";
 299     reference "RFC 6241, Section 4.3";
 300   }
 301
 302   typedef edit-operation-type {
 303     type enumeration {
 304       enum merge {
 305         description
 306           "The configuration data identified by the
 307            element containing this attribute is merged
 308            with the configuration at the corresponding
 309            level in the configuration datastore identified
 310            by the target parameter.";
 311       }
 312       enum replace {
 313         description
 314           "The configuration data identified by the element
 315            containing this attribute replaces any related
 316            configuration in the configuration datastore
 317            identified by the target parameter.  If no such
 318            configuration data exists in the configuration
 319            datastore, it is created.  Unlike a
 320            <copy-config> operation, which replaces the
 321            entire target configuration, only the configuration
 322            actually present in the config parameter is affected.";
 323       }
 324       enum create {
 325         description
 326           "The configuration data identified by the element
 327            containing this attribute is added to the
 328            configuration if and only if the configuration
 329            data does not already exist in the configuration
 330            datastore.  If the configuration data exists, an
 331            <rpc-error> element is returned with an
 332            <error-tag> value of 'data-exists'.";
 333       }
 334       enum delete {
 335         description
 336           "The configuration data identified by the element
 337            containing this attribute is deleted from the
 338            configuration if and only if the configuration
 339            data currently exists in the configuration
 340            datastore.  If the configuration data does not
 341            exist, an <rpc-error> element is returned with
 342            an <error-tag> value of 'data-missing'.";
 343       }
 344       enum remove {
 345         description
 346           "The configuration data identified by the element
 347            containing this attribute is deleted from the
 348            configuration if the configuration
 349            data currently exists in the configuration
 350            datastore.  If the configuration data does not
 351            exist, the 'remove' operation is silently ignored
 352            by the server.";
 353       }
 354     }
 355     default "merge";
 356     description "NETCONF 'operation' attribute values";
 357     reference "RFC 6241, Section 7.2";
 358   }
 359
 360   // NETCONF Standard Protocol Operations
 361
 362   rpc get-config {
 363     description
 364       "Retrieve all or part of a specified configuration.";
 365
 366     reference "RFC 6241, Section 7.1";
 367
 368     input {
 369       container source {
 370         description
 371           "Particular configuration to retrieve.";
 372
 373         choice config-source {
 374           mandatory true;
 375           description
 376             "The configuration to retrieve.";
 377           leaf candidate {
 378             if-feature candidate;
 379             type empty;
 380             description
 381               "The candidate configuration is the config source.";
 382           }
 383           leaf running {
 384             type empty;
 385             description
 386               "The running configuration is the config source.";
 387           }
 388           leaf startup {
 389             if-feature startup;
 390             type empty;
 391             description
 392               "The startup configuration is the config source.
 393                This is optional-to-implement on the server because
 394                not all servers will support filtering for this
 395                datastore.";
 396           }
 397         }
 398       }
 399
 400       anyxml filter {
 401         description
 402           "Subtree or XPath filter to use.";
 403         nc:get-filter-element-attributes;
 404       }
 405     }
 406
 407     output {
 408       anyxml data {
 409         description
 410           "Copy of the source datastore subset that matched
 411            the filter criteria (if any).  An empty data container
 412            indicates that the request did not produce any results.";
 413       }
 414     }
 415   }
 416
 417   rpc edit-config {
 418     description
 419       "The <edit-config> operation loads all or part of a specified
 420        configuration to the specified target configuration.";
 421
 422     reference "RFC 6241, Section 7.2";
 423
 424     input {
 425       container target {
 426         description
 427           "Particular configuration to edit.";
 428
 429         choice config-target {
 430           mandatory true;
 431           description
 432             "The configuration target.";
 433
 434           leaf candidate {
 435             if-feature candidate;
 436             type empty;
 437             description
 438               "The candidate configuration is the config target.";
 439           }
 440           leaf running {
 441             if-feature writable-running;
 442             type empty;
 443             description
 444               "The running configuration is the config source.";
 445           }
 446         }
 447       }
 448
 449       leaf default-operation {
 450         type enumeration {
 451           enum merge {
 452             description
 453               "The default operation is merge.";
 454           }
 455           enum replace {
 456             description
 457               "The default operation is replace.";
 458           }
 459           enum none {
 460             description
 461               "There is no default operation.";
 462           }
 463         }
 464         default "merge";
 465         description
 466           "The default operation to use.";
 467       }
 468
 469       leaf test-option {
 470         if-feature validate;
 471         type enumeration {
 472           enum test-then-set {
 473             description
 474               "The server will test and then set if no errors.";
 475           }
 476           enum set {
 477             description
 478               "The server will set without a test first.";
 479           }
 480
 481           enum test-only {
 482             description
 483               "The server will only test and not set, even
 484                if there are no errors.";
 485           }
 486         }
 487         default "test-then-set";
 488         description
 489           "The test option to use.";
 490       }
 491
 492       leaf error-option {
 493         type enumeration {
 494           enum stop-on-error {
 495             description
 496               "The server will stop on errors.";
 497           }
 498           enum continue-on-error {
 499             description
 500               "The server may continue on errors.";
 501           }
 502           enum rollback-on-error {
 503             description
 504               "The server will roll back on errors.
 505                This value can only be used if the 'rollback-on-error'
 506                feature is supported.";
 507           }
 508         }
 509         default "stop-on-error";
 510         description
 511           "The error option to use.";
 512       }
 513
 514       choice edit-content {
 515         mandatory true;
 516         description
 517           "The content for the edit operation.";
 518
 519         anyxml config {
 520           description
 521             "Inline Config content.";
 522         }
 523         leaf url {
 524           if-feature url;
 525           type inet:uri;
 526           description
 527             "URL-based config content.";
 528         }
 529       }
 530     }
 531   }
 532
 533   rpc copy-config {
 534     description
 535       "Create or replace an entire configuration datastore with the
 536        contents of another complete configuration datastore.";
 537
 538     reference "RFC 6241, Section 7.3";
 539
 540     input {
 541       container target {
 542         description
 543           "Particular configuration to copy to.";
 544
 545         choice config-target {
 546           mandatory true;
 547           description
 548             "The configuration target of the copy operation.";
 549
 550           leaf candidate {
 551             if-feature candidate;
 552             type empty;
 553             description
 554               "The candidate configuration is the config target.";
 555           }
 556           leaf running {
 557             if-feature writable-running;
 558             type empty;
 559             description
 560               "The running configuration is the config target.
 561                This is optional-to-implement on the server.";
 562           }
 563           leaf startup {
 564             if-feature startup;
 565             type empty;
 566             description
 567               "The startup configuration is the config target.";
 568           }
 569           leaf url {
 570             if-feature url;
 571             type inet:uri;
 572             description
 573               "The URL-based configuration is the config target.";
 574           }
 575         }
 576       }
 577
 578       container source {
 579         description
 580           "Particular configuration to copy from.";
 581
 582         choice config-source {
 583           mandatory true;
 584           description
 585             "The configuration source for the copy operation.";
 586
 587           leaf candidate {
 588             if-feature candidate;
 589             type empty;
 590             description
 591               "The candidate configuration is the config source.";
 592           }
 593           leaf running {
 594             type empty;
 595             description
 596               "The running configuration is the config source.";
 597           }
 598           leaf startup {
 599             if-feature startup;
 600             type empty;
 601             description
 602               "The startup configuration is the config source.";
 603           }
 604           leaf url {
 605             if-feature url;
 606             type inet:uri;
 607             description
 608               "The URL-based configuration is the config source.";
 609           }
 610           anyxml config {
 611             description
 612               "Inline Config content: <config> element.  Represents
 613                an entire configuration datastore, not
 614                a subset of the running datastore.";
 615           }
 616         }
 617       }
 618     }
 619   }
 620
 621   rpc delete-config {
 622     description
 623       "Delete a configuration datastore.";
 624
 625     reference "RFC 6241, Section 7.4";
 626
 627     input {
 628       container target {
 629         description
 630           "Particular configuration to delete.";
 631
 632         choice config-target {
 633           mandatory true;
 634           description
 635             "The configuration target to delete.";
 636
 637           leaf startup {
 638             if-feature startup;
 639             type empty;
 640             description
 641               "The startup configuration is the config target.";
 642           }
 643           leaf url {
 644             if-feature url;
 645             type inet:uri;
 646             description
 647               "The URL-based configuration is the config target.";
 648           }
 649         }
 650       }
 651     }
 652   }
 653
 654   rpc lock {
 655     description
 656       "The lock operation allows the client to lock the configuration
 657        system of a device.";
 658
 659     reference "RFC 6241, Section 7.5";
 660
 661     input {
 662       container target {
 663         description
 664           "Particular configuration to lock.";
 665
 666         choice config-target {
 667           mandatory true;
 668           description
 669             "The configuration target to lock.";
 670
 671           leaf candidate {
 672             if-feature candidate;
 673             type empty;
 674             description
 675               "The candidate configuration is the config target.";
 676           }
 677           leaf running {
 678             type empty;
 679             description
 680               "The running configuration is the config target.";
 681           }
 682           leaf startup {
 683             if-feature startup;
 684             type empty;
 685             description
 686               "The startup configuration is the config target.";
 687           }
 688         }
 689       }
 690     }
 691   }
 692
 693   rpc unlock {
 694     description
 695       "The unlock operation is used to release a configuration lock,
 696        previously obtained with the 'lock' operation.";
 697
 698     reference "RFC 6241, Section 7.6";
 699
 700     input {
 701       container target {
 702         description
 703           "Particular configuration to unlock.";
 704
 705         choice config-target {
 706           mandatory true;
 707           description
 708             "The configuration target to unlock.";
 709
 710           leaf candidate {
 711             if-feature candidate;
 712             type empty;
 713             description
 714               "The candidate configuration is the config target.";
 715           }
 716           leaf running {
 717             type empty;
 718             description
 719               "The running configuration is the config target.";
 720           }
 721           leaf startup {
 722             if-feature startup;
 723             type empty;
 724             description
 725               "The startup configuration is the config target.";
 726           }
 727         }
 728       }
 729     }
 730   }
 731
 732   rpc get {
 733     description
 734       "Retrieve running configuration and device state information.";
 735
 736     reference "RFC 6241, Section 7.7";
 737
 738     input {
 739       anyxml filter {
 740         description
 741           "This parameter specifies the portion of the system
 742            configuration and state data to retrieve.";
 743         nc:get-filter-element-attributes;
 744       }
 745     }
 746
 747     output {
 748       anyxml data {
 749         description
 750           "Copy of the running datastore subset and/or state
 751            data that matched the filter criteria (if any).
 752            An empty data container indicates that the request did not
 753            produce any results.";
 754       }
 755     }
 756   }
 757
 758   rpc close-session {
 759     description
 760       "Request graceful termination of a NETCONF session.";
 761
 762     reference "RFC 6241, Section 7.8";
 763   }
 764
 765   rpc kill-session {
 766     description
 767       "Force the termination of a NETCONF session.";
 768
 769     reference "RFC 6241, Section 7.9";
 770
 771     input {
 772       leaf session-id {
 773         type session-id-type;
 774         mandatory true;
 775         description
 776           "Particular session to kill.";
 777       }
 778     }
 779   }
 780
 781   rpc commit {
 782     if-feature candidate;
 783
 784     description
 785       "Commit the candidate configuration as the device's new
 786        current configuration.";
 787
 788     reference "RFC 6241, Section 8.3.4.1";
 789
 790     input {
 791       leaf confirmed {
 792         if-feature confirmed-commit;
 793         type empty;
 794         description
 795           "Requests a confirmed commit.";
 796         reference "RFC 6241, Section 8.3.4.1";
 797       }
 798
 799       leaf confirm-timeout {
 800         if-feature confirmed-commit;
 801         type uint32 {
 802           range "1..max";
 803         }
 804         units "seconds";
 805         default "600";   // 10 minutes
 806         description
 807           "The timeout interval for a confirmed commit.";
 808         reference "RFC 6241, Section 8.3.4.1";
 809       }
 810
 811       leaf persist {
 812         if-feature confirmed-commit;
 813         type string;
 814         description
 815           "This parameter is used to make a confirmed commit
 816            persistent.  A persistent confirmed commit is not aborted
 817            if the NETCONF session terminates.  The only way to abort
 818            a persistent confirmed commit is to let the timer expire,
 819            or to use the <cancel-commit> operation.
 820
 821            The value of this parameter is a token that must be given
 822            in the 'persist-id' parameter of <commit> or
 823            <cancel-commit> operations in order to confirm or cancel
 824            the persistent confirmed commit.
 825
 826            The token should be a random string.";
 827         reference "RFC 6241, Section 8.3.4.1";
 828       }
 829
 830       leaf persist-id {
 831         if-feature confirmed-commit;
 832         type string;
 833         description
 834           "This parameter is given in order to commit a persistent
 835            confirmed commit.  The value must be equal to the value
 836            given in the 'persist' parameter to the <commit> operation.
 837            If it does not match, the operation fails with an
 838           'invalid-value' error.";
 839         reference "RFC 6241, Section 8.3.4.1";
 840       }
 841
 842     }
 843   }
 844
 845   rpc discard-changes {
 846     if-feature candidate;
 847
 848     description
 849       "Revert the candidate configuration to the current
 850        running configuration.";
 851     reference "RFC 6241, Section 8.3.4.2";
 852   }
 853
 854   rpc cancel-commit {
 855     if-feature confirmed-commit;
 856     description
 857       "This operation is used to cancel an ongoing confirmed commit.
 858        If the confirmed commit is persistent, the parameter
 859        'persist-id' must be given, and it must match the value of the
 860        'persist' parameter.";
 861     reference "RFC 6241, Section 8.4.4.1";
 862
 863     input {
 864       leaf persist-id {
 865         type string;
 866         description
 867           "This parameter is given in order to cancel a persistent
 868            confirmed commit.  The value must be equal to the value
 869            given in the 'persist' parameter to the <commit> operation.
 870            If it does not match, the operation fails with an
 871           'invalid-value' error.";
 872       }
 873     }
 874   }
 875
 876   rpc validate {
 877     if-feature validate;
 878
 879     description
 880       "Validates the contents of the specified configuration.";
 881
 882     reference "RFC 6241, Section 8.6.4.1";
 883
 884     input {
 885       container source {
 886         description
 887           "Particular configuration to validate.";
 888
 889         choice config-source {
 890           mandatory true;
 891           description
 892             "The configuration source to validate.";
 893
 894           leaf candidate {
 895             if-feature candidate;
 896             type empty;
 897             description
 898               "The candidate configuration is the config source.";
 899           }
 900           leaf running {
 901             type empty;
 902             description
 903               "The running configuration is the config source.";
 904           }
 905           leaf startup {
 906             if-feature startup;
 907             type empty;
 908             description
 909               "The startup configuration is the config source.";
 910           }
 911           leaf url {
 912             if-feature url;
 913             type inet:uri;
 914             description
 915               "The URL-based configuration is the config source.";
 916           }
 917           anyxml config {
 918             description
 919               "Inline Config content: <config> element.  Represents
 920                an entire configuration datastore, not
 921                a subset of the running datastore.";
 922           }
 923         }
 924       }
 925     }
 926   }
 927
 928 }