diff --git a/doc/Clock commands/clock_managment_hld.md b/doc/Clock commands/clock_managment_hld.md new file mode 100644 index 0000000000..427edc6976 --- /dev/null +++ b/doc/Clock commands/clock_managment_hld.md @@ -0,0 +1,229 @@ +# Clock Managment Design # + +## Table of Content + + +* 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. [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 + +| Rev | Date | Author | Change Description | +| :---: | :-----: | :--------------: | :----------------: | +| 0.1 | 01/2023 | Meir Renford | High level Design | + +### 1.2. Scope + +This document will address the high level design for clock commands: +1. Set/show date-time command +2. Set/show timezone command + + +### 1.3 Definitions/Abbreviations + +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 + +1. Any time/date configuration will change accordingly 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. + + +## 2 Design + +### 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. + +hostcfgd will be the daemon in charge of this configuration management. + +CLI Commands desin:
+ + Set operations will be divided into 2 different commands: + + 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. + 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. + + + 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" + * In case NTP is enabled -> time/date set is NOT allowed and being blocked + + 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 + +### 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 { + + container DEVICE_METADATA { + + description "DEVICE_METADATA part of config_db.json"; + + container localhost{ + ... + leaf timezone { + type string; + description "System time-zone setting"; + } +``` + +#### 3.2.2. CLI + +##### Show CLI + +``` +root@host:~$ show clock +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 + +``` +root@host:~$ config clock timezone "" + +``` + +``` +root@host:~$ config clock date + +``` + + +## 4 Test Plan + +### 4.1 Unit Test cases + +1. Good flows:
+ 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 -
+ 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.
+ 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.