1 module org-openroadm-manifest-file {
2 namespace "http://org/openroadm/manifest-file";
3 prefix org-openroadm-manifest-file;
10 "YANG definitions of sw-manifest-file
12 Copyright of the Members of the Open ROADM MSA Agreement dated (c) 2017,
13 AT&T Intellectual Property. All other rights reserved.
15 Redistribution and use in source and binary forms, with or without modification,
16 are permitted provided that the following conditions are met:
18 * Redistributions of source code must retain the above copyright notice, this
19 list of conditions and the following disclaimer.
20 * Redistributions in binary form must reproduce the above copyright notice,
21 this list of conditions and the following disclaimer in the documentation and/or
22 other materials provided with the distribution.
23 * Neither the Members of the Open ROADM MSA Agreement nor the names of its
24 contributors may be used to endorse or promote products derived from this software
25 without specific prior written permission.
27 THIS SOFTWARE IS PROVIDED BY THE MEMBERS OF THE OPEN ROADM MSA AGREEMENT ''AS IS''
28 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
29 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30 IN NO EVENT THE MEMBERS OF THE OPEN ROADM MSA AGREEMENT BE LIABLE FOR ANY DIRECT,
31 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
33 OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
34 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36 POSSIBILITY OF SUCH DAMAGE.
38 Also contains code components extracted from IETF netconf. These code components
39 are copyrighted and licensed as follows:
41 Copyright (c) 2016 IETF Trust and the persons identified as the document authors.
44 This document is subject to BCP 78 and the IETF Trust’s Legal Provisions Relating
45 to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of
46 publication of this document. Please review these documents carefully, as they
47 describe your rights and restrictions with respect to this document. Code Components
48 extracted from this document must include Simplified BSD License text as described in
49 Section 4.e of the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.";
59 reference "This module serves as the manifest file reference.";
62 identity manifest-commands {
64 "base identity for defining manifest-commands.";
67 identity download-file {
68 base manifest-commands;
70 "download-file (transfer from OWB-C to Device)";
73 identity upload-file {
74 base manifest-commands;
76 "upload-file (transfer from Device to OWB-C)";
79 identity delete-file {
80 base manifest-commands;
82 "delete-file from device";
85 identity sw-manifest-commands {
86 base manifest-commands;
88 "base identity for defining manifest-commands specific to sw-manifest.";
92 base sw-manifest-commands;
94 "sw-stage sw-manifest-command";
97 identity sw-activate {
98 base sw-manifest-commands;
100 "sw-activate sw-manifest-command";
103 identity db-backup-manifest-commands {
104 base manifest-commands;
106 "base identity for defining manifest-commands specific to db-backup-manifest.";
110 base db-backup-manifest-commands;
112 "db-backup db-backup-manifest-command";
115 identity db-restore-manifest-commands {
116 base manifest-commands;
118 "base identity for defining manifest-commands specific to db-restore-manifest.";
121 identity db-restore {
122 base db-restore-manifest-commands;
124 "db-restore db-restore-manifest-command";
127 identity db-activate {
128 base db-restore-manifest-commands;
130 "db-activate db-restore-manifest-command";
133 grouping base-manifest {
135 "base set of variables in all manifest files";
140 "This field should match the /org-openroadm-device/info/vendor.
141 It is assumed that the vendor value does not change during the
142 processing of the manifest file.
144 The controller agent would use the vendor and model to find the
145 manifest for an Open ROADM NE. The controller agent would also
146 use the vendor and model to validate that this is a valid manifest
147 for the Open ROADM NE.
154 "This field should match the /org-openroadm-device/info/model.
155 It is assumed that the model value does not change during the
156 processing of the manifest file.
158 The controller agent would use the vendor and model to find the
159 manifest for an Open ROADM NE. The controller agent would also
160 use the vendor and model to validate that this is a valid manifest
161 for the Open ROADM NE.
167 "This field should match the
168 /org-openroadm-device/info/softwareVersion.
169 This is the value in the info tree AFTER an upgrade.
172 leaf global-async-timeout {
176 "global-async-timeout - time in seconds to wait for command processing to
179 Upon timeout, the controller may either:
182 - poll the device to determine success/failure of the operation
184 This global-async-timeout applies to any asynchronous command.
187 leaf global-sync-timeout {
190 "global-sync-timeout - time in seconds to wait for the rpc response for
191 synchronous commands.
193 This global-sync-timeout applies to any synchronous command.
195 Upon timeout, the controller may either:
198 - poll the device to determine success/failure of the operation
200 No default is modeled; if not provided, defaults to the global
201 timeout supported by the controller for rpc responses.
206 grouping timeout-command {
208 "timeout-command is to be used by any manifest command supporting a timeout";
212 "See command for additional details.
214 - overrides the global-async-timeout;
215 - defaults to the global-async-timeout if not provided.
217 - overrides the global-sync-timeout;
218 - defaults to the global-sync-timeout if not provided.
223 grouping is-async-command {
225 "is-async-command is to be supported by all manifest commands even if only
226 supported as sync or async. In such cases, a must statement should be
227 included to limit support to either sync or async.";
232 "command can be supported as either an async or sync command by a vendor.
233 When supported as a sync command, the OWB-C will determine the success/failure
234 of the command based on the RPC response instead of waiting for transient
235 notifications from the device.";
239 grouping transfer-command {
241 "transfer-command defines the common set of variables used by download-file
243 leaf remote-filename {
247 "See command for detailed description.";
249 leaf local-file-path {
253 "See command for detailed description.";
255 uses timeout-command;
256 uses is-async-command;
259 grouping file-command {
261 "file-command is used by all manifest files needing a filename";
265 "filename is mandatory for delete-file; optional otherwise.
266 See command for detailed description.";
270 grouping command-reboot {
272 "command-reboot is used by manifest commands which result in a
278 "See command for detailed description.";
282 grouping download-file-command {
285 container download-file {
286 when "../command = 'download-file'";
288 "Transfer a file from the SFTP server to the device.
289 format: download-file remote-filename local-file-path [timeout]
291 remote-filename is the filename of the file to transfer on the SFTP
292 server. The filename can include a relative path that represents the
293 subdirectory structure of the vendor's software directory. This file
294 (and optional path) must exist in the software release directory on
297 local-file-path is the local path and filename to transfer the file on
300 timeout - see timeout-command grouping for basic details;
302 - Receipt of an in-progress (version 2)
303 transfer-notification resets the timeout.
305 Maps to the transfer rpc with
307 local-file-path = local-file-path
309 sftp://user:password@host[:port]/path/remote-filename
311 The remote-file-path attribute on the transfer command would be
312 constructed by the software download agent by appending the sftp URL
313 (which includes username, password, host, port, and path to the
314 software release directory) with the remote_filename.
316 In the context of the transfer, remote is the SFTP server (e.g., located
317 on the software download agent) and local is on the Open ROADM device.
319 Expected notifications: transfer-notification
321 uses transfer-command;
325 grouping upload-file-command {
327 "upload-file-command";
328 container upload-file {
329 when "../command = 'upload-file'";
331 "Transfer a file from the device to the SFTP server.
332 format: upload-file remote-filename local-file-path [timeout]
334 remote-filename is the filename of the file to receive the upload
335 on the SFTP server. The filename can include a relative path that
336 represents the subdirectory structure of the vendor's software
339 local-file-path is the local path and filename of the file on
340 the device to be uploaded to the SFTP server. This file must exist on
343 timeout - see timeout-command grouping for basic details;
345 - Receipt of an in-progress (version 2)
346 transfer-notification resets the timeout.
348 Maps to the transfer rpc with
350 local-file-path = local-file-path
352 sftp://user:password@host[:port]/path/remote-filename
354 The remote-file-path attribute on the transfer command would be
355 constructed by the software download agent by appending the sftp URL
356 (which includes username, password, host, port, and path to the
357 software release directory) with the remote_filename.
359 In the context of the transfer, remote is the SFTP server (e.g., located
360 on the software download agent) and local is on the Open ROADM device.
362 Expected notifications: transfer-notification
364 uses transfer-command;
368 grouping delete-file-command {
370 "delete-file-command";
371 container delete-file {
372 when "../command = 'delete-file'";
373 must "is-async != 'false'" {
374 error-message "delete-file is only supported as sync command";
377 "Delete a file from the device's file system.
378 format: delete-file filename [timeout]
380 filename is the filename to be deleted from the device. The filename
381 may include path information.
383 timeout - overrides the global-sync-timeout; defaults to the
384 global-sync-timeout if not provided.
386 Maps to the delete-file rpc:
394 uses timeout-command;
395 uses is-async-command;
399 grouping sw-stage-command {
403 when "../command = 'sw-stage'";
405 "Stage a file in the device. The details of what a device does during
406 the staging operation is vendor specific. However, the vendor may
407 initiate additional file transfers from the SFTP server during the
408 staging operation. It is expected that the files will only be
409 transferred from the software release directory.
411 format: sw-stage [filename] [timeout]
413 filename is the filename of the file to stage. If filename is not
414 provided, the software download application will send the sw-stage
415 command without a filename.
417 timeout - overrides the global-async-timeout; defaults to the
418 global-async-timeout if not provided.
421 Maps to the sw-stage rpc:
424 Expected notifications: sw-stage-notification
427 uses timeout-command;
428 uses is-async-command;
432 grouping sw-activate-command {
434 "sw-activate-command";
435 container sw-activate {
436 when "../command = 'sw-activate'";
437 must "is-async != 'true'" {
438 error-message "sw-activate is only supported as async command";
441 "Activate a software load in a device. The details of what a device does
442 during the activation phase is vendor specific. The device initiates
443 an automatic reboot as part of the activation.
445 format: sw-activate version [validation-timer] [timeout] auto-reboot
447 version: The version of software that is being activated. (The current
448 YANG model indicates that version is optional; however, version should
449 be a mandatory attribute of the sw-activate command in the manifest
452 validation-timer: Validation timer setting for the software activation.
453 Format is expected to be in the form HH-MM-SS per the YANG model. The
454 software download application expects this format in order to treat
455 00-00-00 and no validation timer as the same use case.
457 timeout - overrides the global-async-timeout; defaults to the
458 global-async-timeout if not provided. This timer begins as soon as the
459 sw-activate processing begins. timeout must be greater than the
462 auto-reboot: time (in seconds) to wait to for the device to reboot.
463 This is the device restart time (e.g. the length of time from device
464 comm loss until the device is ready for login). This timer begins when
465 the controller detects the comm-loss from the device. If login is not
466 successful when this timer expires, the sw-activate is failed.
468 NOTE: if controller swdl application is not doing the login directly,
469 the controller may need to augment the auto-reboot timer to account for
472 Maps to the sw-activate rpc:
473 sw-activate version [validationTimer]
475 Expected notifications: sw-activate-notification
476 When no validation timer (or validation-timer = 00-00-00), two
477 notifications will be expected: one for activate, the other for
478 commit. Otherwise, only the activate notification is expected.
480 NOTE: the sw-activate-notifications (for activate) may be received
481 before or after the reboot; it is assumed the sw-activate-notification
482 (for commit) always occurs after the reboot. Any polling due to missed
483 sw-activate-notifications (activate and/or commit) should not be done
484 until after the reboot login; processing of sw-activate does not
485 complete until after receipt of the notifications and the reboot login.
491 "Although version is optional in the sw-activate rpc, it is
492 mandatory in the manifest file command.";
494 leaf validation-timer {
499 uses timeout-command;
501 uses is-async-command;
505 grouping db-backup-command {
508 container db-backup {
509 when "../command = 'db-backup'";
511 "Perform a database backup on the device.
513 format: db-backup [filename] [timeout]
515 filename is the filename of the backup file to be generated on the
516 device. If filename is not provided, the database backup application
517 will send the db-backup command without a filename. It's possible the
518 filename will not be statically provided in the manifest file, but
519 provided by the database backup application.
521 timeout - see timeout-command grouping for basic details;
523 Maps to the db-backup rpc:
526 Expected notifications: db-backup-notification
529 uses timeout-command;
530 uses is-async-command;
534 grouping db-restore-command {
536 "db-restore-command";
537 container db-restore {
538 when "../command = 'db-restore'";
540 "Perform a database restore on the device.
542 format: db-restore [filename] [node-id-check] [timeout]
544 filename is the filename of the file to be restored on the
545 device. If filename is not provided, the database restore application
546 will send the db-restore command without a filename. It's possible the
547 filename will not be statically provided in the manifest file, but
548 provided by the database restore application.
550 node-id-check is a boolean indicating whether sysNameCheck is required.
552 timeout - see timeout-command grouping for basic details;
554 Maps to the db-restore rpc:
555 db-restore [filename] [nodeIDCheck]
557 Expected notifications: db-restore-notification
564 "Defined as an string here so that manifest file can parameterize
565 the value for user input. __NODE-ID-CHECK is used for that purpose. Other valid
566 values are true or false. Maps to a boolean value in the rpc invocation.";
568 uses timeout-command;
569 uses is-async-command;
573 grouping db-activate-command {
575 "db-activate-command";
576 container db-activate {
577 when "../command = 'db-activate'";
578 must "is-async != 'true'" {
579 error-message "db-activate is only supported as async command";
582 "Activate a database on a device. The details of what a device does
583 during the activation phase is vendor specific. The device initiates
584 an automatic reboot as part of the activation.
586 format: db-activate [rollback-timer] [timeout] auto-reboot
588 rollback-timer: Rollback timer setting for the database activation.
589 Format is expected to be in the form HH-MM-SS per the YANG model. The
590 database activation application expects this format in order to treat
591 00-00-00 and no validation timer as the same use case.
593 timeout - overrides the global-async-timeout; defaults to the
594 global-async-timeout if not provided. This timer begins as soon as the
595 db-activate processing begins. timeout must be greater than the
598 auto-reboot: time (in seconds) to wait to for the device to reboot.
599 This is the device restart time (e.g. the length of time from device
600 comm loss until the device is ready for login). This timer begins when
601 the controller detects the comm-loss from the device. If login is not
602 successful when this timer expires, the db-activate is failed.
604 NOTE: if controller database application is not doing the login
605 directly, the controller may need to augment the auto-reboot timer to
606 account for the login time.
608 Maps to the db-activate rpc:
609 db-activate [rollBackTimer]
611 Expected notifications: db-activate-notification
612 When no rollback timer (or rollback-timer = 00-00-00), two
613 notifications will be expected: one for activate, the other for
614 commit. Otherwise, only the activate notification is expected.
616 NOTE: the db-activate-notifications (for activate) may be received
617 before or after the reboot; it is assumed the db-activate-notification
618 (for commit) always occurs after the reboot. Any polling due to missed
619 db-activate-notifications (activate and/or commit) should not be done
620 until after the reboot login; processing of db-activate does not
621 complete until after receipt of the notifications and the reboot login.
623 leaf rollback-timer {
628 uses timeout-command;
630 uses is-async-command;
634 container sw-manifest {
635 presence "The sw-manifest instructions for swdl operations have been defined.";
637 "The manifest file provides instructions to a software download
638 application to download and install a new software load into a vendor’s
641 Software download files
642 All vendor files for a software release should be stored in a
643 separate directory. A unique directory would be used for each vendor,
644 model and software release combination. This directory and all files in
645 that directory will be accessible by the SFTP server.
646 The software directory can be flat or hierarchical with
647 subdirectories. The manifest file should be in the root directory of the
649 A software directory must contain files for one and only one
653 Each software release directory shall contain a manifest file for
654 that release. The filename for the manifest file shall be sw-manifest.json.
657 refine "sw-version" {
661 list instruction-set {
664 "The instruction set for a list of sw-versions that can be upgraded to
665 the sw-version specified at the top of the manifest file.";
669 "The index for this instruction set.";
671 leaf-list from-sw-version {
674 "The optional list of sw-versions that can be upgraded to the
675 sw-version specified at the top of the sw-manifest file.
677 If not specified, this instruction set is used to upgrade from
678 any sw-version to the sw-version specified at the top of the
681 If multiple instruction sets are provided, from-sw-version
682 should always be defined.";
684 leaf is-commit-sw-activate-async {
688 "Is cancel-validation-timer (accept = true) supported as an
689 async or sync command on the device? If supported as sync, the rpc response
690 is used to determine success/failure instead of waiting for transient notifications
692 NOTE: cancel-validation-timer (accept = false) requires a reboot so is
693 always considered async";
695 leaf cancel-validation-timer-async-timeout {
698 "timeout value to use for cancel-validation-timer when supported as
699 an async command. If not specified, the global-async-timeout is used.";
701 leaf cancel-validation-timer-sync-timeout {
704 "timeout value to use for cancel-validation-timer (accept = true) when
705 supported as a sync command. If not specified, the global-sync-timeout
708 container sw-manifest-commands {
710 "The ordered list of commands to be processed. Since some yang
711 implementations do not support ordered-by user, the list is also
712 indexed by command-order. The commands should be processed
713 in the order of command-order.
715 Processing moves to the next command when:
716 1. command is synchronous and rpc returns a successful result.
717 2. command is asynchronous, the rpc returns a successful result,
719 2.1 expected successful notification(s) have been received; or
722 Processing of the manifest file is aborted when:
723 1. command is synchronous and rpc returns a failed result.
724 2. command is asynchronous, and:
725 2.1 the rpc returns a failed result; or
726 2.2 a failed notification is received; or
729 NOTE: behavior for timeouts (synchronous or asynchronous) may depend upon
730 controller implementation per command. It may be considered either:
731 - as a successful result
733 - as a success or failure based on polling the device
735 list sw-manifest-command {
739 "The list of commands to be processed.";
743 "The order in which commands should be processed.";
747 base sw-manifest-commands;
751 "The command to be processed.";
753 uses download-file-command;
754 uses delete-file-command;
755 uses sw-stage-command;
756 uses sw-activate-command;
761 container db-backup-manifest {
762 presence "The db-backup-manifest template for db-backup operations has been defined.";
764 "The manifest file provides instructions to a database operations
765 application to backup the database on a device.
767 Since the files used for these operations are likely user selected,
768 these manifest files are more likely used by the controller as a
769 template to control the overall flow of a backup operation and provide
770 a means of providing customized timeout values.
772 The following strings will be recognized as parameters to be replaced
773 by the user selected values: __LOCAL-FILE-PATH, __REMOTE-FILENAME.
776 Each vendor/model combination can have a separate manifest file
777 defined for backup. These shall be named db-backup-manifest.json.
780 container db-backup-manifest-commands {
782 "The ordered list of commands to be processed. Since some yang
783 implementations do not support ordered-by user, the list is also
784 indexed by command-order. The commands should be processed
785 in the order of command-order.
787 Processing moves to the next command when:
788 1. command is synchronous and rpc returns a successful result.
789 2. command is asynchronous, the rpc returns a successful result,
791 2.1 expected successful notification(s) have been received; or
794 Processing of the manifest file is aborted when:
795 1. command is synchronous and rpc returns a failed result.
796 2. command is asynchronous, and:
797 2.1 the rpc returns a failed result; or
798 2.2 a failed notification is received; or
801 NOTE: behavior for timeouts (synchronous or asynchronous) may depend upon
802 controller implementation per command. It may be considered either:
803 - as a successful result
805 - as a success or failure based on polling the device
807 list db-backup-manifest-command {
811 "The list of commands to be processed.";
815 "The order in which commands should be processed.";
819 base db-backup-manifest-commands;
823 "The command to be processed.";
825 uses upload-file-command;
826 uses delete-file-command;
827 uses db-backup-command;
831 container db-restore-manifest {
832 presence "The db-restore-manifest template for db-restore operations has been defined.";
834 "The manifest file provides instructions to a database operations
835 application to restore the database on a device.
837 Since the files used for these operations are likely user selected,
838 these manifest files are more likely used by the controller as a
839 template to control the overall flow of a restore operation and provide
840 a means of providing customized timeout and auto-reboot values.
842 The following strings will be recognized as parameters to be replaced
843 by the user selected values: __LOCAL-FILE-PATH, __REMOTE-FILENAME,
847 Each vendor/model combination can have a separate manifest file
848 defined for restore. These shall be named db-restore-manifest.json.
851 leaf is-commit-db-activate-async {
855 "Is cancel-rollback-timer (accept = true) supported as an
856 async or sync command on the device? If supported as sync, the rpc response
857 is used to determine success/failure instead of waiting for transient notifications
859 NOTE: cancel-rollback-timer (accept = false) requires a reboot so is
860 always considered async";
862 leaf cancel-rollback-timer-async-timeout {
865 "timeout value to use for cancel-rollback-timer when supported as
866 an async command. If not specified, the global-async-timeout is used.";
868 leaf cancel-rollback-timer-sync-timeout {
871 "timeout value to use for cancel-rollback-timer (accept = true) when
872 supported as a sync command. If not specified, the global-sync-timeout
875 leaf database-init-sync-timeout {
878 "timeout value to use for database-init command. If not specified,
879 the global-sync-timeout is used.";
881 container db-restore-manifest-commands {
883 "The ordered list of commands to be processed. Since some yang
884 implementations do not support ordered-by user, the list is also
885 indexed by command-order. The commands should be processed
886 in the order of command-order.
888 Processing moves to the next command when:
889 1. command is synchronous and rpc returns a successful result.
890 2. command is asynchronous, the rpc returns a successful result,
892 2.1 expected successful notification(s) have been received; or
895 Processing of the manifest file is aborted when:
896 1. command is synchronous and rpc returns a failed result.
897 2. command is asynchronous, and:
898 2.1 the rpc returns a failed result; or
899 2.2 a failed notification is received; or
902 NOTE: behavior for timeouts (synchronous or asynchronous) may depend upon
903 controller implementation per command. It may be considered either:
904 - as a successful result
906 - as a success or failure based on polling the device
908 list db-restore-manifest-command {
912 "The list of commands to be processed.";
916 "The order in which commands should be processed.";
920 base db-restore-manifest-commands;
924 "The command to be processed.";
926 uses download-file-command;
927 uses delete-file-command;
928 uses db-restore-command;
929 uses db-activate-command;