From 8fff56bf662f45651a97bc3a450f0291311d911a Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Mon, 4 May 2020 10:13:08 -0700 Subject: [PATCH 1/7] First draft of HLD for management framework NTP support --- doc/SONiC_OC_NTP_HLD.txt | 491 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 491 insertions(+) create mode 100644 doc/SONiC_OC_NTP_HLD.txt diff --git a/doc/SONiC_OC_NTP_HLD.txt b/doc/SONiC_OC_NTP_HLD.txt new file mode 100644 index 0000000000..7d0c757708 --- /dev/null +++ b/doc/SONiC_OC_NTP_HLD.txt @@ -0,0 +1,491 @@ +# Feature Name +NTP Support in Management Framework + +# High Level Design Document + +#### Rev 0.1 + +# Table of Contents + * [List of Tables](#list-of-tables) + * [Revision](#revision) + * [About This Manual](#about-this-manual) + * [Scope](#scope) + * [Definition/Abbreviation](#definitionabbreviation) + +# List of Tables +[Table 1: Abbreviations](#table-1-abbreviations) + +# Revision +| Rev | Date | Author | Change Description | +|:---:|:-----------:|:------------------:|-----------------------------------| +| 0.1 | 05/03 | Bing Sun | Initial version | + + +# About this Manual + +This document introduces the support of NTP configuration using management framework. It also describes the mechanism of ntp service upon various NTP configuration changes. + +# Scope + +This document covers NTP "configuration" and "show" commands based on the OpenConfig YANG model, as well as the backend mechanism required to support each command. +NTP unit tests are also included. + +# Definition/Abbreviation + +### Table 1: Abbreviations +| **Term** | **Meaning** | +|--------------------------|-------------------------------------| +| NTP | Network Time Protocol | +| ntpd | NTP Daemon | + + +# 1 Feature Overview + +NTP stands for Network Time Protocol. It is used to synchronize the time of a computer or server to another server or refernce time source. + +SONiC click CLI provides commands to add/delete the IP address of a remote NTP server. Multiple NTP servers can be configured, and both IPv4 an IPv6 are supported. SONiC click CLI also provides the show command to display status of NTP peers. + +With this feature, users will be provided the same capabilities via Management CLI, REST and gNMI using OpenConfig Yang models. +It also provides users to configure NTP source and NTP vrf (Management VRF for now?) for addtional ntp control. + +## 1.1 Requirements + +### 1.1.1 Front end configuration and get capabilities + +#### 1.1.1.1 add/delete NTP server +This installs NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). +The NTP server can be IPv4 address, IPv6 address , or the name of a NTP server. +Mutliple NTP servers can be configured. + +#### 1.1.1.2 add NTP source +This installs the global NTP source information in the Redis ConfigDB and in the ntp.conf file. It enables ntpd to listen to the specific source. +NTP source can be configured as either IP address or interface name. +Only one NTP source will be installed as the global NTP source. A new configured NTP source will override the existing NTP source. + +#### 1.1.1.3 delete NTP source +This deletes the global NTP source entry from the Redis ConfigDB and from the ntp.conf file. + +#### 1.1.1.4 add/delete VRF name +This installs the global NTP VRF information in the Redis ConfigDB. It is used by the ntp configuration script to start the ntpd in a specific VRF context. +For this release, only Management VRF and default instance are supported(?). When the global NTP VRF is deleted, ntpd will be restarted in the default instance. + +#### 1.1.1.5 Get NTP association +This displays the output of "ntpq -p" command. + +### 1.1.2 Backend mechanisms to support configuration and get + +#### 1.1.2.1 add/delete NTP server +The creates or deletes a NTP server entry in the Redis ConfigDB. + +``` + "NTP_SERVER|10.11.0.1": { + "type": "hash", + "value": { + "NULL": "NULL" + } + }, + "NTP_SERVER|2001:aa:aa::a": { + "type": "hash", + "value": { + "NULL": "NULL" + } + }, + "NTP_SERVER|pool.ntp.org": { + "type": "hash", + "value": { + "NULL": "NULL" + } + } +``` + +A change in the NTP_SERVER entry triggers hostcfgd to start the NTP configuration script, which in turn writes each NTP server to the ntp.conf and then restart the ntp service. + +SONiC click CLI only supports IP address for NTP server. It can be extended to server name as well. + + +#### 1.1.2.2 add/delete NTP source + +This creates or deletes a global NTP source entry in the Redis ConfigDB. The NTP source can be a L3 interface name or an interface IP address (IPv4 or IPv6). + +``` + "NTP|global": { + "type": "hash", + "value": { + "source": "Ethernet36" + } + } +``` + +A change in this entry triggers hostcfgd to start the NTP configuration script, which in turn writes the ntp source to the ntp.conf and then restart the ntp service. +Only one global NTP source entry is allowd, and it can be either an interface name or interface IP address. + +SONiC click CLI can be extende to include this configuration. + + +#### 1.1.2.3 add/delete NTP VRF + +This creates or deletes a global NTP vrf entry in the Redis ConfigDB. For this release, it can only be "mgmt"(??). + +``` + "NTP|global": { + "type": "hash", + "value": { + "vrf": "mgmt" + } + } +``` + +A change in this DB entry triggers hostcfgd to restart ntp service. + +When Management VRF is configured, existing SONiC code always restart ntpd in the mgmt vrf context. Since this release introduces support of NTP source, +NTP may listen to a L3 interface in the default instance even with the presence of Management VRF. As a result, ntp service script needs to be modified +to restart the NTP service in the configured NTP vrf instance, or restart the ntp service in default instance if this entry is absent. + +If data vrf as NTP vrf is also supported, then hostcfgd needs to install localhost in the specified vrf in addition. + +SONiC click CLI can be extende to include this configuration. + + +#### 1.1.2.4 get NTP associations + +Transformer function issues "ntpq -p" command, parses the response and maps the outputs to the OpenConfig NTP states. + +### 1.1.3 Functional Requirements + +Provide management framework support to +- configure NTP server +- configure NTP source +- configure NTP vrf + +### 1.1.4 Configuration and Management Requirements +- CLI style configuration and show commands +- REST API support +- gNMI Support + +Details described in Section 3. + +### 1.1.5 Configurations not supported by this feature using management framework: +- NTP authenticate +- NTP authentication-key +- configure local server as a NTP server +- trusted key +- broadcast mode + +### 1.1.6 Scalability Requirements + +### 1.1.7 Warm Boot Requirements + +## 1.2 Design Overview + +### 1.2.1 Basic Approach +Implement NTP support using transformer in sonic-mgmt-framework. + +### 1.2.2 Container +The front end code change will be done in management-framework container including: +- XML file for the CLI +- Python script to handle CLI request (actioner) +- Jinja template to render CLI output (renderer) +- OpenConfig YANG model for NTP openconfig-system.yang and openconfig-system-ext.yang +- SONiC NTP model for NTP based on Redis DB schema of NTP +- transformer functions to + * convert OpenConfig YANG model to SONiC YANG model for NTP related configurations + * convert from Linux command "ntpq -p" output to OpenConfig NTP state YANG model + +### 1.2.3 SAI Overview + +# 2 Functionality + +## 2.1 Target Deployment Use Cases +Manage/configure Management VRF via gNMI, REST and CLI interfaces + +## 2.2 Functional Description +Provide CLI, gNMI and REST supports for Management VRF handling + +## 2.3 Backend change to support new configurations +Provide change in hostcfgd, ntp config script, ntp service script. +SONiC click CLI enhancement if possible. + +# 3 Design + +## 3.1 Overview + +Enhancing the management framework backend code and transformer methods to add support for NTP. + +## 3.2 DB Changes + +### 3.2.1 CONFIG DB +This feature will allow the user to make NTP configuration changes to CONFIG DB, and get NTP peer states. + +### 3.2.2 APP DB + +### 3.2.3 STATE DB + +### 3.2.4 ASIC DB + +### 3.2.5 COUNTER DB + +## 3.3 Switch State Service Design + +### 3.3.1 Orchestration Agent + +### 3.3.2 Other Process + +## 3.4 SyncD + +## 3.5 SAI + +## 3.6 User Interface + +### 3.6.1 Data Models + +YANG models needed for NTP handling in the management framework: +1. **openconfig-system.yang** + +2. **openconfig-system-ext.yang** + +3. **sonic-system-ntp.yang** + +Supported yang objects and attributes: +```diff + +module: openconfig-system + +--rw system + ++ +--rw ntp ++ | +--rw config + | | +--rw enabled? boolean ++ | | +--rw ntp-source-address? oc-inet:ip-address + | | +--rw enable-ntp-auth? boolean ++ | | +--rw oc-sys-ext:ntp-source-interface ++ | | | +--rw oc-sys-ext:interface? -> /oc-if:interfaces/interface/name ++ | | | +--rw oc-sys-ext:subinterface? -> /oc-if:interfaces/interface[oc-if:name=current()/../interface]/subinterfaces/subinterface/index ++ | | +--rw oc-sys-ext:vrf? string + | +--ro state + | | +--ro enabled? boolean ++ | | +--ro ntp-source-address? oc-inet:ip-address + | | +--ro enable-ntp-auth? boolean + | | +--ro auth-mismatch? oc-yang:counter64 ++ | | +--ro oc-sys-ext:ntp-source-interface ++ | | | +--ro oc-sys-ext:interface? -> /oc-if:interfaces/interface/name ++ | | | +--ro oc-sys-ext:subinterface? -> /oc-if:interfaces/interface[oc-if:name=current()/../interface]/subinterfaces/subinterface/index ++ | | +--ro oc-sys-ext:vrf? string + | +--rw ntp-keys + | | +--rw ntp-key* [key-id] + | | +--rw key-id -> ../config/key-id + | | +--rw config + | | | +--rw key-id? uint16 + | | | +--rw key-type? identityref + | | | +--rw key-value? string + | | +--ro state + | | +--ro key-id? uint16 + | | +--ro key-type? identityref + | | +--ro key-value? string ++ | +--rw servers ++ | +--rw server* [address] ++ | +--rw address -> ../config/address ++ | +--rw config ++ | | +--rw address? oc-inet:host + | | +--rw port? oc-inet:port-number + | | +--rw version? uint8 + | | +--rw association-type? enumeration + | | +--rw iburst? boolean + | | +--rw prefer? boolean ++ | +--ro state ++ | +--ro address? oc-inet:host + | +--ro port? oc-inet:port-number + | +--ro version? uint8 + | +--ro association-type? enumeration + | +--ro iburst? boolean + | +--ro prefer? boolean ++ | +--ro stratum? uint8 ++ | +--ro root-delay? uint32 ++ | +--ro root-dispersion? uint64 ++ | +--ro offset? uint64 ++ | +--ro poll-interval? uint32 ++ | +--ro oc-sys-ext:selMode? string ++ | +--ro oc-sys-ext:refid? inet:host ++ | +--ro oc-sys-ext:type? string ++ | +--ro oc-sys-ext:now? uint32 ++ | +--ro oc-sys-ext:reach? uint8 + + +module: sonic-system-ntp + ++ +--rw sonic-system-ntp ++ +--rw NTP ++ | +--rw NTP_LIST* [global_key] ++ | +--rw global_key enumeration ++ | +--rw source? union ++ | +--rw vrf? string ++ +--rw NTP_SERVER ++ +--rw NTP_SERVER_LIST* [server_address] ++ +--rw server_address inet:host + +``` + +### 3.6.2 CLI + + +#### 3.6.2.1 Configuration Commands +All commands are executed in `configuration-view`: +``` +sonic# configure terminal +sonic(config)# +``` + +##### 3.6.2.1.1 Configure NTP server +``` +sonic(config)#ntp + server Configure NTP server +sonic(config)#ntp server +String NTP server address or name + +sonic(config)# ntp server 10.11.0.1 + +sonic(config)# ntp server 2001:aa:aa::a + +sonic(config)# ntp server pool.ntp.org + +``` + +##### 3.6.2.1.2 Delete NTP server + +``` +sonic(config)# no ntp server + String NTP server address or name + +sonic(config)# no ntp server 10.11.0.1 + +sonic(config)# no ntp server 2001:aa:aa::a + +sonic(config)# no ntp server pool.ntp.org + +``` + +##### 3.6.2.1.3 Configure NTP source ip + +``` +sonic(config)# ntp + source Configure source IP address + +sonic(config)# ntp source 11.22.33.55 + +sonic(config)# ntp source 2001:aa:aa::b + +``` + +##### 3.6.2.1.4 Delete NTP source + +``` +sonic(config)# no ntp source + +``` + +##### 3.6.2.1.5 Configure NTP vrf + +``` +sonic(config)# + vrf Enabling NTP on a VRF + +sonic(config)#ntp vrf + management Enable NTP on management VRF + String(Max: 32 characters) Enable NTP on non-default VRF + +sonic(config)# ntp vrf management + +``` + +##### 3.6.2.1.6 Delete NTP vrf + +``` +sonic(config)# no ntp + vrf Disable NTP on a VRF + +sonic(config)# no ntp vrf + management Disable NTP on management VRF + String(Max: 32 characters) Disable NTP on non-default VRF + +sonic(config)# no ntp vrf management + +``` + +#### 3.6.2.2 Show ntp associations + +``` +sonic(config)# do show ntp + associations NTP associations + + +sonic(config)# do show ntp associations + remote refid st t when poll reach delay offset jitter +============================================================================== +*10.11.0.1 10.11.8.1 4 u 28 64 1 0.183 1.499 2.625 ++2001:aa:aa::b 60.39.129.68 10 u 27 64 1 0.638 2171.31 0.411 ++10.11.0.2 10.11.8.1 4 u 24 64 1 0.240 -13.957 12.786 +* master (synced), # master (unsynced), + selected, - candidate, ~ configured + +``` + +#### 3.6.2.3 Debug Commands + +#### 3.6.2.4 IS-CLI Compliance + +### 3.6.3 REST API Support +``` +GET - Get existing NTP configuration information from CONFIG DB. + Get NTP peer states +POST - Add NTP configuration into CONFIG DB. +PATCH - Update existing NTP configuraiton information in CONFIG DB. +DELETE - Delete a existing NTP configuration from CONFIG DB. +``` + +# 4 Flow Diagrams + +# 5 Error Handling + +# 6 Serviceability and Debug + +# 7 Warm Boot Support + +# 8 Scalability + +# 9 Unit Test + +The unit-test for this feature will include: +#### Configuration via CLI + +| Test Name | Test Description | +| :-------- | :----- | +| Configure NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peers | +| Delete NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peers | +| Configure NTP source| Verify NTP source is installed correctly in the configDB, NTP packets are transmitted and received over this source | +| Delete NTP source| Verify that NTP source is removed from the configDB, NTP packets are transmitted and received over the default interface| +| Configure NTP vrf| Verify that NTP vrf is installed correctly in the configDB and ntp service is running in the specified VRF| +| Delete NTP vrf| Verify that NTP vrf is removed from the configDB and ntp service is running in the default instance| +| show ntp associations | Verify ntp associations are displayed correctly | + +#### Configuration via gNMI + +Same test as CLI configuration Test but using gNMI request. +Additional tests will be done to set NTP configuration at different levels of Yang models. + +#### Get configuration via gNMI + +Same as CLI show test but with gNMI request, will verify the JSON response is correct. +Additional tests will be done to get NTP configuration and NTP states at different levels of Yang models. + +#### Configuration via REST (POST/PUT/PATCH) + +Same test as CLI configuration Test but using REST POST request +Additional tests will be done to set NTP configuration at different levels of Yang models. + + +#### Get configuration via REST (GET) + +Same as CLI show test but with REST GET request, will verify the JSON response is correct. +Additional tests will be done to get NTP configuration and NTP states at different levels of Yang models. + + +# 10 Internal Design Information + + From dd4ccdf6f82fa2b791d15f51a156a4ec46a1f9d1 Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Mon, 4 May 2020 10:31:56 -0700 Subject: [PATCH 2/7] mv .txt to .md --- doc/{SONiC_OC_NTP_HLD.txt => SONiC_OC_NTP_HLD.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{SONiC_OC_NTP_HLD.txt => SONiC_OC_NTP_HLD.md} (100%) diff --git a/doc/SONiC_OC_NTP_HLD.txt b/doc/SONiC_OC_NTP_HLD.md similarity index 100% rename from doc/SONiC_OC_NTP_HLD.txt rename to doc/SONiC_OC_NTP_HLD.md From dd2ed31f4619a79ee7fde9c1d0364b32fb44c7bc Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Mon, 21 Sep 2020 15:22:40 -0700 Subject: [PATCH 3/7] add clarification --- doc/SONiC_OC_NTP_HLD.md | 416 ++++++++++++++++++++++++++-------------- 1 file changed, 275 insertions(+), 141 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index 7d0c757708..6df0e3ba81 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -18,12 +18,14 @@ NTP Support in Management Framework # Revision | Rev | Date | Author | Change Description | |:---:|:-----------:|:------------------:|-----------------------------------| -| 0.1 | 05/03 | Bing Sun | Initial version | +| 0.1 | 05/03/2020 | Bing Sun | Initial version | +| 0.2 | 06/15/2020 | Bing Sun | Update based on comments | +| 0.3 | 09/21/2020 | Bing Sun | Add dhcp behavior | # About this Manual -This document introduces the support of NTP configuration using management framework. It also describes the mechanism of ntp service upon various NTP configuration changes. +This document introduces the support of NTP configuration using management framework. It also describes the corresponding backend ntp configuration and service restart upon configuration changes discussed here. # Scope @@ -37,45 +39,66 @@ NTP unit tests are also included. |--------------------------|-------------------------------------| | NTP | Network Time Protocol | | ntpd | NTP Daemon | +| mgmt VRF | Management VRF | # 1 Feature Overview -NTP stands for Network Time Protocol. It is used to synchronize the time of a computer or server to another server or refernce time source. +NTP stands for Network Time Protocol. It is used to synchronize the time of a computer or server to another server or reference time source. -SONiC click CLI provides commands to add/delete the IP address of a remote NTP server. Multiple NTP servers can be configured, and both IPv4 an IPv6 are supported. SONiC click CLI also provides the show command to display status of NTP peers. +SONiC click CLI provides commands to add and delete the IP address of a remote NTP server. Multiple NTP servers can be configured, and both IPv4 and IPv6 are supported. SONiC click CLI also provides the show command (output of "ntpq -pn"). -With this feature, users will be provided the same capabilities via Management CLI, REST and gNMI using OpenConfig Yang models. -It also provides users to configure NTP source and NTP vrf (Management VRF for now?) for addtional ntp control. +This feature provides users the same capabilities via Management CLI, REST and gNMI using OpenConfig YANG models. +In addition, it provides users to configure NTP source interface and NTP vrf. For this release, only "mgmt" and "default" vrf can be configured as NTP vrf. ## 1.1 Requirements ### 1.1.1 Front end configuration and get capabilities #### 1.1.1.1 add/delete NTP server -This installs NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). -The NTP server can be IPv4 address, IPv6 address , or the name of a NTP server. -Mutliple NTP servers can be configured. - -#### 1.1.1.2 add NTP source -This installs the global NTP source information in the Redis ConfigDB and in the ntp.conf file. It enables ntpd to listen to the specific source. -NTP source can be configured as either IP address or interface name. -Only one NTP source will be installed as the global NTP source. A new configured NTP source will override the existing NTP source. - -#### 1.1.1.3 delete NTP source -This deletes the global NTP source entry from the Redis ConfigDB and from the ntp.conf file. - -#### 1.1.1.4 add/delete VRF name -This installs the global NTP VRF information in the Redis ConfigDB. It is used by the ntp configuration script to start the ntpd in a specific VRF context. -For this release, only Management VRF and default instance are supported(?). When the global NTP VRF is deleted, ntpd will be restarted in the default instance. - -#### 1.1.1.5 Get NTP association -This displays the output of "ntpq -p" command. - +Add/delete NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). +The NTP server can be IPv4 address, IPv6 address , or a ntp pool name. +Mutliple NTP servers can be configured. + +#### 1.1.1.2 add/delete NTP source interface +Add/delete the global NTP source interface in the Redis ConfigDB and in the ntp.conf file. The ip address of this interface will be used by ntpd as source ip for all NTP packets. +Only one NTP source interface can be configured. +Following interfaces can be used as NTP source interface when "mgmt" is not configured as NTP vrf. +- Ethernet interface +- PortChannel +- Vlan interface +- Loopback interfacee +- eth0 + +#### 1.1.1.3 add/delete VRF name +Add/delete the global NTP VRF information in the Redis ConfigDB. It is used by /etc/init.d/ntp script to start the ntpd in a specific VRF context. +For this release, only Management VRF and default instance are supported. + +#### 1.1.1.4 Get NTP association +This displays the output of "ntpq -np" command. + +#### 1.1.1.5 Overall Behavior related to NTP source interface and NTP vrf +##### When mgmt VRF is configured +a.if no ntp vrf is configured, ntp service starts in mgmt VRF context by default +b.if "mgmt" is configured as NTP vrf, ntp service starts in mgmt VRF context +c.if "default" is configured as NTP vrf, ntp service starts in default vrf context + +##### When mgmt VRF is not configured +ntp service always starts in default vrf context + +##### NTP source interface related +a.if NTP vrf is empty or "default", NTP source interface can be configured +b.if NTP vrf is "mgmt", configuration of “ntp source-interface” will be rejected +c.if NTP source interface is configured, configuration of "mgmt" as NTP vrf will be rejected +d.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets +e.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured +f.if NTP vrf is "mgmt", eth0/mgmt interface ip will be used as source ip for all ntp packets by default + + ### 1.1.2 Backend mechanisms to support configuration and get #### 1.1.2.1 add/delete NTP server -The creates or deletes a NTP server entry in the Redis ConfigDB. +This creates or deletes a NTP server entry in the Redis ConfigDB. ``` "NTP_SERVER|10.11.0.1": { @@ -100,31 +123,31 @@ The creates or deletes a NTP server entry in the Redis ConfigDB. A change in the NTP_SERVER entry triggers hostcfgd to start the NTP configuration script, which in turn writes each NTP server to the ntp.conf and then restart the ntp service. -SONiC click CLI only supports IP address for NTP server. It can be extended to server name as well. +SONiC click CLI only supports IP address for NTP server. It can be extended to ntp pool name as well. -#### 1.1.2.2 add/delete NTP source +#### 1.1.2.2 add/delete NTP source -This creates or deletes a global NTP source entry in the Redis ConfigDB. The NTP source can be a L3 interface name or an interface IP address (IPv4 or IPv6). +This creates or deletes a global NTP source interface entry in the Redis ConfigDB. ``` "NTP|global": { "type": "hash", "value": { - "source": "Ethernet36" + "src_intf": "Ethernet36" } } ``` -A change in this entry triggers hostcfgd to start the NTP configuration script, which in turn writes the ntp source to the ntp.conf and then restart the ntp service. -Only one global NTP source entry is allowd, and it can be either an interface name or interface IP address. +A change in this entry triggers hostcfgd to start the NTP configuration script, which in turn writes the ntp source interface to the ntp.conf and then restart the ntp service. +Only one global NTP source entry is allowed. -SONiC click CLI can be extende to include this configuration. - +SONiC click CLI can be extended to include this configuration. + -#### 1.1.2.3 add/delete NTP VRF +#### 1.1.2.3 add/delete NTP VRF -This creates or deletes a global NTP vrf entry in the Redis ConfigDB. For this release, it can only be "mgmt"(??). +This creates or deletes a global NTP vrf entry in the Redis ConfigDB. For this release, it can only be "mgmt" or "default". ``` "NTP|global": { @@ -137,54 +160,53 @@ This creates or deletes a global NTP vrf entry in the Redis ConfigDB. For this r A change in this DB entry triggers hostcfgd to restart ntp service. -When Management VRF is configured, existing SONiC code always restart ntpd in the mgmt vrf context. Since this release introduces support of NTP source, -NTP may listen to a L3 interface in the default instance even with the presence of Management VRF. As a result, ntp service script needs to be modified -to restart the NTP service in the configured NTP vrf instance, or restart the ntp service in default instance if this entry is absent. - -If data vrf as NTP vrf is also supported, then hostcfgd needs to install localhost in the specified vrf in addition. - -SONiC click CLI can be extende to include this configuration. - +SONiC click CLI can be extended to include this configuration. + -#### 1.1.2.4 get NTP associations +#### 1.1.2.4 get NTP associations -Transformer function issues "ntpq -p" command, parses the response and maps the outputs to the OpenConfig NTP states. +Transformer function issues "ntpq -p" command, parses the response and maps the outputs to the OpenConfig system YANG NTP states. -### 1.1.3 Functional Requirements +### 1.1.3 Functional Requirements Provide management framework support to - configure NTP server -- configure NTP source -- configure NTP vrf +- configure NTP source interface +- configure NTP vrf -### 1.1.4 Configuration and Management Requirements +### 1.1.4 Configuration and Management Requirements - CLI style configuration and show commands - REST API support - gNMI Support Details described in Section 3. -### 1.1.5 Configurations not supported by this feature using management framework: +### 1.1.5 Configurations not supported by this feature using management framework: - NTP authenticate - NTP authentication-key - configure local server as a NTP server - trusted key - broadcast mode -### 1.1.6 Scalability Requirements - -### 1.1.7 Warm Boot Requirements +### 1.1.6 Scalability Requirements +Only 1 source interface. +Ntpd runs in one VRF context, default vrf or mgmt vrf. +Multiple ntp servers supported. + +### 1.1.7 Warm Boot Requirements +NA -## 1.2 Design Overview +## 1.2 Design Overview -### 1.2.1 Basic Approach -Implement NTP support using transformer in sonic-mgmt-framework. +### 1.2.1 Basic Approach +Implement NTP support using transformer in sonic-mgmt-framework. -### 1.2.2 Container +### 1.2.2 Container The front end code change will be done in management-framework container including: - XML file for the CLI - Python script to handle CLI request (actioner) -- Jinja template to render CLI output (renderer) +- Jinja template to render CLI output (renderer) +- front-end code to support "show running-configuration ntp" - OpenConfig YANG model for NTP openconfig-system.yang and openconfig-system-ext.yang - SONiC NTP model for NTP based on Redis DB schema of NTP - transformer functions to @@ -195,26 +217,35 @@ The front end code change will be done in management-framework container includi # 2 Functionality -## 2.1 Target Deployment Use Cases -Manage/configure Management VRF via gNMI, REST and CLI interfaces +## 2.1 Target Deployment Use Cases +Manage/configure NTP via gNMI, REST and CLI interfaces. -## 2.2 Functional Description -Provide CLI, gNMI and REST supports for Management VRF handling +## 2.2 Functional Description +Provide CLI, gNMI and REST supports for NTP related configurations. -## 2.3 Backend change to support new configurations -Provide change in hostcfgd, ntp config script, ntp service script. -SONiC click CLI enhancement if possible. +## 2.3 Backend change to support new configurations +Provide changes in hostcfgd, ntp.conf.j2 and /etc/init.d/ntp. +SONiC click CLI enhancement if possible. -# 3 Design +## 2.4 Behavior when Management IP Address is acquired via DHCP +If the management IP address is acquired via DHCP, and if the NTP server option specifies the NTP server, /etc/dhcp/dhclient-exit-hooks.d/ntp script will generate the file /var/lib/ntp/ntp.conf.dhcp. This file is a copy of the default /etc/ntp.conf with a modified server list from the DHCP server. +NTP daemon only uses one of the 2 files, and /var/lib/ntp/ntp.conf.dhcp takes precedence over the default /etc/ntp.conf. It is the existing behavior and is out of the scope of this HLD. -## 3.1 Overview +NTP source-interface and NTP vrf discussed in the HLD are only guaranteed to take effect on the static configured NTP servers. +For acquired NTP servers from DHCP server, NTP source-interface and NTP vrf will only take effect if /var/lib/ntp/ntp.conf.dhcp is generated based on the /etc/ntp.conf with user configured NTP source-interface. + +Applying the configured NTP source-interface and NTP vrf to acquired NTP servers from the DHCP server is not a requirement for this release. + +# 3 Design + +## 3.1 Overview Enhancing the management framework backend code and transformer methods to add support for NTP. ## 3.2 DB Changes -### 3.2.1 CONFIG DB -This feature will allow the user to make NTP configuration changes to CONFIG DB, and get NTP peer states. +### 3.2.1 CONFIG DB +This feature will allow users to make NTP configuration changes to CONFIG DB, and get NTP configurations. ### 3.2.2 APP DB @@ -236,7 +267,7 @@ This feature will allow the user to make NTP configuration changes to CONFIG DB, ## 3.6 User Interface -### 3.6.1 Data Models +### 3.6.1 Data Models YANG models needed for NTP handling in the management framework: 1. **openconfig-system.yang** @@ -247,27 +278,17 @@ YANG models needed for NTP handling in the management framework: Supported yang objects and attributes: ```diff - -module: openconfig-system - +--rw system - -+ +--rw ntp -+ | +--rw config + +--rw ntp + | +--rw config | | +--rw enabled? boolean -+ | | +--rw ntp-source-address? oc-inet:ip-address | | +--rw enable-ntp-auth? boolean -+ | | +--rw oc-sys-ext:ntp-source-interface -+ | | | +--rw oc-sys-ext:interface? -> /oc-if:interfaces/interface/name -+ | | | +--rw oc-sys-ext:subinterface? -> /oc-if:interfaces/interface[oc-if:name=current()/../interface]/subinterfaces/subinterface/index ++ | | +--rw oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--rw oc-sys-ext:vrf? string | +--ro state | | +--ro enabled? boolean -+ | | +--ro ntp-source-address? oc-inet:ip-address | | +--ro enable-ntp-auth? boolean | | +--ro auth-mismatch? oc-yang:counter64 -+ | | +--ro oc-sys-ext:ntp-source-interface -+ | | | +--ro oc-sys-ext:interface? -> /oc-if:interfaces/interface/name -+ | | | +--ro oc-sys-ext:subinterface? -> /oc-if:interfaces/interface[oc-if:name=current()/../interface]/subinterfaces/subinterface/index ++ | | +--ro oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--ro oc-sys-ext:vrf? string | +--rw ntp-keys | | +--rw ntp-key* [key-id] @@ -280,8 +301,8 @@ module: openconfig-system | | +--ro key-id? uint16 | | +--ro key-type? identityref | | +--ro key-value? string -+ | +--rw servers -+ | +--rw server* [address] + | +--rw servers + | +--rw server* [address] + | +--rw address -> ../config/address + | +--rw config + | | +--rw address? oc-inet:host @@ -291,23 +312,25 @@ module: openconfig-system | | +--rw iburst? boolean | | +--rw prefer? boolean + | +--ro state -+ | +--ro address? oc-inet:host - | +--ro port? oc-inet:port-number - | +--ro version? uint8 - | +--ro association-type? enumeration - | +--ro iburst? boolean - | +--ro prefer? boolean -+ | +--ro stratum? uint8 -+ | +--ro root-delay? uint32 -+ | +--ro root-dispersion? uint64 -+ | +--ro offset? uint64 -+ | +--ro poll-interval? uint32 -+ | +--ro oc-sys-ext:selMode? string -+ | +--ro oc-sys-ext:refid? inet:host -+ | +--ro oc-sys-ext:type? string -+ | +--ro oc-sys-ext:now? uint32 -+ | +--ro oc-sys-ext:reach? uint8 - ++ | +--ro address? oc-inet:host + | +--ro port? oc-inet:port-number + | +--ro version? uint8 + | +--ro association-type? enumeration + | +--ro iburst? boolean + | +--ro prefer? boolean ++ | +--ro stratum? uint8 + | +--ro root-delay? uint32 + | +--ro root-dispersion? uint64 + | +--ro offset? uint64 ++ | +--ro poll-interval? uint32 ++ | +--ro oc-sys-ext:peerdelay? decimal64 ++ | +--ro oc-sys-ext:peeroffset? decimal64 ++ | +--ro oc-sys-ext:peerjitter? decimal64 ++ | +--ro oc-sys-ext:selmode? string ++ | +--ro oc-sys-ext:refid? inet:host ++ | +--ro oc-sys-ext:peertype? string ++ | +--ro oc-sys-ext:now? uint32 ++ | +--ro oc-sys-ext:reach? uint8 module: sonic-system-ntp @@ -315,7 +338,7 @@ module: sonic-system-ntp + +--rw NTP + | +--rw NTP_LIST* [global_key] + | +--rw global_key enumeration -+ | +--rw source? union ++ | +--rw src_intf? union + | +--rw vrf? string + +--rw NTP_SERVER + +--rw NTP_SERVER_LIST* [server_address] @@ -331,6 +354,12 @@ All commands are executed in `configuration-view`: ``` sonic# configure terminal sonic(config)# + +sonic(config)# ntp + server Configure NTP server + source-interface Configure NTP source interface to pick the source IP, used for the NTP packets + vrf Enable NTP on VRF + ``` ##### 3.6.2.1.1 Configure NTP server @@ -362,25 +391,44 @@ sonic(config)# no ntp server pool.ntp.org ``` -##### 3.6.2.1.3 Configure NTP source ip +##### 3.6.2.1.3 Configure NTP source interface ``` -sonic(config)# ntp - source Configure source IP address - -sonic(config)# ntp source 11.22.33.55 +sonic(config)# ntp source-interface + Ethernet Ethernet interface + Loopback Loopback interface + Management Management Interface + PortChannel PortChannel interface + Vlan Vlan interface + +sonic(config)# ntp source-interface Ethernet 48 +sonic(config)# +sonic(config)# -sonic(config)# ntp source 2001:aa:aa::b +sonic(config)# ntp source-interface Loopback 100 +sonic(config)# +sonic(config)# +sonic(config)# +sonic(config)# ntp source-interface Management 0 +sonic(config)# +sonic(config)# +sonic(config)# +sonic(config)# ntp source-interface PortChannel 100 +sonic(config)# +sonic(config)# +sonic(config)# +sonic(config)# ntp source-interface Vlan 100 +sonic(config)# ``` - -##### 3.6.2.1.4 Delete NTP source + +##### 3.6.2.1.4 Delete NTP source interface ``` -sonic(config)# no ntp source +sonic(config)# no ntp source-interface ``` - + ##### 3.6.2.1.5 Configure NTP vrf ``` @@ -388,13 +436,11 @@ sonic(config)# vrf Enabling NTP on a VRF sonic(config)#ntp vrf - management Enable NTP on management VRF - String(Max: 32 characters) Enable NTP on non-default VRF - -sonic(config)# ntp vrf management + mgmt Enable NTP on management VRF + default Enable NTP on default VRF ``` - + ##### 3.6.2.1.6 Delete NTP vrf ``` @@ -402,21 +448,22 @@ sonic(config)# no ntp vrf Disable NTP on a VRF sonic(config)# no ntp vrf - management Disable NTP on management VRF - String(Max: 32 characters) Disable NTP on non-default VRF - -sonic(config)# no ntp vrf management ``` - -#### 3.6.2.2 Show ntp associations - + +#### 3.6.2.2 Show ntp ``` -sonic(config)# do show ntp - associations NTP associations +sonic# show ntp + associations Display NTP associations + global Display NTP global configuration + server Display NTP server configuration +``` + +##### 3.6.2.2.1 show ntp associations -sonic(config)# do show ntp associations +``` +sonic# show ntp associations remote refid st t when poll reach delay offset jitter ============================================================================== *10.11.0.1 10.11.8.1 4 u 28 64 1 0.183 1.499 2.625 @@ -425,20 +472,101 @@ sonic(config)# do show ntp associations * master (synced), # master (unsynced), + selected, - candidate, ~ configured ``` + +##### 3.6.2.2.2 Show configured ntp servers +``` +sonic# show ntp server +-------------------------------- +NTP Servers +-------------------------------- +10.11.0.1 +10.11.0.2 +``` + +##### 3.6.2.2.3 Show global ntp configurations +``` +sonic# show ntp global +---------------------------------------------- +NTP Global Configuration +---------------------------------------------- +NTP source-interface: Ethernet24 +NTP vrf: default + +``` + +##### 3.6.2.2.4 Show running-configuration +``` +sonic(config)# ntp server 10.11.0.1 +sonic(config)# ntp server pool.ntp.org +sonic(config)# ntp source-interface Ethernet 16 +sonic(config)# do show running-configuration +! +ntp server 10.11.0.1 +ntp server pool.ntp.org +ntp source-interface Ethernet 16 +! + +sonic(config)# no ntp source-interface +sonic(config)# ntp vrf mgmt +sonic(config)# do show running-configuration +! +ntp server 10.11.0.1 +ntp server pool.ntp.org +ntp vrf mgmt +! + +sonic(config)# ntp vrf default +sonic(config)# do show running-configuration +! +ntp server 10.11.0.1 +ntp server pool.ntp.org +ntp vrf default +! + +``` + #### 3.6.2.3 Debug Commands +``` +From KLISH: + +show ntp associations + +show ntp server + +show ntp global + +``` + +``` +From shell: + +servcie ntp status + +check /etc/ntp.conf +check /var/log/syslog and look for ntp + +ifconfig lo + +ifconfig lo-m + +show mgmt-vrf + +``` + #### 3.6.2.4 IS-CLI Compliance ### 3.6.3 REST API Support ``` GET - Get existing NTP configuration information from CONFIG DB. - Get NTP peer states + Get NTP peer states +PUT - Create NTP configuration into CONFIG DB. POST - Add NTP configuration into CONFIG DB. PATCH - Update existing NTP configuraiton information in CONFIG DB. DELETE - Delete a existing NTP configuration from CONFIG DB. ``` - + # 4 Flow Diagrams # 5 Error Handling @@ -446,6 +574,7 @@ DELETE - Delete a existing NTP configuration from CONFIG DB. # 6 Serviceability and Debug # 7 Warm Boot Support +NA # 8 Scalability @@ -457,34 +586,39 @@ The unit-test for this feature will include: | Test Name | Test Description | | :-------- | :----- | | Configure NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peers | -| Delete NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peers | -| Configure NTP source| Verify NTP source is installed correctly in the configDB, NTP packets are transmitted and received over this source | -| Delete NTP source| Verify that NTP source is removed from the configDB, NTP packets are transmitted and received over the default interface| +| Delete NTP server | Verify NTP server is deleted from the configDB and reflected in the NTP peers | +| Configure NTP source interface| Verify NTP source interface is installed correctly in the configDB, NTP packets are transmitted and received over this source | +| | Verify that NTP source interface cannot be configured if NTP vrf is mgmt| +| Delete NTP source interface| Verify that NTP source interface is removed from the configDB, NTP packets are transmitted and received over the default interface| | Configure NTP vrf| Verify that NTP vrf is installed correctly in the configDB and ntp service is running in the specified VRF| +| | Verify that only default and mgmt can be configured as NTP vrf| +| | Verify that mgmt cannot be configured as NTP vrf if NTP source interface is configured| | Delete NTP vrf| Verify that NTP vrf is removed from the configDB and ntp service is running in the default instance| | show ntp associations | Verify ntp associations are displayed correctly | +| show ntp server | Verify ntp servers are displayed correctly | +| show ntp global | Verify ntp global configurations are displayed correctly | #### Configuration via gNMI Same test as CLI configuration Test but using gNMI request. -Additional tests will be done to set NTP configuration at different levels of Yang models. +Additional tests will be done to set NTP configuration at different levels of YANG models. #### Get configuration via gNMI Same as CLI show test but with gNMI request, will verify the JSON response is correct. -Additional tests will be done to get NTP configuration and NTP states at different levels of Yang models. +Additional tests will be done to get NTP configuration and NTP states at different levels of YANG models. #### Configuration via REST (POST/PUT/PATCH) -Same test as CLI configuration Test but using REST POST request -Additional tests will be done to set NTP configuration at different levels of Yang models. +Same test as CLI configuration Test but using REST POST/PUT/PATCH request. +Additional tests will be done to set NTP configuration at different levels of YANG models. #### Get configuration via REST (GET) Same as CLI show test but with REST GET request, will verify the JSON response is correct. -Additional tests will be done to get NTP configuration and NTP states at different levels of Yang models. - +Additional tests will be done to get NTP configuration and NTP states at different levels of YANG models. + # 10 Internal Design Information From acc38d089d98834f111d75a38f1bc598822ad90f Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Tue, 3 Nov 2020 01:25:39 -0800 Subject: [PATCH 4/7] add support for NTP authentication --- doc/SONiC_OC_NTP_HLD.md | 389 +++++++++++++++++++++++++++++++++++----- 1 file changed, 341 insertions(+), 48 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index 6df0e3ba81..9701803241 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -3,7 +3,7 @@ NTP Support in Management Framework # High Level Design Document -#### Rev 0.1 +#### Rev 0.4 # Table of Contents * [List of Tables](#list-of-tables) @@ -21,6 +21,7 @@ NTP Support in Management Framework | 0.1 | 05/03/2020 | Bing Sun | Initial version | | 0.2 | 06/15/2020 | Bing Sun | Update based on comments | | 0.3 | 09/21/2020 | Bing Sun | Add dhcp behavior | +| 0.4 | 11/02/2020 | Bing Sun | Add support for NTP authentication| # About this Manual @@ -55,15 +56,36 @@ In addition, it provides users to configure NTP source interface and NTP vrf. Fo ### 1.1.1 Front end configuration and get capabilities -#### 1.1.1.1 add/delete NTP server +#### 1.1.1.1 add/delete NTP server +``` +ntp server 99.1.1.1 +ntp server pool.ntp.org +``` Add/delete NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). The NTP server can be IPv4 address, IPv6 address , or a ntp pool name. Mutliple NTP servers can be configured. #### 1.1.1.2 add/delete NTP source interface +``` +ntp source-interface Ethernet36 +``` + +``` +ntp source-interface PortChannel 100 +``` + +``` +ntp source-interface Vlan 100 +``` + +``` +ntp source-interface Management 0 +``` + + Add/delete the global NTP source interface in the Redis ConfigDB and in the ntp.conf file. The ip address of this interface will be used by ntpd as source ip for all NTP packets. Only one NTP source interface can be configured. -Following interfaces can be used as NTP source interface when "mgmt" is not configured as NTP vrf. +Following interfaces can be used as NTP source interface, - Ethernet interface - PortChannel - Vlan interface @@ -71,10 +93,22 @@ Following interfaces can be used as NTP source interface when "mgmt" is not conf - eth0 #### 1.1.1.3 add/delete VRF name +``` +ntp vrf default +``` + +``` +ntp vrf mgmt +``` + Add/delete the global NTP VRF information in the Redis ConfigDB. It is used by /etc/init.d/ntp script to start the ntpd in a specific VRF context. For this release, only Management VRF and default instance are supported. #### 1.1.1.4 Get NTP association +``` +show ntp association +``` + This displays the output of "ntpq -np" command. #### 1.1.1.5 Overall Behavior related to NTP source interface and NTP vrf @@ -87,14 +121,49 @@ c.if "default" is configured as NTP vrf, ntp service starts in default vrf conte ntp service always starts in default vrf context ##### NTP source interface related -a.if NTP vrf is empty or "default", NTP source interface can be configured -b.if NTP vrf is "mgmt", configuration of “ntp source-interface” will be rejected -c.if NTP source interface is configured, configuration of "mgmt" as NTP vrf will be rejected -d.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets -e.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured -f.if NTP vrf is "mgmt", eth0/mgmt interface ip will be used as source ip for all ntp packets by default +a.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets +b.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured +#### 1.1.1.6 NTP authentication configuration +NTP authentication enables an NTP client or peer to authenticate time received from their servers and peers. + +##### ntp authenticate +``` +ntp authenticate +``` + +This command enable the NTP authentication feature + +##### ntp authentication-key +``` +ntp authentication-key 1 md5 "ntp client 1" + +ntp authentication-key 2 md5 ntp_client2 +``` + +This command defines an authentication key with key number, authentication type and password. +The key number is from 1 to 65535. +The authentication type supported is MD5, SHA1 and SHA2-256. +The password is configured with plaintext the first time. In runnning-configuration, it is encrypted with the flag "encrypted" at the end. Authentication key can then be configured with encrypted format and "encrypted" flag. + + +##### ntp trusted key +``` +ntp trusted-key 1 + +ntp trusted-key 2 +``` +This command adds the list of key numbers that the NTP server must provide in its NTP packets in order for the NTP clients +to synchronize to it. + +##### ntp server key +``` +ntp server 99.1.1.1 key 1 +``` + +This command configures the key expected from a specific NTP server. + ### 1.1.2 Backend mechanisms to support configuration and get #### 1.1.2.1 add/delete NTP server @@ -165,7 +234,129 @@ SONiC click CLI can be extended to include this configuration. #### 1.1.2.4 get NTP associations -Transformer function issues "ntpq -p" command, parses the response and maps the outputs to the OpenConfig system YANG NTP states. +Transformer function issues "ntpq -pn" command, parses the response and maps the outputs to the OpenConfig system YANG NTP states. + +#### 1.1.2.5 NTP authentication + +##### 1.1.2.5.1 enable or disable ntp authenticate + +When "authenticate" is enabled, "enable-ntp-auth" field is set to "true" in the NTP global entry, + +``` +"NTP|global": { + "type": "hash", + "value": { + "enable-ntp-auth": "true", + } +} +``` + +This change triggers /etc/ntp.conf to get generated with the line indicating where to find the configured keys +``` +key /etc/ntp.keys +``` + +When "authenticate" is removed, the same attribute is set to "false". The file /etc/ntp.conf is generated without "key /etc/ntp.keys" but with the line +``` +disable auth +``` + +The file /etc/ntp.keys will be created with the configured authentication keys if "authenticate" is enabled, and removed if "authenticate" is disabled. + +##### 1.1.2.5.2 Add or delete ntp authentication key + +When an authentication key is configured with a key number, authentication type and password in plaintext, a transformer function will change the plaintext password to the encrypted format and puts the key in an NTP_AUTHENTICATION_KEY ConfigDB entry. A boolean "key_encrypted" is set to true and added in the same entry as well. This is done so that "show running-configuration" from CLI or GET from REST/gNMI will be able to display the password in encrypted format. For example, +``` + "NTP_AUTHENTICATION_KEY|1": { + "type": "hash", + "value": { + "key_encrypted": "true", + "key_type": "MD5", + "key_value": "3b88c0eb8406a9e76722b84baf1d94e5e185eb7f64f8dd46c759719c33557876" + } + } +``` + +If "authenticate" is enabled, the file /etc/ntp.keys is populated with the configured authentication keys. The password in this file is in the plaintext format. + +When an ntp authentication key is removed, the ConfigDb and /etc/ntp.keys will be updated accordingly. + +##### 1.1.2.5.3 Add or delete ntp trusted key + +When a ntp trusted key number is configured, the key number is added to the "trustedkeys" list in the NTP global entry, e.g +``` + "NTP|global": { + "type": "hash", + "value": { + "authenticat": enabled, + "trustedkeys@": "1,2" + } + } +``` + +/etc/ntp.conf will be generated with the line +``` +trustedkey 1 2 +``` + +When a ntp trusted key number is removed, the key number is removed from the "trustedkey" list. + + +##### 1.1.2.5.4 Add a key for NTP server + +When a ntp server is created with a key number, the "key_id" with the key number will be added as a field for the NTP server ConfigDb entry, e.g +``` +"NTP_SERVER|99.1.1.1": { + "type": "hash", + "value": { + "key_id": "1" + } + } +``` + +The file /etc/ntp.conf will be generated with the same key number for that NTP server, e.g +``` +server 99.1.1.1 iburst key 1 +``` + +##### 1.1.2.5.5 Sample ntp.conf and ntp.keys +###### Relevant entries in ntp.conf for NTP server +``` +keys /etc/ntp.keys + +server 10.14.8.140 iburst + +# By default, exchange time with everybody, but don't allow configuration. +restrict -4 default kod notrap nomodify nopeer noquery +restrict -6 default kod notrap nomodify nopeer noquery + +interface listen Loopback100 +interface listen 127.0.0.1 + +trustedkey 1 2 +``` + +###### Relevant entries in ntp.keys on NTP server +``` +1 MD5 ntp client 1 +2 MD5 ntp_client_2 +``` + +###### Relevant entries in ntp.conf on NTP client +``` +keys /etc/ntp.keys + +server 99.1.1.1 iburst key 1 + +interface listen Vlan100 + +trustedkey 1 +``` + +###### Relevant entries in ntp.keys on NTP client +``` +1 MD5 ntp client 1 +``` ### 1.1.3 Functional Requirements @@ -173,7 +364,8 @@ Provide management framework support to - configure NTP server - configure NTP source interface - configure NTP vrf - +- configure NTP authentication + ### 1.1.4 Configuration and Management Requirements - CLI style configuration and show commands - REST API support @@ -182,16 +374,13 @@ Provide management framework support to Details described in Section 3. ### 1.1.5 Configurations not supported by this feature using management framework: -- NTP authenticate -- NTP authentication-key -- configure local server as a NTP server -- trusted key +- configure local server as a NTP master - broadcast mode - + ### 1.1.6 Scalability Requirements -Only 1 source interface. -Ntpd runs in one VRF context, default vrf or mgmt vrf. -Multiple ntp servers supported. +Only 1 source interface, assuming the remote NTP peer has route to this source interface +Ntpd runs in one VRF context, default vrf or mgmt vrf. +Multiple ntp servers supported. ### 1.1.7 Warm Boot Requirements NA @@ -206,7 +395,7 @@ The front end code change will be done in management-framework container includi - XML file for the CLI - Python script to handle CLI request (actioner) - Jinja template to render CLI output (renderer) -- front-end code to support "show running-configuration ntp" +- front-end code to support "show running-configuration" - OpenConfig YANG model for NTP openconfig-system.yang and openconfig-system-ext.yang - SONiC NTP model for NTP based on Redis DB schema of NTP - transformer functions to @@ -224,7 +413,7 @@ Manage/configure NTP via gNMI, REST and CLI interfaces. Provide CLI, gNMI and REST supports for NTP related configurations. ## 2.3 Backend change to support new configurations -Provide changes in hostcfgd, ntp.conf.j2 and /etc/init.d/ntp. +Provide changes in hostcfgd, ntp.conf.j2, ntp.keys.j2 and /etc/init.d/ntp. SONiC click CLI enhancement if possible. ## 2.4 Behavior when Management IP Address is acquired via DHCP @@ -281,26 +470,28 @@ Supported yang objects and attributes: +--rw ntp | +--rw config | | +--rw enabled? boolean - | | +--rw enable-ntp-auth? boolean ++ | | +--rw enable-ntp-auth? boolean + | | +--rw oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--rw oc-sys-ext:vrf? string | +--ro state | | +--ro enabled? boolean - | | +--ro enable-ntp-auth? boolean ++ | | +--ro enable-ntp-auth? boolean | | +--ro auth-mismatch? oc-yang:counter64 + | | +--ro oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--ro oc-sys-ext:vrf? string - | +--rw ntp-keys - | | +--rw ntp-key* [key-id] - | | +--rw key-id -> ../config/key-id - | | +--rw config - | | | +--rw key-id? uint16 - | | | +--rw key-type? identityref - | | | +--rw key-value? string - | | +--ro state - | | +--ro key-id? uint16 - | | +--ro key-type? identityref - | | +--ro key-value? string ++ | +--rw ntp-keys ++ | | +--rw ntp-key* [key-id] ++ | | +--rw key-id -> ../config/key-id ++ | | +--rw config ++ | | | +--rw key-id? uint16 ++ | | | +--rw key-type? identityref ++ | | | +--rw key-value? string ++ | | | +--rw oc-sys-ext:key-encrypted? boolean ++ | | +--ro state ++ | | +--ro key-id? uint16 ++ | | +--ro key-type? identityref ++ | | +--ro key-value? string ++ | | +--rw oc-sys-ext:key-encrypted? boolean | +--rw servers | +--rw server* [address] + | +--rw address -> ../config/address @@ -311,6 +502,7 @@ Supported yang objects and attributes: | | +--rw association-type? enumeration | | +--rw iburst? boolean | | +--rw prefer? boolean ++ | | +--rw oc-sys-ext:key-id? uint16 + | +--ro state + | +--ro address? oc-inet:host | +--ro port? oc-inet:port-number @@ -318,6 +510,7 @@ Supported yang objects and attributes: | +--ro association-type? enumeration | +--ro iburst? boolean | +--ro prefer? boolean ++ | +--rw oc-sys-ext:key-id? uint16 + | +--ro stratum? uint8 | +--ro root-delay? uint32 | +--ro root-dispersion? uint64 @@ -331,18 +524,28 @@ Supported yang objects and attributes: + | +--ro oc-sys-ext:peertype? string + | +--ro oc-sys-ext:now? uint32 + | +--ro oc-sys-ext:reach? uint8 - +``` + +```diff module: sonic-system-ntp - -+ +--rw sonic-system-ntp -+ +--rw NTP -+ | +--rw NTP_LIST* [global_key] -+ | +--rw global_key enumeration -+ | +--rw src_intf? union -+ | +--rw vrf? string -+ +--rw NTP_SERVER -+ +--rw NTP_SERVER_LIST* [server_address] -+ +--rw server_address inet:host ++ +--rw sonic-system-ntp ++ +--rw NTP ++ | +--rw NTP_LIST* [global_key] ++ | +--rw global_key enumeration ++ | +--rw src_intf? union ++ | +--rw vrf? union ++ | +--rw enable-ntp-auth? boolean ++ | +--rw trustedkeys* -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ++ +--rw NTP_AUTHENTICATION_KEY ++ | +--rw NTP_AUTHENTICATION_KEY_LIST* [key_id] ++ | +--rw key_id uint16 ++ | +--rw key_type? enumeration ++ | +--rw key_value? string ++ | +--rw key_encrypted? boolean ++ +--rw NTP_SERVER ++ +--rw NTP_SERVER_LIST* [server_address] ++ +--rw server_address inet:host ++ +--rw key_id? -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ``` @@ -356,9 +559,12 @@ sonic# configure terminal sonic(config)# sonic(config)# ntp - server Configure NTP server - source-interface Configure NTP source interface to pick the source IP, used for the NTP packets - vrf Enable NTP on VRF + authenticate Authenticate time sources + authentication-key Authentication key for trusted time sources + server Configure NTP server + source-interface Configure NTP source interface to pick the source IP, used for the NTP packets + trusted-key Key numbers for trusted time sources + vrf Enable NTP on VRF ``` @@ -451,6 +657,66 @@ sonic(config)# no ntp vrf ``` +##### 3.6.2.1.7 Enable NTP authentication +``` +sonic(config)#ntp + authenticate Authenticate time sources +sonic(config)#ntp authenticate +``` + +##### 3.6.2.1.8 Disable NTP authentication +``` +sonic(config)#no ntp authenticate +``` + +##### 3.6.2.1.9 Configure NTP authentication-key +``` +sonic(config)#ntp authentication-key + <1-65535> Key number + +sonic(config)#ntp authentication-key 1 + md5 MD5 authentication + sha1 SHA1 authentication + sha2-256 SHA2-256 authentication + +sonic(config)#ntp authentication-key 1 md5 + String Authentication key (max 64 chars, keys longer than 20 chars must be hex) + +sonic(config)#ntp authentication-key 1 md5 "ntp client 1" + +``` + +##### 3.6.2.1.10 Delete NTP authentication-key +``` +sonic(config)#no ntp authentication-key 1 +``` + +##### 3.6.2.1.11 Configure NTP trusted-key +``` +sonic(config)#ntp trusted-key + <1-65535> Key number + +sonic(config)#ntp trusted-key 1 +``` + +##### 3.6.2.1.12 Delete NTP trusted-key +``` +sonic(config)no ntp trusted-key 1 +``` + +##### 3.6.2.1.13 Add NTP server with key +``` +sonic(config)#ntp server 99.1.1.1 + key Configure peer authentication key + +sonic(config)#ntp server 99.1.1.1 key 1 +``` + +##### 3.6.2.1.14 Delete NTP server with key +``` +sonic(config)#no ntp server 99.1.1.1 +``` + #### 3.6.2.2 Show ntp ``` sonic# show ntp @@ -497,6 +763,22 @@ NTP vrf: default ##### 3.6.2.2.4 Show running-configuration ``` +sonic(config)#ntp authenticate +sonic(config)#ntp authentication-key 1 md5 "ntp client 1" +sonic(config)#ntp authentication-key 1 md5 ntp_client_2 +sonic(config)#ntp server 99.1.1.1 key 1 +sonic(config)#ntp trusted-keys 1 +sonic(config)#ntp trusted-keys 2 +sonic(config)# do show running-configuration +! +ntp authenticate +ntp authentication-key 1 md5 3b88c0eb8406a9e76722b84baf1d94e5e185eb7f64f8dd46c759719c33557876 encrypted +ntp authentication-key 2 md5 771de7710005c5d6aa5b3313812b721d5d0d4a93fb1548572994464495476c4e encrypted +ntp server 99.1.1.1 key 1 +ntp trusted-keys 1 +ntp trusted-keys 2 +! + sonic(config)# ntp server 10.11.0.1 sonic(config)# ntp server pool.ntp.org sonic(config)# ntp source-interface Ethernet 16 @@ -547,6 +829,8 @@ check /etc/ntp.conf check /var/log/syslog and look for ntp +check "docker exec -it mgmt tail -f /var/log/rest_server/rest_server.log" for rest logs + ifconfig lo ifconfig lo-m @@ -594,6 +878,15 @@ The unit-test for this feature will include: | | Verify that only default and mgmt can be configured as NTP vrf| | | Verify that mgmt cannot be configured as NTP vrf if NTP source interface is configured| | Delete NTP vrf| Verify that NTP vrf is removed from the configDB and ntp service is running in the default instance| +| Configure NTP authentication for NTP server| Verify that NTP authentication-key can be created correctly| +| | Verify that NTP trusted-keys can be added correctly| +| | Verify that NTP authentiate can be enabled and disabled| +| Configure NTP authentication for NTP client| Verify that NTP authentication-key can be created correctly| +| | Verify that NTP trusted-keys can be added correctly| +| | Verify that key number can be added to a NTP server | +| | Verify that NTP authenticate can be enabled and disabled| +| | Verify NTP server is accepted if authentication keys match on NTP server and NTP client| +| | Verify NTP server is rejected if authentication keys mismatch on NTP server and NTP client| | show ntp associations | Verify ntp associations are displayed correctly | | show ntp server | Verify ntp servers are displayed correctly | | show ntp global | Verify ntp global configurations are displayed correctly | From 9a1f162fe8f72fd08dcf9ca2f69111de970256bb Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Sun, 8 Nov 2020 23:49:44 -0800 Subject: [PATCH 5/7] add support to configure multiple NTP source interfaces --- doc/SONiC_OC_NTP_HLD.md | 214 +++++++++++++++++++++++----------------- 1 file changed, 124 insertions(+), 90 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index 9701803241..99e06d88c2 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -3,7 +3,7 @@ NTP Support in Management Framework # High Level Design Document -#### Rev 0.4 +#### Rev 0.5 # Table of Contents * [List of Tables](#list-of-tables) @@ -22,17 +22,18 @@ NTP Support in Management Framework | 0.2 | 06/15/2020 | Bing Sun | Update based on comments | | 0.3 | 09/21/2020 | Bing Sun | Add dhcp behavior | | 0.4 | 11/02/2020 | Bing Sun | Add support for NTP authentication| +| 0.5 | 11/08/2020 | Bing Sun | Allow configuration of multiple NTP source interfaces| # About this Manual -This document introduces the support of NTP configuration using management framework. It also describes the corresponding backend ntp configuration and service restart upon configuration changes discussed here. +This document introduces the support of NTP configuration using management framework. It also describes the corresponding backend NTP configuration changes(/etc/ntp.conf and /etc/ntp.keys) as well as ntp service restart upon configuration changes. # Scope -This document covers NTP "configuration" and "show" commands based on the OpenConfig YANG model, as well as the backend mechanism required to support each command. -NTP unit tests are also included. - +This document covers NTP "configuration" and "show" commands based on the OpenConfig YANG model. In addition, it decribes the backend mechanism required to support each command. +A summary of NTP unit test cases is presented at the end. + # Definition/Abbreviation ### Table 1: Abbreviations @@ -47,11 +48,17 @@ NTP unit tests are also included. NTP stands for Network Time Protocol. It is used to synchronize the time of a computer or server to another server or reference time source. -SONiC click CLI provides commands to add and delete the IP address of a remote NTP server. Multiple NTP servers can be configured, and both IPv4 and IPv6 are supported. SONiC click CLI also provides the show command (output of "ntpq -pn"). - -This feature provides users the same capabilities via Management CLI, REST and gNMI using OpenConfig YANG models. -In addition, it provides users to configure NTP source interface and NTP vrf. For this release, only "mgmt" and "default" vrf can be configured as NTP vrf. - +Today, SONiC click CLI provides commands to +- add and delete remote NTP servers with IPv4 or IPv6 addresses +- display NTP synchronization status with show command (output of "ntpq -pn") + +This feature provides the the same above mentioned capabilities via Management CLI, REST and gNMI using OpenConfig YANG models. +In addition, it provides the following configuration, +- add remote NTP server with hostname +- NTP source interfaces +- NTP vrf +- NTP authentication + ## 1.1 Requirements ### 1.1.1 Front end configuration and get capabilities @@ -61,8 +68,8 @@ In addition, it provides users to configure NTP source interface and NTP vrf. Fo ntp server 99.1.1.1 ntp server pool.ntp.org ``` -Add/delete NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). -The NTP server can be IPv4 address, IPv6 address , or a ntp pool name. +Add/delete NTP server information in the Redis ConfigDB and in /etc/ntp.conf. +The NTP server can be IPv4 address, IPv6 address , or hostname. Mutliple NTP servers can be configured. #### 1.1.1.2 add/delete NTP source interface @@ -83,14 +90,14 @@ ntp source-interface Management 0 ``` -Add/delete the global NTP source interface in the Redis ConfigDB and in the ntp.conf file. The ip address of this interface will be used by ntpd as source ip for all NTP packets. -Only one NTP source interface can be configured. -Following interfaces can be used as NTP source interface, +Add/delete the global NTP source interface in the Redis ConfigDB and in /etc/ntp.conf. The ip address of this interface will be used by ntpd as source ip for all NTP packets. +Multiple NTP source interfaces can be configured. +Following interface types can be used as NTP source interface, - Ethernet interface - PortChannel - Vlan interface - Loopback interfacee -- eth0 +- eth0(management interface) #### 1.1.1.3 add/delete VRF name ``` @@ -109,20 +116,20 @@ For this release, only Management VRF and default instance are supported. show ntp association ``` -This displays the output of "ntpq -np" command. +This command displays the output of "ntpq -np" command. #### 1.1.1.5 Overall Behavior related to NTP source interface and NTP vrf ##### When mgmt VRF is configured a.if no ntp vrf is configured, ntp service starts in mgmt VRF context by default b.if "mgmt" is configured as NTP vrf, ntp service starts in mgmt VRF context -c.if "default" is configured as NTP vrf, ntp service starts in default vrf context +c.if "default" is again configured as NTP vrf, ntp service starts in default vrf context ##### When mgmt VRF is not configured ntp service always starts in default vrf context ##### NTP source interface related -a.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets -b.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured +a.if a NTP source interface has IP address configured, the IP address will be used as source ip for all NTP packets exchanged with the respective NTP servers/clients +b.if a NTP source interface has no IP address configured, it is not being considered as an NTP source interface #### 1.1.1.6 NTP authentication configuration NTP authentication enables an NTP client or peer to authenticate time received from their servers and peers. @@ -132,8 +139,8 @@ NTP authentication enables an NTP client or peer to authenticate time received f ntp authenticate ``` -This command enable the NTP authentication feature - +NTP server and NTP client use this command to enable the NTP authentication feature. + ##### ntp authentication-key ``` ntp authentication-key 1 md5 "ntp client 1" @@ -141,10 +148,10 @@ ntp authentication-key 1 md5 "ntp client 1" ntp authentication-key 2 md5 ntp_client2 ``` -This command defines an authentication key with key number, authentication type and password. +NTP client uses this command to define an authentication key with key number, authentication type and password. The key number is from 1 to 65535. The authentication type supported is MD5, SHA1 and SHA2-256. -The password is configured with plaintext the first time. In runnning-configuration, it is encrypted with the flag "encrypted" at the end. Authentication key can then be configured with encrypted format and "encrypted" flag. +The password is configured with plaintext the first time. In runnning-configuration, it is encrypted and is indicated with "encrypted" at the end. Authentication key can then be configured with the encrypted format and "encrypted" flag. ##### ntp trusted key @@ -154,15 +161,15 @@ ntp trusted-key 1 ntp trusted-key 2 ``` -This command adds the list of key numbers that the NTP server must provide in its NTP packets in order for the NTP clients -to synchronize to it. +NTP server uses this command to add a list of key numbers that the NTP server must provide in its NTP packets in order for the NTP clients to synchronize to it. +NTP client must configure a list with this command if it desires to authenticate the NTP server with any of the key number. ##### ntp server key ``` ntp server 99.1.1.1 key 1 ``` -This command configures the key expected from a specific NTP server. +NTP client uses this command to configure the key expected from a specific NTP server. ### 1.1.2 Backend mechanisms to support configuration and get @@ -191,9 +198,7 @@ This creates or deletes a NTP server entry in the Redis ConfigDB. ``` A change in the NTP_SERVER entry triggers hostcfgd to start the NTP configuration script, which in turn writes each NTP server to the ntp.conf and then restart the ntp service. - -SONiC click CLI only supports IP address for NTP server. It can be extended to ntp pool name as well. - + #### 1.1.2.2 add/delete NTP source @@ -209,7 +214,6 @@ This creates or deletes a global NTP source interface entry in the Redis ConfigD ``` A change in this entry triggers hostcfgd to start the NTP configuration script, which in turn writes the ntp source interface to the ntp.conf and then restart the ntp service. -Only one global NTP source entry is allowed. SONiC click CLI can be extended to include this configuration. @@ -238,7 +242,7 @@ Transformer function issues "ntpq -pn" command, parses the response and maps the #### 1.1.2.5 NTP authentication -##### 1.1.2.5.1 enable or disable ntp authenticate +##### 1.1.2.5.1 Enable or disable ntp authenticate When "authenticate" is enabled, "enable-ntp-auth" field is set to "true" in the NTP global entry, @@ -277,7 +281,7 @@ When an authentication key is configured with a key number, authentication type } ``` -If "authenticate" is enabled, the file /etc/ntp.keys is populated with the configured authentication keys. The password in this file is in the plaintext format. +If "authenticate" is enabled, the file /etc/ntp.keys is populated with the configured authentication keys. The password in this file is in the plaintext format. Only root user can read /etc/ntp.keys. When an ntp authentication key is removed, the ConfigDb and /etc/ntp.keys will be updated accordingly. @@ -319,45 +323,64 @@ The file /etc/ntp.conf will be generated with the same key number for that NTP s server 99.1.1.1 iburst key 1 ``` -##### 1.1.2.5.5 Sample ntp.conf and ntp.keys -###### Relevant entries in ntp.conf for NTP server +##### 1.1.2.5.5 Sample NTP authentication CLI commands on NTP server and NTP client ``` -keys /etc/ntp.keys - -server 10.14.8.140 iburst +NTP master ------------------------- SONiC switch ----------------------------------server +Mgmt. IP: 100.94.121.15 mgmt. IP: 100.94.122.16 + Loopback100: 2001:aa:aa::1 -# By default, exchange time with everybody, but don't allow configuration. -restrict -4 default kod notrap nomodify nopeer noquery -restrict -6 default kod notrap nomodify nopeer noquery +``` -interface listen Loopback100 -interface listen 127.0.0.1 +Here the SONiC switch is a NTP client to the NTP master. It is also a NTP server to the downstream servers. +As a NTP client, SONiC switch uses NTP authentication to validate its NTP server. +As a NTP server, the downstream servers are the NTP client. It is up to the NTP client (server) whether NTP authentication is desired with its NTP server (SONiC switch). +SONiC switch can server as a NTP client and a NTP server simultaneously, with or without NTP authentication with either a remote NTP server or NTP client. +The NTP master reaches SONiC switch via its management interface. The downstream servers reach the SONiC switch via its front panel ports. + +###### Relevant CLI commmands on SONiC switch as NTP server -trustedkey 1 2 ``` - -###### Relevant entries in ntp.keys on NTP server +sonic(config)# ntp source-interface Loopback 100 +sonic(config)#ip vrf mgmt ``` -1 MD5 ntp client 1 -2 MD5 ntp_client_2 + +###### Relevant CLI commands on SONiC switch as NTP client ``` - -###### Relevant entries in ntp.conf on NTP client +sonic(config)#ntp authenticate +sonic(config)#ntp authentication-key 1 MD5 force +sonic(config)#ntp trusted-key 1 +sonic(config)#ntp server 100.94.121.15 key 1 +sonic(config)# ntp source-interface Management 0 ``` -keys /etc/ntp.keys - -server 99.1.1.1 iburst key 1 - -interface listen Vlan100 - -trustedkey 1 + +###### Relevant CLI commands on the server as NTP client without NTP authentication +``` +sonic(config)#ntp server 2001:aa:aa::1 +sonic(config)# ntp source-interface Vlan 100 ``` -###### Relevant entries in ntp.keys on NTP client +###### Relevant CLI commands for the server and SONiC switch with NTP authentication ``` -1 MD5 ntp client 1 +On the SONiC switch + +sonic(config)#ntp authenticate +sonic(config)#ntp authentication-key 2 MD5 jungle +sonic(config)#ntp trusted-key 2 +sonic(config)# ntp source-interface Loopback 100 +sonic(config)#ip vrf mgmt ``` + +``` +On the server + +sonic(config)#ntp authenticate +sonic(config)#ntp authentication-key 2 MD5 jungle +sonic(config)#ntp trusted-key 2 +sonic(config)#ntp server 2001:aa:aa::1 key 2 +sonic(config)# ntp source-interface Vlan 100 +``` + ### 1.1.3 Functional Requirements Provide management framework support to @@ -378,9 +401,9 @@ Details described in Section 3. - broadcast mode ### 1.1.6 Scalability Requirements -Only 1 source interface, assuming the remote NTP peer has route to this source interface +Interface listening will not be enabled on all L3 interfaces. User can configure NTP source interfaces which are only a few. Ntpd runs in one VRF context, default vrf or mgmt vrf. -Multiple ntp servers supported. +Multiple ntp servers supported, also only a few. ### 1.1.7 Warm Boot Requirements NA @@ -420,10 +443,10 @@ SONiC click CLI enhancement if possible. If the management IP address is acquired via DHCP, and if the NTP server option specifies the NTP server, /etc/dhcp/dhclient-exit-hooks.d/ntp script will generate the file /var/lib/ntp/ntp.conf.dhcp. This file is a copy of the default /etc/ntp.conf with a modified server list from the DHCP server. NTP daemon only uses one of the 2 files, and /var/lib/ntp/ntp.conf.dhcp takes precedence over the default /etc/ntp.conf. It is the existing behavior and is out of the scope of this HLD. -NTP source-interface and NTP vrf discussed in the HLD are only guaranteed to take effect on the static configured NTP servers. -For acquired NTP servers from DHCP server, NTP source-interface and NTP vrf will only take effect if /var/lib/ntp/ntp.conf.dhcp is generated based on the /etc/ntp.conf with user configured NTP source-interface. +NTP source-interface, NTP vrf and NTP authentication discussed in the HLD are only guaranteed to take effect on the static configured NTP servers. +For acquired NTP servers from DHCP server, NTP source-interface, NTP vrf and NTP authentication will only take effect if /var/lib/ntp/ntp.conf.dhcp is generated based on the /etc/ntp.conf with user configured NTP source-interface and NTP authentication. -Applying the configured NTP source-interface and NTP vrf to acquired NTP servers from the DHCP server is not a requirement for this release. +Applying the configured NTP source-interface, NTP vrf and NTP authentication to acquired NTP servers from the DHCP server is not a requirement for this release. # 3 Design @@ -471,14 +494,16 @@ Supported yang objects and attributes: | +--rw config | | +--rw enabled? boolean + | | +--rw enable-ntp-auth? boolean -+ | | +--rw oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref ++ | | +--rw oc-sys-ext:ntp-source-interface* oc-if:base-interface-ref + | | +--rw oc-sys-ext:vrf? string ++ | | +--rw oc-sys-ext:trustedkey* uint16 | +--ro state | | +--ro enabled? boolean + | | +--ro enable-ntp-auth? boolean | | +--ro auth-mismatch? oc-yang:counter64 + | | +--ro oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--ro oc-sys-ext:vrf? string ++ | | +--rw oc-sys-ext:trustedkey* uint16 + | +--rw ntp-keys + | | +--rw ntp-key* [key-id] + | | +--rw key-id -> ../config/key-id @@ -510,12 +535,12 @@ Supported yang objects and attributes: | +--ro association-type? enumeration | +--ro iburst? boolean | +--ro prefer? boolean -+ | +--rw oc-sys-ext:key-id? uint16 + | +--ro stratum? uint8 | +--ro root-delay? uint32 | +--ro root-dispersion? uint64 | +--ro offset? uint64 + | +--ro poll-interval? uint32 ++ | +--rw oc-sys-ext:key-id? uint16 + | +--ro oc-sys-ext:peerdelay? decimal64 + | +--ro oc-sys-ext:peeroffset? decimal64 + | +--ro oc-sys-ext:peerjitter? decimal64 @@ -528,25 +553,23 @@ Supported yang objects and attributes: ```diff module: sonic-system-ntp -+ +--rw sonic-system-ntp + +--rw NTP + | +--rw NTP_LIST* [global_key] -+ | +--rw global_key enumeration -+ | +--rw src_intf? union -+ | +--rw vrf? union -+ | +--rw enable-ntp-auth? boolean ++ | +--rw global_key enumeration ++ | +--rw src_intf* union ++ | +--rw vrf? union ++ | +--rw auth_enabled? boolean + | +--rw trustedkeys* -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id + +--rw NTP_AUTHENTICATION_KEY + | +--rw NTP_AUTHENTICATION_KEY_LIST* [key_id] + | +--rw key_id uint16 -+ | +--rw key_type? enumeration -+ | +--rw key_value? string ++ | +--rw key_type enumeration ++ | +--rw key_value string + | +--rw key_encrypted? boolean + +--rw NTP_SERVER + +--rw NTP_SERVER_LIST* [server_address] + +--rw server_address inet:host + +--rw key_id? -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id - ``` ### 3.6.2 CLI @@ -631,10 +654,14 @@ sonic(config)# ##### 3.6.2.1.4 Delete NTP source interface ``` -sonic(config)# no ntp source-interface +sonic(config)# no ntp source-interface PortChannel 100 ``` - + +``` +sonic(config)# no ntp source-interface +``` + ##### 3.6.2.1.5 Configure NTP vrf ``` @@ -755,8 +782,10 @@ sonic# show ntp global ---------------------------------------------- NTP Global Configuration ---------------------------------------------- -NTP source-interface: Ethernet24 -NTP vrf: default +NTP source-interface: eth0 + Loopback100 + +NTP vrf: mgmt ``` @@ -779,22 +808,25 @@ ntp trusted-keys 1 ntp trusted-keys 2 ! -sonic(config)# ntp server 10.11.0.1 -sonic(config)# ntp server pool.ntp.org -sonic(config)# ntp source-interface Ethernet 16 -sonic(config)# do show running-configuration +sonic(config)#ntp server 10.11.0.1 +sonic(config)#ntp server pool.ntp.org +sonic(config)#ntp source-interface Management 0 +sonic(config)#ntp source-interface Loopback 100 +sonic(config)#do show running-configuration ! ntp server 10.11.0.1 ntp server pool.ntp.org -ntp source-interface Ethernet 16 +ntp source-interface Management 0 +ntp source-interface Loopback 100 ! -sonic(config)# no ntp source-interface +sonic(config)# no ntp source-interface Loopback 100 sonic(config)# ntp vrf mgmt sonic(config)# do show running-configuration ! ntp server 10.11.0.1 ntp server pool.ntp.org +ntp source-interface Management 0 ntp vrf mgmt ! @@ -803,6 +835,7 @@ sonic(config)# do show running-configuration ! ntp server 10.11.0.1 ntp server pool.ntp.org +ntp source-interface Management 0 ntp vrf default ! @@ -837,6 +870,8 @@ ifconfig lo-m show mgmt-vrf +ntpq -pn + ``` #### 3.6.2.4 IS-CLI Compliance @@ -869,22 +904,21 @@ The unit-test for this feature will include: | Test Name | Test Description | | :-------- | :----- | -| Configure NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peers | -| Delete NTP server | Verify NTP server is deleted from the configDB and reflected in the NTP peers | +| Configure NTP server | Verify NTP servers are installed correctly in the configDB and reflected in the NTP peer status | +| Delete NTP server | Verify NTP server is deleted from the configDB and reflected in the NTP peer status | | Configure NTP source interface| Verify NTP source interface is installed correctly in the configDB, NTP packets are transmitted and received over this source | -| | Verify that NTP source interface cannot be configured if NTP vrf is mgmt| +| | Verify that multiple NTP source interfaces can be configured, for both default and mgmt vrf cases| | Delete NTP source interface| Verify that NTP source interface is removed from the configDB, NTP packets are transmitted and received over the default interface| | Configure NTP vrf| Verify that NTP vrf is installed correctly in the configDB and ntp service is running in the specified VRF| | | Verify that only default and mgmt can be configured as NTP vrf| -| | Verify that mgmt cannot be configured as NTP vrf if NTP source interface is configured| | Delete NTP vrf| Verify that NTP vrf is removed from the configDB and ntp service is running in the default instance| | Configure NTP authentication for NTP server| Verify that NTP authentication-key can be created correctly| | | Verify that NTP trusted-keys can be added correctly| -| | Verify that NTP authentiate can be enabled and disabled| +| | Verify that NTP authentication can be enabled and disabled| | Configure NTP authentication for NTP client| Verify that NTP authentication-key can be created correctly| | | Verify that NTP trusted-keys can be added correctly| | | Verify that key number can be added to a NTP server | -| | Verify that NTP authenticate can be enabled and disabled| +| | Verify that NTP authentication can be enabled and disabled| | | Verify NTP server is accepted if authentication keys match on NTP server and NTP client| | | Verify NTP server is rejected if authentication keys mismatch on NTP server and NTP client| | show ntp associations | Verify ntp associations are displayed correctly | From 08b65838c06d3cfb7ffa12a4154f22a827a7a5f2 Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Mon, 7 Dec 2020 21:32:10 -0800 Subject: [PATCH 6/7] modify Yang model and add tables in 3.2 --- doc/SONiC_OC_NTP_HLD.md | 84 +++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 11 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index 99e06d88c2..d94b101c4b 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -23,6 +23,8 @@ NTP Support in Management Framework | 0.3 | 09/21/2020 | Bing Sun | Add dhcp behavior | | 0.4 | 11/02/2020 | Bing Sun | Add support for NTP authentication| | 0.5 | 11/08/2020 | Bing Sun | Allow configuration of multiple NTP source interfaces| +| 0.6 | 12/07/2020 | Bing Sun | Updated section 3.2 configDB changes | +| | | | Minor change for Yang models | # About this Manual @@ -459,6 +461,66 @@ Enhancing the management framework backend code and transformer methods to add s ### 3.2.1 CONFIG DB This feature will allow users to make NTP configuration changes to CONFIG DB, and get NTP configurations. +''' +NTP server + + "NTP_SERVER": { + "2.2.2.2": { + "key_id": "1" + }, + "3.3.3.3": { + "key_id": "2" + }, + "4.4.4.4": { + "key_id": "3" + }, + "10.14.8.140": {} + } +''' + +''' +NTP authentication key + + "NTP_AUTHENTICATION_KEY": { + "1": { + "encrypted": "true", + "type": "MD5", + "value": "U2FsdGVkX18LP3kIv47lRKCboUop/+0YyacH2UT2WJ0=" + }, + "2": { + "encrypted": "true", + "type": "SHA1", + "value": "U2FsdGVkX1+DU7geMDXVvCOJjZQyP1zTT4vRbHFqsZo=" + }, + "3": { + "encrypted": "true", + "type": "SHA2_256", + "value": "U2FsdGVkX19yHcvrGFDKJb80FRY+cnmO1+yv6SGkao8=" + } + } +''' + +''' +NTP global configuration + + "NTP": { + "global": { + "auth_enabled": "true", + "src_intf": [ + "eth0", + "Loopback99" + ], + "trusted_key": [ + "1", + "2", + "3" + ], + "vrf": "mgmt" + } + } +''' + + ### 3.2.2 APP DB ### 3.2.3 STATE DB @@ -496,14 +558,14 @@ Supported yang objects and attributes: + | | +--rw enable-ntp-auth? boolean + | | +--rw oc-sys-ext:ntp-source-interface* oc-if:base-interface-ref + | | +--rw oc-sys-ext:vrf? string -+ | | +--rw oc-sys-ext:trustedkey* uint16 ++ | | +--rw oc-sys-ext:trusted-key* uint16 | +--ro state | | +--ro enabled? boolean + | | +--ro enable-ntp-auth? boolean | | +--ro auth-mismatch? oc-yang:counter64 + | | +--ro oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--ro oc-sys-ext:vrf? string -+ | | +--rw oc-sys-ext:trustedkey* uint16 ++ | | +--rw oc-sys-ext:trusted-key* uint16 + | +--rw ntp-keys + | | +--rw ntp-key* [key-id] + | | +--rw key-id -> ../config/key-id @@ -511,12 +573,12 @@ Supported yang objects and attributes: + | | | +--rw key-id? uint16 + | | | +--rw key-type? identityref + | | | +--rw key-value? string -+ | | | +--rw oc-sys-ext:key-encrypted? boolean ++ | | | +--rw oc-sys-ext:encrypted? boolean + | | +--ro state + | | +--ro key-id? uint16 + | | +--ro key-type? identityref + | | +--ro key-value? string -+ | | +--rw oc-sys-ext:key-encrypted? boolean ++ | | +--rw oc-sys-ext:encrypted? boolean | +--rw servers | +--rw server* [address] + | +--rw address -> ../config/address @@ -559,17 +621,17 @@ module: sonic-system-ntp + | +--rw src_intf* union + | +--rw vrf? union + | +--rw auth_enabled? boolean -+ | +--rw trustedkeys* -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ++ | +--rw trusted_keys* -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/id + +--rw NTP_AUTHENTICATION_KEY -+ | +--rw NTP_AUTHENTICATION_KEY_LIST* [key_id] -+ | +--rw key_id uint16 -+ | +--rw key_type enumeration -+ | +--rw key_value string -+ | +--rw key_encrypted? boolean ++ | +--rw NTP_AUTHENTICATION_KEY_LIST* [id] ++ | +--rw id uint16 ++ | +--rw type enumeration ++ | +--rw value string ++ | +--rw encrypted? boolean + +--rw NTP_SERVER + +--rw NTP_SERVER_LIST* [server_address] + +--rw server_address inet:host -+ +--rw key_id? -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ++ +--rw key_id? -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/id ``` ### 3.6.2 CLI From a02c020447c9b9a081cd887b7ab36c3e86d401ab Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Mon, 7 Dec 2020 21:41:01 -0800 Subject: [PATCH 7/7] fix format --- doc/SONiC_OC_NTP_HLD.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index d94b101c4b..b29cb8d564 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -461,24 +461,24 @@ Enhancing the management framework backend code and transformer methods to add s ### 3.2.1 CONFIG DB This feature will allow users to make NTP configuration changes to CONFIG DB, and get NTP configurations. -''' -NTP server +``` +NTP server - "NTP_SERVER": { - "2.2.2.2": { - "key_id": "1" - }, - "3.3.3.3": { - "key_id": "2" - }, - "4.4.4.4": { - "key_id": "3" - }, - "10.14.8.140": {} - } -''' + "NTP_SERVER": { + "2.2.2.2": { + "key_id": "1" + }, + "3.3.3.3": { + "key_id": "2" + }, + "4.4.4.4": { + "key_id": "3" + }, + "10.14.8.140": {} + } +``` -''' +``` NTP authentication key "NTP_AUTHENTICATION_KEY": { @@ -498,9 +498,9 @@ NTP authentication key "value": "U2FsdGVkX19yHcvrGFDKJb80FRY+cnmO1+yv6SGkao8=" } } -''' +``` -''' +``` NTP global configuration "NTP": { @@ -518,7 +518,7 @@ NTP global configuration "vrf": "mgmt" } } -''' +``` ### 3.2.2 APP DB