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