From 438e39d2fe1b1d952c12e918d1c4db3ee8301188 Mon Sep 17 00:00:00 2001
From: Ahmed Karic <ahmkar@addiva.se>
Date: Tue, 22 Oct 2024 08:58:19 +0200
Subject: [PATCH] doc: update system.md with ntp information

Fixes #733
---
 doc/networking.md |  6 ++++
 doc/system.md     | 78 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/doc/networking.md b/doc/networking.md
index 4e04aa833..f6ac94262 100644
--- a/doc/networking.md
+++ b/doc/networking.md
@@ -610,6 +610,12 @@ possible to set the value of as well.
 **Default:** `router`, `dns`, `domain`, `broadcast`, `ntpsrv`, `search`,
              `address`, `staticroutes`, `msstaticroutes`
 
+When configuring a DHCP client, ensure that the NTP client is enabled
+for the `ntpsrv` DHCP option to be processed correctly. If the NTP
+client is not enabled, any NTP servers provided by the DHCP server will
+be ignored. For details on how to enable the NTP client, see the 
+[NTP Client Configuration](system.md#ntp-client-configuration) section.
+
 > **Note:** DHCP address method is only available for *LAN* interfaces
 > (Ethernet, virtual Ethernet (veth), bridge, link aggregates, etc.)
 
diff --git a/doc/system.md b/doc/system.md
index 5f268e0f8..a1a642109 100644
--- a/doc/system.md
+++ b/doc/system.md
@@ -145,7 +145,7 @@ is committed by issuing the `leave` command.
 admin@host:/config/> edit system
 admin@host:/config/system/> set hostname example
 admin@host:/config/system/> leave
-admin@example:/> 
+admin@host:/> 
 ```
 
 The hostname is advertised over mDNS-SD in the `.local` domain.  If
@@ -201,6 +201,82 @@ admin@host:/>
 > and then re-enter configure context to use your editor of choice.
 
 
+## NTP Client Configuration
+
+Below is an example configuration for enabling NTP 
+with a specific server and the `iburst` option for faster initial 
+synchronization.
+
+```
+admin@host:/> configure
+admin@host:/config/> set system ntp enabled
+admin@host:/config/> set system ntp server ntp-pool
+admin@host:/config/> set system ntp server ntp-pool udp address pool.ntp.org
+admin@host:/config/> set system ntp server ntp-pool iburst
+admin@host:/config/> set system ntp server ntp-pool prefer
+```
+
+This configuration enables the NTP client and sets the NTP server to 
+`pool.ntp.org` with the `iburst` and `prefer` options. The `iburst` 
+option ensures faster initial synchronization, and the `prefer` option 
+designates this server as preferred.
+
+* `prefer false`: The NTP client will choose the best available source
+based on several factors, such as network delay, stratum, and other 
+metrics (default config).
+* `prefer true`: The NTP client will try to use the preferred server 
+as the primary source unless it becomes unreachable or unusable.
+
+### Show NTP Status
+
+To check the status of NTP synchronization, use the following command:
+
+```
+admin@host:/> show ntp
+Reference ID    : C0248F86 (192.36.143.134)
+Stratum         : 2
+Ref time (UTC)  : Mon Oct 21 10:06:45 2024
+System time     : 0.000000001 seconds slow of NTP time
+Last offset     : -3845.151367188 seconds
+RMS offset      : 3845.151367188 seconds
+Frequency       : 4.599 ppm slow
+Residual freq   : +1293.526 ppm
+Skew            : 12.403 ppm
+Root delay      : 1.024467230 seconds
+Root dispersion : 0.273462683 seconds
+Update interval : 0.0 seconds
+Leap status     : Normal
+admin@host:/>
+```
+
+This output provides detailed information about the NTP status, including 
+reference ID, stratum, time offsets, frequency, and root delay.
+
+### Show NTP Sources
+
+To view the sources being used by the NTP client, run:
+
+```
+admin@host:/> show ntp sources 
+
+  .-- Source mode  '^' = server, '=' = peer, '#' = local clock.
+ / .- Source state '*' = current best, '+' = combined, '-' = not combined,
+| /             'x' = may be in error, '~' = too variable, '?' = unusable.
+||                                                 .- xxxx [ yyyy ] +/- zzzz
+||      Reachability register (octal) -.           |  xxxx = adjusted offset,
+||      Log2(Polling interval) --.      |          |  yyyy = measured offset,
+||                                \     |          |  zzzz = estimated error.
+||                                 |    |           \
+MS Name/IP address         Stratum Poll Reach LastRx Last sample               
+===============================================================================
+^* 192.36.143.134                1   6   177     9   +278ms[ -3845s] +/-  514ms
+admin@host:/>
+```
+
+> The system uses `chronyd` for Network Time Protocol (NTP)
+> synchronization. The output shown here is best explained in the
+> [Chrony documentation](https://chrony-project.org/doc/4.6.1/chronyc.html).
+
 [1]: https://www.rfc-editor.org/rfc/rfc7317
 [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/infix-system%402024-02-29.yang
 [3]: https://www.rfc-editor.org/rfc/rfc8341