data-model/yang/published/o-ran/ru-fh/o-ran-software-management@2022-12-05.yang

   1 module o-ran-software-management {
   2   yang-version 1.1;
   3   namespace "urn:o-ran:software-management:1.0";
   4   prefix o-ran-swm;
   5
   6   import ietf-inet-types {
   7     prefix "inet";
   8     revision-date 2013-07-15;
   9   }
  10
  11   import ietf-hardware {
  12     prefix "hw";
  13   }
  14
  15   import o-ran-hardware {
  16     prefix "o-ran-hw";
  17   }
  18
  19   import o-ran-file-management {
  20     prefix "o-ran-file-mgmt";
  21   }
  22
  23   import o-ran-wg4-features {
  24     prefix "or-feat";
  25   }
  26
  27   organization "O-RAN Alliance";
  28
  29   contact
  30     "www.o-ran.org";
  31
  32   description
  33     "This module defines operations and configuration for the management of software packages.
  34     This module is derived out of opencpe-firmware-mgmt@2014-02-06.yang
  35
  36     Copyright 2021 the O-RAN Alliance.
  37
  38     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS'
  39     AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  41     ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  42     LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  43     CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  44     SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  45     INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  46     CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  47     ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  48     POSSIBILITY OF SUCH DAMAGE.
  49
  50     Redistribution and use in source and binary forms, with or without
  51     modification, are permitted provided that the following conditions are met:
  52
  53     * Redistributions of source code must retain the above copyright notice,
  54     this list of conditions and the above disclaimer.
  55     * Redistributions in binary form must reproduce the above copyright notice,
  56     this list of conditions and the above disclaimer in the documentation
  57     and/or other materials provided with the distribution.
  58     * Neither the Members of the O-RAN Alliance nor the names of its
  59     contributors may be used to endorse or promote products derived from
  60     this software without specific prior written permission.";
  61
  62   revision "2022-12-05" {
  63     description
  64       "version 11.0.0
  65
  66       1) SW Install timeout
  67       2) check integrity directly after download";
  68
  69     reference "ORAN-WG4.M.0-v11.00";
  70   }
  71
  72   revision "2022-08-15" {
  73     description
  74       "version 9.1.0
  75
  76       1) clarified description statements
  77       2) style guide corrections
  78       3) changed import prefix for o-ran-file-management";
  79
  80     reference "ORAN-WG4.M.0-v09.00";
  81   }
  82
  83   revision "2022-04-18" {
  84     description
  85       "version 9.0.0
  86
  87       1) aded new parameter build-content-download";
  88
  89     reference "ORAN-WG4.M.0-v09.00";
  90   }
  91
  92   revision "2021-12-01" {
  93     description
  94       "version 8.0.0
  95
  96       1) typographical corrections in descriptions
  97       2) new option to use IANA private enterprise number as vendor-code";
  98
  99     reference "ORAN-WG4.M.0-v08.00";
 100   }
 101   revision "2021-07-26" {
 102     description
 103       "version 7.0.0
 104
 105       1) added FTPES support";
 106
 107     reference "ORAN-WG4.M.0-v07.00";
 108   }
 109
 110   revision "2021-03-22" {
 111     description
 112       "version 1.1.0
 113
 114       1) typographical corrections in descriptions.";
 115
 116     reference "ORAN-WG4.M.0-v01.00";
 117   }
 118
 119   revision "2019-07-03" {
 120     description
 121       "version 1.0.2
 122
 123       1) backward compatible changes to correct sFTP Server Authentication .
 124       2) simplifying file management and authentication to reuse from o-ran-file-management module
 125       3) minor fixes according to lack of descriptions
 126       4) removal of not used grouping
 127       5) backward compatible changes to introduce groupings.";
 128
 129     reference "ORAN-WG4.M.0-v01.00";
 130   }
 131
 132   revision "2019-02-04" {
 133     description
 134       "version 1.0.0
 135
 136       1) imported model from xRAN
 137       2) changed namespace and reference from xran to o-ran";
 138
 139     reference "ORAN-WG4.M.0-v01.00";
 140   }
 141
 142
 143
 144   // groupings
 145
 146   grouping slot-group {
 147     description
 148       "Contains information about each software slot and its content.";
 149     list software-slot {
 150       key name;
 151       min-elements 2;
 152
 153       description
 154         "Information about available software-slots, their status, state and content.";
 155
 156       leaf name {
 157         type string;
 158
 159         description
 160           "Name of the software slot. This shall be unique to identify the software-slot.";
 161       }
 162
 163       leaf status {
 164         type enumeration {
 165           enum VALID {
 166             description
 167               "Slot contains software considered as proven valid";
 168           }
 169           enum INVALID {
 170             description
 171               "Software in the slot is considered by O-RU as invalid (e.g. wrong CRC).
 172               O-RU prohibits activation of slot with such status.";
 173           }
 174           enum EMPTY {
 175             description
 176               "Slot does not contain software package. O-RU prohibits activation of slot
 177               with such status.";
 178           }
 179         }
 180         config false;
 181         mandatory true;
 182
 183         description "Indicates the status of the software slot";
 184       }
 185
 186       leaf active {
 187           type boolean;
 188       must "../status = 'VALID'";
 189         config false;
 190           description
 191             "informs if software stored in particular slot is activated at the moment";
 192       }
 193
 194       leaf running {
 195           type boolean;
 196       must "../status = 'VALID'";
 197         config false;
 198           description
 199             "Informs if software stored in particular slot is used at the moment";
 200       }
 201
 202       leaf access {
 203         type enumeration {
 204           enum READ_ONLY {
 205             description
 206               "slot intended only for factory software,
 207               activation of such software slot means getting back to factory defaults";
 208           }
 209           enum READ_WRITE {
 210             description
 211               "slot used for updating software";
 212           }
 213         }
 214         default READ_WRITE;
 215         config false;
 216
 217         description
 218           "Indicates the writeability of the slot.
 219           A Read-Only software slot is one which has a factory installed software-slot";
 220       }
 221
 222       leaf product-code {
 223         type leafref {
 224         path "/hw:hardware/hw:component/o-ran-hw:product-code";
 225         }
 226         config false;
 227
 228         description "product code provided by the vendor, specific to the product. This is derived from manifest file.";
 229       }
 230
 231       leaf vendor-code {
 232         type string {
 233           length 1..5;
 234           pattern '(.{1,2})|(\d{1,5})';
 235         }
 236         config false;
 237
 238         description
 239           "Unique code of the vendor. This is derived from manifest file.
 240
 241           This may be a 1 or two upper case characters or a 1-5 digit IANA Private Enterprise Number.";
 242       }
 243
 244       leaf build-id {
 245         type string;
 246         config false;
 247
 248         description
 249           "Identity associated with the software. This is derived from manifest file.";
 250       }
 251
 252       leaf build-name {
 253         type string;
 254         config false;
 255
 256         description
 257           "Name of the build. This is derived from manifest file.";
 258       }
 259
 260       leaf build-version {
 261         type string;
 262         description "The vendor-specific version string of the software build.";
 263       }
 264
 265       list files {
 266         key "name";
 267         config false;
 268
 269         description "List of all the files present in the software slot.";
 270
 271         leaf name {
 272           type string;
 273
 274           description
 275             "Name of the file installed in the slot.";
 276         }
 277
 278         leaf version {
 279           type string;
 280
 281           description
 282             "Version of the file installed in the slot";
 283         }
 284         leaf local-path {
 285           type string;
 286           mandatory true;
 287
 288           description
 289             "Complete path of the file stored locally";
 290         }
 291
 292         leaf integrity {
 293           type enumeration {
 294             enum OK {
 295               description "OK - indicates that file integrity is correct";
 296             }
 297             enum NOK {
 298               description "NOK - indicates corrupted file";
 299             }
 300           }
 301           config false;
 302
 303           description
 304             "Result of the file integrity check (checksum calculation) during installation.";
 305         }
 306       }
 307     }
 308   }
 309
 310   grouping download-input {
 311     description
 312       "Grouping for SW download RPC input";
 313     leaf remote-file-path {
 314       type inet:uri;
 315       mandatory true;
 316       description
 317         "URI of the software image including username.
 318         The following format is possible:
 319         When file download is via sftp, the format shall be of the form
 320         sftp://<username>@<host>[:<port>]/path
 321         When file transfer is via FTPES, the format shall be of the form
 322         ftpes://<username>@<host>[:port]/path
 323
 324         Note, ftpes is not an IANA registered URI scheme, but used here to signal
 325         that a file transfer should be performed over FTPES.";
 326     }
 327
 328
 329     uses o-ran-file-mgmt:credential-information;
 330   }
 331
 332   grouping download-output {
 333     description
 334       "Grouping for SW download RPC output";
 335     leaf status {
 336       type enumeration {
 337         enum STARTED {
 338           description
 339             "Operation has been started without error.";
 340         }
 341         enum FAILED {
 342           description
 343             "Operation cannot be started because of error, more detailed information can be found in error-message.";
 344         }
 345       }
 346       mandatory true;
 347
 348       description
 349         "Status of the software file download";
 350     }
 351     leaf error-message {
 352       when "../status = 'FAILED'";
 353       type string;
 354
 355       description
 356         "Detailed error Message when the status is FAILED.";
 357     }
 358
 359     leaf notification-timeout {
 360       type int32 {range "1..max";}
 361       units seconds;
 362       default 30;
 363
 364       description
 365         "Notification timeout is the time NETCONF client shall
 366         wait for a 'download-event' notification from O-RU. If there is no
 367         'download-event' notification received within notification-timeout,
 368         NETCONF client shall assume the download timeout/failure, and follow necessary steps.";
 369     }
 370   }
 371
 372   grouping install-input {
 373     description
 374       "Grouping for SW installation RPC input";
 375     leaf slot-name {
 376       type leafref {
 377         path "/software-inventory/software-slot/name";
 378         }
 379       must "/software-inventory/software-slot[name = current()][active = 'false' and running = 'false']" {
 380         error-message "software-install may be requested only against active::false and running::false slot!";
 381       }
 382       mandatory true;
 383
 384       description
 385         "Software slot to which the software shall be installed.";
 386     }
 387
 388     leaf-list file-names {
 389       type string;
 390
 391       description
 392         "Names of the files within software package to be installed";
 393     }
 394   }
 395
 396   grouping install-output {
 397     description
 398       "Grouping for SW installation RPC output";
 399     leaf status {
 400       type enumeration {
 401         enum STARTED {
 402           description
 403             "Operation has been started without error.";
 404         }
 405         enum FAILED {
 406           description
 407             "Operation cannot be started because of error, more detailed information can be found in error-message.";
 408         }
 409       }
 410       mandatory true;
 411
 412       description
 413         "Status of the software package installation to software slot.";
 414     }
 415     leaf error-message {
 416       when "../status = 'FAILED'";
 417       type string;
 418
 419       description
 420         "Detailed error Message when the status is FAILED.";
 421     }
 422
 423     leaf sw-install-timeout {
 424       type int32 {range "1..max";}
 425       units seconds;
 426
 427       description
 428         "Optional timeout indicated by O-RU after which time
 429         an 'install-event' notification will be sent indicating
 430         the installation procedure has timed out.";
 431     }
 432   }
 433
 434   grouping activate-input {
 435     description
 436       "Grouping for SW activation RPC input";
 437     leaf slot-name {
 438       type leafref {
 439         path "/software-inventory/software-slot/name";
 440       }
 441       must "/software-inventory/software-slot[name = current()][status = 'VALID']" {
 442         error-message "software activation may be requested only on VALID slot!";
 443       }
 444       mandatory true;
 445
 446       description
 447         "Slot name on which software has to be activated.";
 448     }
 449   }
 450
 451   grouping activate-output {
 452     description
 453       "Grouping for SW activation RPC output";
 454     leaf status {
 455       type enumeration {
 456         enum STARTED {
 457           description
 458             "Operation has been started without error.";
 459         }
 460         enum FAILED {
 461           description
 462             "Operation cannot be started because of error, more detailed information can be found in error-message.";
 463         }
 464       }
 465       mandatory true;
 466
 467       description
 468         "Status of the software files activation";
 469     }
 470     leaf error-message {
 471       when "../status = 'FAILED'";
 472       type string;
 473
 474       description
 475         "Detailed error Message when the status is FAILED.";
 476     }
 477
 478     leaf notification-timeout {
 479       type int32 {range "1..max";}
 480       units seconds;
 481       default 30;
 482
 483       description
 484         "Timeout on client waiting for the activate event";
 485     }
 486   }
 487
 488   grouping download-notification {
 489     description
 490       "Grouping for notification event structure for download completion";
 491     leaf file-name {
 492       type string;
 493       mandatory true;
 494
 495       description
 496         "File name of transferred software file.";
 497     }
 498
 499     leaf status {
 500       type enumeration {
 501         enum COMPLETED {
 502           description
 503             "Operation completed successfully";
 504         }
 505         enum AUTHENTICATION_ERROR {
 506           description "Source available, wrong credentials";
 507         }
 508         enum PROTOCOL_ERROR {
 509           description "SFTP or FTPES errors";
 510         }
 511         enum FILE_NOT_FOUND {
 512           description "Source not available.";
 513         }
 514         enum APPLICATION_ERROR {
 515           description "Application related errors";
 516         }
 517         enum TIMEOUT {
 518           description "Timeout waiting for download";
 519         }
 520         enum INTEGRITY_ERROR {
 521           description "File is corrupted";
 522         }
 523       }
 524
 525       description
 526         "Status of finished operation execution";
 527     }
 528     leaf error-message {
 529       when "../status != 'COMPLETED'";
 530       type string;
 531
 532       description
 533         "Detailed description of faulty situation";
 534     }
 535   }
 536
 537   grouping install-notification {
 538     description
 539       "Grouping for notification event structure for installation completion";
 540     leaf slot-name {
 541       type leafref {
 542         path "/software-inventory/software-slot/name";
 543       }
 544
 545       description
 546         "Name of the slot to which software was installed.";
 547     }
 548     leaf status {
 549       type enumeration {
 550         enum COMPLETED {
 551           description
 552             "Operation completed successfully";
 553         }
 554         enum FILE_ERROR {
 555           description "Operation on the file resulted in in error, disk failure, not enough disk space,
 556                       incompatible file format";
 557         }
 558         enum INTEGRITY_ERROR {
 559           description "File is corrupted";
 560         }
 561         enum APPLICATION_ERROR {
 562           description "Operation failed due to internal reason";
 563         }
 564         enum TIMEOUT {
 565           description "Install operation timed out";
 566         }
 567       }
 568
 569       description
 570         "Status of finished operation execution";
 571     }
 572     leaf error-message {
 573       when "../status != 'COMPLETED'";
 574       type string;
 575
 576       description
 577         "Detailed description of faulty situation";
 578     }
 579   }
 580
 581   grouping activation-notification {
 582     description
 583       "Grouping for notification event structure for activation completion";
 584     leaf slot-name {
 585       type leafref {
 586         path "/software-inventory/software-slot/name";
 587       }
 588
 589       description
 590         "Name of the slot which was activated";
 591     }
 592
 593     leaf status {
 594       type enumeration {
 595         enum COMPLETED {
 596           description
 597             "Operation completed successfully";
 598         }
 599         enum APPLICATION_ERROR {
 600           description
 601             "Operation finished with error, more details can by found in error-message";
 602         }
 603       }
 604
 605       description
 606         "Status of finished operation execution";
 607     }
 608     leaf return-code {
 609       type uint8;
 610
 611       description
 612         "Status code return when the software is tried to activate";
 613     }
 614     leaf error-message {
 615       when "../status != 'COMPLETED'";
 616       type string;
 617
 618       description
 619         "Detailed description of faulty situation";
 620     }
 621   }
 622
 623   // top-level container
 624
 625   container software-inventory {
 626     config false;
 627     description
 628       "Contains information about each software slot and its content as well as information related to
 629       software processing.";
 630
 631     uses slot-group;
 632
 633     leaf build-content-download {
 634       type empty;
 635       description
 636         "An optional leaf used to indicate that the O-RU requires separate download procedures to be
 637         re-used for downloading individual files in a software build, instead of a single archived package.";
 638     }
 639
 640     leaf integrity-check-at-download-enabled {
 641       if-feature or-feat:INTEGRITY-CHECK-AT-SW-DOWNLOAD;
 642       type empty;
 643       description "Presence of this node enables O-RU to perform integrity check at file download.";
 644     }
 645
 646   }
 647     // RPC statements
 648
 649   rpc software-download {
 650     description
 651       "RPC needed to perform software download operation.";
 652
 653     input {
 654       uses download-input;
 655     }
 656     output {
 657       uses download-output;
 658     }
 659   }
 660
 661   rpc software-install {
 662     description
 663       "Install a previously downloaded software.";
 664
 665     input {
 666       uses install-input;
 667     }
 668     output {
 669       uses install-output;
 670     }
 671   }
 672
 673   rpc software-activate {
 674     description
 675       "Activate a previously installed software.";
 676     input {
 677       uses activate-input;
 678     }
 679     output {
 680       uses activate-output;
 681     }
 682   }
 683
 684     // notification definitions
 685   notification download-event {
 686     description "Notification event structure for download completion";
 687     uses download-notification;
 688
 689   }
 690
 691   notification install-event {
 692     description "Notification event structure for installation completion";
 693     uses install-notification;
 694   }
 695
 696   notification activation-event {
 697     description "Notification event structure for activation completion";
 698     uses activation-notification;
 699   }
 700 }