ntsimulator/yang/x-ran/xran-software-management.yang

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