From a4968d6f1ca323d03c304f8d974a53125e4f2282 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Thu, 12 Jan 2023 15:45:37 +0200 Subject: [PATCH 01/16] Initial doc for HLD --- doc/Clock commands/clock_managment_hld.md | 92 +++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 doc/Clock commands/clock_managment_hld.md diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md new file mode 100644 index 00000000000..a32d3f99a7f --- /dev/null +++ b/doc/Clock commands/clock_managment_hld.md @@ -0,0 +1,92 @@ +# HLD Name # + +## Table of Content + +### Revision + +### Scope + +This section describes the scope of this high-level design document in SONiC. + +### Definitions/Abbreviations + +This section covers the abbreviation if any, used in this high-level design document and its definitions. + +### Overview + +The purpose of this section is to give an overview of high-level design document and its architecture implementation in SONiC. + +### Requirements + +This section list out all the requirements for the HLD coverage and exemptions (not supported) if any for this design. + +### Architecture Design + +This section covers the changes that are required in the SONiC architecture. In general, it is expected that the current architecture is not changed. +This section should explain how the new feature/enhancement (module/sub-module) fits in the existing architecture. + +If this feature is a SONiC Application Extension mention which changes (if any) needed in the Application Extension infrastructure to support new feature. + +### High-Level Design + +This section covers the high level design of the feature/enhancement. This section covers the following points in detail. + + - Is it a built-in SONiC feature or a SONiC Application Extension? + - What are the modules and sub-modules that are modified for this design? + - What are the repositories that would be changed? + - Module/sub-module interfaces and dependencies. + - SWSS and Syncd changes in detail + - DB and Schema changes (APP_DB, ASIC_DB, COUNTERS_DB, LOGLEVEL_DB, CONFIG_DB, STATE_DB) + - Sequence diagram if required. + - Linux dependencies and interface + - Warm reboot requirements/dependencies + - Fastboot requirements/dependencies + - Scalability and performance requirements/impact + - Memory requirements + - Docker dependency + - Build dependency if any + - Management interfaces - SNMP, CLI, RestAPI, etc., + - Serviceability and Debug (logging, counters, trace etc) related design + - Is this change specific to any platform? Are there dependencies for platforms to implement anything to make this feature work? If yes, explain in detail and inform community in advance. + - SAI API requirements, CLI requirements, ConfigDB requirements. Design is covered in following sections. + +### SAI API + +This section covers the changes made or new API added in SAI API for implementing this feature. If there is no change in SAI API for HLD feature, it should be explicitly mentioned in this section. +This section should list the SAI APIs/objects used by the design so that silicon vendors can implement the required support in their SAI. Note that the SAI requirements should be discussed with SAI community during the design phase and ensure the required SAI support is implemented along with the feature/enhancement. + +### Configuration and management +This section should have sub-sections for all types of configuration and management related design. Example sub-sections for "CLI" and "Config DB" are given below. Sub-sections related to data models (YANG, REST, gNMI, etc.,) should be added as required. + +#### Manifest (if the feature is an Application Extension) + +Paste a preliminary manifest in a JSON format. + +#### CLI/YANG model Enhancements + +This sub-section covers the addition/deletion/modification of CLI changes and YANG model changes needed for the feature in detail. If there is no change in CLI for HLD feature, it should be explicitly mentioned in this section. Note that the CLI changes should ensure downward compatibility with the previous/existing CLI. i.e. Users should be able to save and restore the CLI from previous release even after the new CLI is implemented. +This should also explain the CLICK and/or KLISH related configuration/show in detail. +https://github.com/sonic-net/sonic-utilities/blob/master/doc/Command-Reference.md needs be updated with the corresponding CLI change. + +#### Config DB Enhancements + +This sub-section covers the addition/deletion/modification of config DB changes needed for the feature. If there is no change in configuration for HLD feature, it should be explicitly mentioned in this section. This section should also ensure the downward compatibility for the change. + +### Warmboot and Fastboot Design Impact +Mention whether this feature/enhancement has got any requirements/dependencies/impact w.r.t. warmboot and fastboot. Ensure that existing warmboot/fastboot feature is not affected due to this design and explain the same. + +### Restrictions/Limitations + +### Testing Requirements/Design +Explain what kind of unit testing, system testing, regression testing, warmboot/fastboot testing, etc., +Ensure that the existing warmboot/fastboot requirements are met. For example, if the current warmboot feature expects maximum of 1 second or zero second data disruption, the same should be met even after the new feature/enhancement is implemented. Explain the same here. +Example sub-sections for unit test cases and system test cases are given below. + +#### Unit Test cases + +#### System Test cases + +### Open/Action items - if any + + +NOTE: All the sections and sub-sections given above are mandatory in the design document. Users can add additional sections/sub-sections if required. From 877560080dd59ba5ca853a337498f16f3d4e44c5 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 15:57:58 +0200 Subject: [PATCH 02/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 59 +++++++++++++++++------ 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index a32d3f99a7f..115408eb191 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -1,31 +1,62 @@ -# HLD Name # +# Clock Managment Design # ## Table of Content -### Revision -### Scope +* 1. [Table of Content](#TableofContent) + * 1.1. [Revision](#Revision) + * 1.2. [Scope](#Scope) + * 1.3. [Definitions/Abbreviations](#DefinitionsAbbreviations) + * 1.4. [Overview](#Overview) + * 1.5. [Requirements](#Requirements) + * 1.5.1. [Functional requirements](#FunctionalRequirements) + * 1.5.2. [Configuration and Management Requirements](#ConfigurationManagementRequirements) +* 2. [Design](#Design) + * 2.1. [High-Level Design](#High-LevelDesign) +* 3. [Functionality](#Functionality) + * 3.1. [Reset-Factory](#Reset-Factory) + * 3.2. [Config-setup Factory](#Config-setup-Factory) +* 4. [CLI](#CLI) +* 5. [Restrictions/Limitations](#RestrictionsLimitations) +* 6. [Test Plan](#TestPlan) + * 6.1. [Unit Test cases](#UnitTestcases) -This section describes the scope of this high-level design document in SONiC. -### Definitions/Abbreviations +### 1.1 Revision -This section covers the abbreviation if any, used in this high-level design document and its definitions. +| Rev | Date | Author | Change Description | +| :---: | :-----: | :--------------: | ------------------ | +| 0.1 | 01/2023 | Meir Renford | Phase 1 Design | -### Overview +### 1.2 Scope -The purpose of this section is to give an overview of high-level design document and its architecture implementation in SONiC. +This document will address the high level design for NVOS clock commands: +1. Set/show date-time command +2. Set/show timezone command -### Requirements -This section list out all the requirements for the HLD coverage and exemptions (not supported) if any for this design. +### 1.3 Definitions/Abbreviations -### Architecture Design +N/A + +### 1.4 Overview + +The clock commands allow to set and review the current time parameters of the system - including: time, date and timezone. + +### 1.5 Requirements +#### 1.5.1. Functional requirements -This section covers the changes that are required in the SONiC architecture. In general, it is expected that the current architecture is not changed. -This section should explain how the new feature/enhancement (module/sub-module) fits in the existing architecture. +1. Any time configuration that will change in the system will change the system time. + +#### 1.5.2. Configuration and Management Requirements +The requirements from the module are: +1. Set and show the system time and date. +2. Set and show the system timezone. + + +### Architecture Design -If this feature is a SONiC Application Extension mention which changes (if any) needed in the Application Extension infrastructure to support new feature. +N/A ### High-Level Design From e4607f9ee999055089031f1a8e29f1ff1a3202ad Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 16:00:55 +0200 Subject: [PATCH 03/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 115408eb191..90b5528f3f3 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -28,7 +28,7 @@ | :---: | :-----: | :--------------: | ------------------ | | 0.1 | 01/2023 | Meir Renford | Phase 1 Design | -### 1.2 Scope +### 1.2. Scope This document will address the high level design for NVOS clock commands: 1. Set/show date-time command From d6bd0f1e9a91d1b9f6d3680ac500c5a083e9b371 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 17:59:45 +0200 Subject: [PATCH 04/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 90b5528f3f3..a333c261514 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -22,7 +22,7 @@ * 6.1. [Unit Test cases](#UnitTestcases) -### 1.1 Revision +### 1.1 Revision | Rev | Date | Author | Change Description | | :---: | :-----: | :--------------: | ------------------ | From 9a38f256571a478dc0fe89a6487bb328e6ad6708 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 18:02:09 +0200 Subject: [PATCH 05/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index a333c261514..1f6d45bda0a 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -35,7 +35,7 @@ This document will address the high level design for NVOS clock commands: 2. Set/show timezone command -### 1.3 Definitions/Abbreviations +### 1.3 Definitions/Abbreviations N/A From 8fe98154455519da9262c45f56e33a754667cd1d Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 20:22:35 +0200 Subject: [PATCH 06/16] Update clock_managment_hld.md Updated final version for review --- doc/Clock commands/clock_managment_hld.md | 159 ++++++++++++++-------- 1 file changed, 103 insertions(+), 56 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 1f6d45bda0a..c3e7bb0d511 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -13,13 +13,13 @@ * 1.5.2. [Configuration and Management Requirements](#ConfigurationManagementRequirements) * 2. [Design](#Design) * 2.1. [High-Level Design](#High-LevelDesign) -* 3. [Functionality](#Functionality) - * 3.1. [Reset-Factory](#Reset-Factory) - * 3.2. [Config-setup Factory](#Config-setup-Factory) -* 4. [CLI](#CLI) -* 5. [Restrictions/Limitations](#RestrictionsLimitations) -* 6. [Test Plan](#TestPlan) - * 6.1. [Unit Test cases](#UnitTestcases) +* 3. [Configuration and management](#Configurationandmanagement) + * 3.1. [ConfigDB Tables](#ConfigDBTables) + * 3.2. [CLI/YANG model](#CLIYANGmodel) + * 3.2.1. [Yang model](#Yangmodel) + * 3.2.2. [CLI](#Climodel) +* 4. [Test Plan](#TestPlan) + * 4.1. [Unit Test cases](#UnitTestcases) ### 1.1 Revision @@ -54,70 +54,117 @@ The requirements from the module are: 2. Set and show the system timezone. -### Architecture Design +## 2 Design -N/A +### 2.1 High-Level Design + +The design of this feature is based on Linux command of timedatectl.
+(man page for timedatectl: https://man7.org/linux/man-pages/man1/timedatectl.1.html) + +All set operations are based on this command, executing directly in linux upon user CLI execution. +The time/date/timezone are configured directly to Linux, and is persistent upon any reboot. + +System state of time/date/timezone will appear in 1 line as an output of existing "show clock" command. + +Set operations will be divided into 2 different commands: + +1. config clock set-timezone (to set timezone command) + * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). + * Value will be stored in db for future upgrade operations. + Value is persistent upcon reboot. + * Linux timedatectl with set-timezone flag will be called. + e.g. timedatectl set-timezone "Asia/Kolkata" + + +2. config clock set-date "" (to set time and date) + * Command will recieve single string with date-time format "" + * It will be possible to call command with the following options: + 1. Only with a date + 2. Only with time + 3. both date and time "" + * Command does not need to be stored in DB. + * Linux timedatectl with set-time flag will be called. + e.g. timedatectl set-time "2012-10-30 18:17:16" + + +Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. + + + +## 3 Configuration and management + +### 3.1 ConfigDB Tables + +Only timezone configuration will be saved. +Additional field will be added to DEVICE_METADATA table + +``` +DEVICE_METADATA :{ + "timezone": {{string}} +} +``` + +default value: "Etc/UTC" + + +### 3.2 CLI/YANG model + +#### 3.2.1. Yang model + + +Adding to existing Yang model of device_metadata (https://github.com/sonic-net/sonic-buildimage/blob/master/src/sonic-yang-models/yang-models/sonic-device_metadata.yang) + +``` + container sonic-device_metadata { -### High-Level Design + container DEVICE_METADATA { -This section covers the high level design of the feature/enhancement. This section covers the following points in detail. - - - Is it a built-in SONiC feature or a SONiC Application Extension? - - What are the modules and sub-modules that are modified for this design? - - What are the repositories that would be changed? - - Module/sub-module interfaces and dependencies. - - SWSS and Syncd changes in detail - - DB and Schema changes (APP_DB, ASIC_DB, COUNTERS_DB, LOGLEVEL_DB, CONFIG_DB, STATE_DB) - - Sequence diagram if required. - - Linux dependencies and interface - - Warm reboot requirements/dependencies - - Fastboot requirements/dependencies - - Scalability and performance requirements/impact - - Memory requirements - - Docker dependency - - Build dependency if any - - Management interfaces - SNMP, CLI, RestAPI, etc., - - Serviceability and Debug (logging, counters, trace etc) related design - - Is this change specific to any platform? Are there dependencies for platforms to implement anything to make this feature work? If yes, explain in detail and inform community in advance. - - SAI API requirements, CLI requirements, ConfigDB requirements. Design is covered in following sections. + description "DEVICE_METADATA part of config_db.json"; -### SAI API + container localhost{ + ... + leaf timezone { + type string; + } +``` -This section covers the changes made or new API added in SAI API for implementing this feature. If there is no change in SAI API for HLD feature, it should be explicitly mentioned in this section. -This section should list the SAI APIs/objects used by the design so that silicon vendors can implement the required support in their SAI. Note that the SAI requirements should be discussed with SAI community during the design phase and ensure the required SAI support is implemented along with the feature/enhancement. +#### 3.2.2. CLI -### Configuration and management -This section should have sub-sections for all types of configuration and management related design. Example sub-sections for "CLI" and "Config DB" are given below. Sub-sections related to data models (YANG, REST, gNMI, etc.,) should be added as required. +##### Show CLI -#### Manifest (if the feature is an Application Extension) +``` +root@host:~$ show clock +Sun 15 Jan 2023 06:12:08 PM IST -Paste a preliminary manifest in a JSON format. +``` -#### CLI/YANG model Enhancements +##### Config CLI -This sub-section covers the addition/deletion/modification of CLI changes and YANG model changes needed for the feature in detail. If there is no change in CLI for HLD feature, it should be explicitly mentioned in this section. Note that the CLI changes should ensure downward compatibility with the previous/existing CLI. i.e. Users should be able to save and restore the CLI from previous release even after the new CLI is implemented. -This should also explain the CLICK and/or KLISH related configuration/show in detail. -https://github.com/sonic-net/sonic-utilities/blob/master/doc/Command-Reference.md needs be updated with the corresponding CLI change. +``` +root@host:~$ config clock set-timezone "" -#### Config DB Enhancements +``` -This sub-section covers the addition/deletion/modification of config DB changes needed for the feature. If there is no change in configuration for HLD feature, it should be explicitly mentioned in this section. This section should also ensure the downward compatibility for the change. - -### Warmboot and Fastboot Design Impact -Mention whether this feature/enhancement has got any requirements/dependencies/impact w.r.t. warmboot and fastboot. Ensure that existing warmboot/fastboot feature is not affected due to this design and explain the same. +``` +root@host:~$ config clock set-date "" -### Restrictions/Limitations +``` -### Testing Requirements/Design -Explain what kind of unit testing, system testing, regression testing, warmboot/fastboot testing, etc., -Ensure that the existing warmboot/fastboot requirements are met. For example, if the current warmboot feature expects maximum of 1 second or zero second data disruption, the same should be met even after the new feature/enhancement is implemented. Explain the same here. -Example sub-sections for unit test cases and system test cases are given below. -#### Unit Test cases +## 4 Test Plan -#### System Test cases +### 4.1 Unit Test cases -### Open/Action items - if any +1. Good flows: + a. set timezone + b. set date + c. set time + d. set date & time + e. check reboot / upgrade - -NOTE: All the sections and sub-sections given above are mandatory in the design document. Users can add additional sections/sub-sections if required. +2. Bad flows: + a. set invalid timezone + b. set empty string + c. set invalid date format + d. set invalid time format + e. set invalide date/time format From 0217fc0101ba0275fd306be8e6a4a33a2603e252 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Sun, 15 Jan 2023 20:23:29 +0200 Subject: [PATCH 07/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index c3e7bb0d511..96dfe82e253 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -155,16 +155,16 @@ root@host:~$ config clock set-date "" ### 4.1 Unit Test cases -1. Good flows: - a. set timezone - b. set date - c. set time - d. set date & time - e. check reboot / upgrade - -2. Bad flows: - a. set invalid timezone - b. set empty string - c. set invalid date format - d. set invalid time format - e. set invalide date/time format +1. Good flows:
+ a. set timezone
+ b. set date
+ c. set time
+ d. set date & time
+ e. check reboot / upgrade
+ +2. Bad flows:
+ a. set invalid timezone
+ b. set empty string
+ c. set invalid date format
+ d. set invalid time format
+ e. set invalide date/time format
From 54dd6e6c2b1db14460dbee44f635a5a5daebcf59 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Mon, 16 Jan 2023 06:44:23 +0200 Subject: [PATCH 08/16] Update clock_managment_hld.md Updated validation and NTP interop comments --- doc/Clock commands/clock_managment_hld.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 96dfe82e253..a59ecb730e4 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -70,10 +70,12 @@ Set operations will be divided into 2 different commands: 1. config clock set-timezone (to set timezone command) * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). + Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log. * Value will be stored in db for future upgrade operations. Value is persistent upcon reboot. * Linux timedatectl with set-timezone flag will be called. e.g. timedatectl set-timezone "Asia/Kolkata" + * In case NTP is enabled -> timezone configuration is allowed and overrides the current time. 2. config clock set-date "" (to set time and date) @@ -85,6 +87,7 @@ Set operations will be divided into 2 different commands: * Command does not need to be stored in DB. * Linux timedatectl with set-time flag will be called. e.g. timedatectl set-time "2012-10-30 18:17:16" + * In case NTP is enabled -> time/date set is NOT allowed and being blocked Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. @@ -161,6 +164,7 @@ root@host:~$ config clock set-date "" c. set time
d. set date & time
e. check reboot / upgrade
+ 2. Bad flows:
a. set invalid timezone
@@ -168,3 +172,9 @@ root@host:~$ config clock set-date "" c. set invalid date format
d. set invalid time format
e. set invalide date/time format
+ +3. NTP interop + a. Change time/date, followed by changing NTP - and see time changed.
+ b. try to change time/date in case NTP is enabled -> and expect getting a failure. + c. Change timezone in case NTP is enabled, and expect to succeed and change relevant time. + From 0ab39a3eaece239bbcfc23e73525c954a075096c Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Tue, 17 Jan 2023 18:04:25 +0200 Subject: [PATCH 09/16] Update clock_managment_hld.md --- doc/Clock commands/clock_managment_hld.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index a59ecb730e4..5d36388adc0 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -72,7 +72,7 @@ Set operations will be divided into 2 different commands: * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log. * Value will be stored in db for future upgrade operations. - Value is persistent upcon reboot. + Value is persistent upon reboot. * Linux timedatectl with set-timezone flag will be called. e.g. timedatectl set-timezone "Asia/Kolkata" * In case NTP is enabled -> timezone configuration is allowed and overrides the current time. @@ -173,8 +173,8 @@ root@host:~$ config clock set-date "" d. set invalid time format
e. set invalide date/time format
-3. NTP interop +3. NTP interop
a. Change time/date, followed by changing NTP - and see time changed.
- b. try to change time/date in case NTP is enabled -> and expect getting a failure. - c. Change timezone in case NTP is enabled, and expect to succeed and change relevant time. + b. try to change time/date in case NTP is enabled -> and expect getting a failure.
+ c. Change timezone in case NTP is enabled, and expect to succeed and change relevant time.
From 9be491b64e7eee202084583aa234d35c96870fc9 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Mon, 13 Feb 2023 11:23:19 +0200 Subject: [PATCH 10/16] Update clock_managment_hld.md typos fix --- doc/Clock commands/clock_managment_hld.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 5d36388adc0..ff0eb8e43cf 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -46,7 +46,7 @@ The clock commands allow to set and review the current time parameters of the sy ### 1.5 Requirements #### 1.5.1. Functional requirements -1. Any time configuration that will change in the system will change the system time. +1. Any time/date configuration will change accordingly the system time. #### 1.5.2. Configuration and Management Requirements The requirements from the module are: @@ -90,7 +90,9 @@ Set operations will be divided into 2 different commands: * In case NTP is enabled -> time/date set is NOT allowed and being blocked -Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. +* Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. + +* In case of any set command (time/date/timezone) a relevant message will be print to syslog. From 1f31645dfb4f3c80baf64a4e57ab71112e200c10 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Mon, 13 Feb 2023 15:06:13 +0200 Subject: [PATCH 11/16] Update clock_managment_hld.md Update HLD to community with all comments recieved. --- doc/Clock commands/clock_managment_hld.md | 80 ++++++++++++++++------- 1 file changed, 57 insertions(+), 23 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index ff0eb8e43cf..c518d5b6624 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -26,11 +26,11 @@ | Rev | Date | Author | Change Description | | :---: | :-----: | :--------------: | ------------------ | -| 0.1 | 01/2023 | Meir Renford | Phase 1 Design | +| 0.1 | 01/2023 | Meir Renford | High level Design | ### 1.2. Scope -This document will address the high level design for NVOS clock commands: +This document will address the high level design for clock commands: 1. Set/show date-time command 2. Set/show timezone command @@ -66,34 +66,51 @@ The time/date/timezone are configured directly to Linux, and is persistent upon System state of time/date/timezone will appear in 1 line as an output of existing "show clock" command. -Set operations will be divided into 2 different commands: +hostcfgd will be the daemon in charge of this configuration management. -1. config clock set-timezone (to set timezone command) - * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). - Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log. - * Value will be stored in db for future upgrade operations. - Value is persistent upon reboot. - * Linux timedatectl with set-timezone flag will be called. - e.g. timedatectl set-timezone "Asia/Kolkata" - * In case NTP is enabled -> timezone configuration is allowed and overrides the current time. +CLI Commands desin:
+ Set operations will be divided into 2 different commands: -2. config clock set-date "" (to set time and date) - * Command will recieve single string with date-time format "" - * It will be possible to call command with the following options: - 1. Only with a date - 2. Only with time - 3. both date and time "" - * Command does not need to be stored in DB. - * Linux timedatectl with set-time flag will be called. - e.g. timedatectl set-time "2012-10-30 18:17:16" - * In case NTP is enabled -> time/date set is NOT allowed and being blocked + 1. config clock set-timezone (to set timezone command) + * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). + Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log. + * Value will be stored in db for future upgrade operations. + Value is persistent upon reboot. + * Linux timedatectl with set-timezone flag will be called. + e.g. timedatectl set-timezone "Asia/Kolkata" + * In case NTP is enabled -> timezone configuration is allowed and overrides the current time. + * Date & timezone setting will be reflected of all the services/dockers in the system. -* Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. + 2. config clock set-date "" (to set time and date) + * Command will recieve single string with date-time format "" + * It will be possible to call command with the following options: + 1. Only with a date + 2. Only with time + 3. both date and time "" + * Command does not need to be stored in DB. + * Linux timedatectl with set-time flag will be called. + e.g. timedatectl set-time "2012-10-30 18:17:16" + * In case NTP is enabled -> time/date set is NOT allowed and being blocked -* In case of any set command (time/date/timezone) a relevant message will be print to syslog. + Additional show command will be added to display all valid timezones: + 3. show clock-timezones + + * Will display list of all valid timezones to be configured. + * based on "timedatectl list-timezones" linux command. + + +General notes:
+ + * Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately. + + * In case of any set command (time/date/timezone) a relevant message will be print to syslog. + + * In case of any set command (time/date/timezone) - rsyslog service should be restarted to reflect the time change. + + * Upgrades - timezone configuration is part of DEVICE_METADATA, hence - configuration upgrade will be taken care of as any other sonic configuration. ## 3 Configuration and management @@ -130,6 +147,7 @@ Adding to existing Yang model of device_metadata (https://github.com/sonic-net/s ... leaf timezone { type string; + description "System time-zone setting"; } ``` @@ -143,6 +161,17 @@ Sun 15 Jan 2023 06:12:08 PM IST ``` +``` +root@host:~$ show clock-timezones +Africa/Abidjan +Africa/Accra +Africa/Addis_Ababa +Africa/Algiers +Africa/Asmara +... + +``` + ##### Config CLI ``` @@ -166,6 +195,7 @@ root@host:~$ config clock set-date "" c. set time
d. set date & time
e. check reboot / upgrade
+ f. check docker restart
2. Bad flows:
@@ -180,3 +210,7 @@ root@host:~$ config clock set-date "" b. try to change time/date in case NTP is enabled -> and expect getting a failure.
c. Change timezone in case NTP is enabled, and expect to succeed and change relevant time.
+4. Rsyslog:
+ a. In case of any set command (time/date/timezone) - verify rsyslog service should be restarted to reflect the time change. + +* Functional tests covering flows above will be part of sonic-mgmt tests suite. \ No newline at end of file From 387066a9f13d6706581adfdcea415290dae9707f Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Mon, 13 Feb 2023 15:09:00 +0200 Subject: [PATCH 12/16] Update clock_managment_hld.md added additional tests --- doc/Clock commands/clock_managment_hld.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index c518d5b6624..bfa782a70b9 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -196,6 +196,9 @@ root@host:~$ config clock set-date "" d. set date & time
e. check reboot / upgrade
f. check docker restart
+ g. config load / reload <>
+ h. reboot without config save
+ i. upgrade with manually timedatectl before upgrade
2. Bad flows:
From 1546f86410bbc43974b0a121bf5660d74b88e613 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Mon, 13 Feb 2023 16:39:31 +0200 Subject: [PATCH 13/16] Update clock_managment_hld.md small alignment --- doc/Clock commands/clock_managment_hld.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index bfa782a70b9..e58c39dd8c8 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -25,8 +25,8 @@ ### 1.1 Revision | Rev | Date | Author | Change Description | -| :---: | :-----: | :--------------: | ------------------ | -| 0.1 | 01/2023 | Meir Renford | High level Design | +| :---: | :-----: | :--------------: | :----------------: | +| 0.1 | 01/2023 | Meir Renford | High level Design | ### 1.2. Scope From 1f2798504d5050b6eb47e226de2addee61d5dcc3 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Tue, 11 Apr 2023 11:31:06 +0300 Subject: [PATCH 14/16] Update clock_managment_hld.md adjusted the HLD with the exact cli wording implementation. --- doc/Clock commands/clock_managment_hld.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index e58c39dd8c8..3b1cc8188ec 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -72,7 +72,7 @@ hostcfgd will be the daemon in charge of this configuration management. Set operations will be divided into 2 different commands: - 1. config clock set-timezone (to set timezone command) + 1. config clock timezone (to set timezone command) * will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command). Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log. * Value will be stored in db for future upgrade operations. @@ -83,12 +83,8 @@ hostcfgd will be the daemon in charge of this configuration management. * Date & timezone setting will be reflected of all the services/dockers in the system. - 2. config clock set-date "" (to set time and date) - * Command will recieve single string with date-time format "" - * It will be possible to call command with the following options: - 1. Only with a date - 2. Only with time - 3. both date and time "" + 2. config clock date (to set time and date) + * Command will recieve single string with date-time format * Command does not need to be stored in DB. * Linux timedatectl with set-time flag will be called. e.g. timedatectl set-time "2012-10-30 18:17:16" @@ -96,7 +92,7 @@ hostcfgd will be the daemon in charge of this configuration management. Additional show command will be added to display all valid timezones: - 3. show clock-timezones + 3. show clock timezones * Will display list of all valid timezones to be configured. * based on "timedatectl list-timezones" linux command. @@ -216,4 +212,4 @@ root@host:~$ config clock set-date "" 4. Rsyslog:
a. In case of any set command (time/date/timezone) - verify rsyslog service should be restarted to reflect the time change. -* Functional tests covering flows above will be part of sonic-mgmt tests suite. \ No newline at end of file +* Functional tests covering flows above will be part of sonic-mgmt tests suite. From 58868716e7b59443d735c5618df88cb1fbb33c50 Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Tue, 11 Apr 2023 11:33:18 +0300 Subject: [PATCH 15/16] Update clock_managment_hld.md changed the examples according to exact implementation. --- doc/Clock commands/clock_managment_hld.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index 3b1cc8188ec..8cb66bc41f5 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -158,7 +158,7 @@ Sun 15 Jan 2023 06:12:08 PM IST ``` ``` -root@host:~$ show clock-timezones +root@host:~$ show clock timezones Africa/Abidjan Africa/Accra Africa/Addis_Ababa @@ -171,12 +171,12 @@ Africa/Asmara ##### Config CLI ``` -root@host:~$ config clock set-timezone "" +root@host:~$ config clock timezone "" ``` ``` -root@host:~$ config clock set-date "" +root@host:~$ config clock date ``` From f0821352f28c3ebf181b4f2cf94bd2fd72eec36e Mon Sep 17 00:00:00 2001 From: Meir-renford <119849200+Meir-renford@users.noreply.github.com> Date: Fri, 21 Apr 2023 09:48:03 +0300 Subject: [PATCH 16/16] Update clock_managment_hld.md Added test pass criteria to relevant tests. --- doc/Clock commands/clock_managment_hld.md | 42 +++++++++++++++-------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md index e58c39dd8c8..eb084717f0f 100644 --- a/doc/Clock commands/clock_managment_hld.md +++ b/doc/Clock commands/clock_managment_hld.md @@ -190,23 +190,37 @@ root@host:~$ config clock set-date "" ### 4.1 Unit Test cases 1. Good flows:
- a. set timezone
- b. set date
- c. set time
- d. set date & time
- e. check reboot / upgrade
- f. check docker restart
- g. config load / reload <>
- h. reboot without config save
- i. upgrade with manually timedatectl before upgrade
+ a. set timezone -
+ output of the set command is empty, and expect to see the new timezone in show command output, and the time is correlated with this timezone.

+ + b. set date & time -
+ - output of the set command is empty, and expect to see the new date & time in show command output.

+ + c. check reboot -
+ rebooting without config save restores configuration (timezone) to the saved one.

+ + d. check docker restart -
+ expect to see the time remains as system time.

+ + e. config load / reload <> -
+ expect to see timezone changes upon new configuration.

+ + f. reboot without config save -
+ expect rebooting without config save restores configuration (timezone) to the saved one.

+ + g. upgrade with manually timedatectl before upgrade -
+ Expect to have configuration timezone (if configuration exist) apply and change the timedatectl.

2. Bad flows:
- a. set invalid timezone
- b. set empty string
- c. set invalid date format
- d. set invalid time format
- e. set invalide date/time format
+ a. set invalid timezone -
+ expect for error message for invalid timezone, and timezone shouldn’t change (remains the same in show command output).

+ + b. set empty string -
+ expect for error message for empty / incomplete command. Nothing should be changed after it.

+ + c. set invalide date/time format -
+ expect for error message for the invalid parameter.

3. NTP interop
a. Change time/date, followed by changing NTP - and see time changed.