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