netconf-server/schemas/common/o-ran-software-management.yang

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