Update documentation for ntpd
Sven Mäder committed
Feb 22, 2018 at 00:47 UTC
0aae5498951272447f0bc68aa45eaefb394af8fd
3 files changed
+57
-7
conf.d/python.d.conf
+1
@@ -56,6 +56,7 @@ go_expvar: no
56
# nginx: yes
57
# nginx_plus: yes
58
# nsd: yes
59
+# ntpd: yes
60
61
# nginx_log has been replaced by web_log
62
nginx_log: no
python.d/README.md
+7
-4
@@ -1543,10 +1543,10 @@ Configuration is not needed.
1543
1544
# ntpd
1545
1546
-Module monitors the system variables of the local `ntpd` daemon (optional incl. variables of the polled peers) using the NTP Control Message Protocol via UDP socket, similar to `ntpq`.
1546
+Module monitors the system variables of the local `ntpd` daemon (optional incl. variables of the polled peers) using the NTP Control Message Protocol via UDP socket, similar to `ntpq`, the [standard NTP query program](http://doc.ntp.org/current-stable/ntpq.html).
1547
1548
**Requirements:**
1549
- * Version of `ntpd` must be 2.0+
1549
+ * Version: `NTPv4`
1550
* Local interrogation allowed in `/etc/ntp.conf` (default):
1551
1552
```
@@ -1591,12 +1591,15 @@ update_every: 10
1591
host: 'localhost'
1592
port: '123'
1593
show_peers: yes
1594
+# hide peers with source address in ranges 127.0.0.0/8 and 192.168.0.0/16
1595
peer_filter: '(127\..*)|(192\.168\..*)'
1596
+# check for new/changed peers every 60 updates
1597
+peer_rescan: 60
1598
```
1599
1600
Sample (multiple jobs):
1601
1599
-Note: `ntp.conf` on host `otherhost` must be configured to allow queries from our local host by including a line like `restrict <IP> nomodify notrap nopeer`.
1602
+Note: `ntp.conf` on the host `otherhost` must be configured to allow queries from our local host by including a line like `restrict <IP> nomodify notrap nopeer`.
1603
1604
```yaml
1605
local:
@@ -1606,7 +1609,7 @@ otherhost:
1609
host: 'otherhost'
1610
```
1611
1609
-If no configuration is given, module will attempt to connect to `ntpd` on `::1:123` or `127.0.0.1:123` and show charts for the systemvars. Use `show_peers: yes` to also show the charts for configured peers. Local peers (127.*) are hidden by default, use `peer_filter: ''` to show all.
1612
+If no configuration is given, module will attempt to connect to `ntpd` on `::1:123` or `127.0.0.1:123` and show charts for the systemvars. Use `show_peers: yes` to also show the charts for configured peers. Local peers in the range `127.0.0.0/8` are hidden by default, use `peer_filter: ''` to show all peers.
1613
1614
---
1615
web/dashboard_info.js
+49
-3
@@ -358,7 +358,7 @@ netdataDashboard.menu = {
358
'ntpd': {
359
title: 'ntpd',
360
icon: '<i class="fas fa-clock"></i>',
361
- info: 'Provides statistics for the internal variables of the Network Time Protocol daemon <b><a href="http://www.ntp.org/">ntpd</a></b> including the configured peers.'
361
+ info: 'Provides statistics for the internal variables of the Network Time Protocol daemon <b><a href="http://www.ntp.org/">ntpd</a></b> and optional including the configured peers (if enabled in the module configuration). The module presents the performance metrics as shown by <b><a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a></b> (the standard NTP query program) using NTP mode 6 UDP packets to communicate with the NTP server.'
362
}
363
};
364
@@ -513,12 +513,12 @@ netdataDashboard.submenu = {
513
514
'ntpd.system': {
515
title: 'system',
516
- info: 'Statistics of the internal system variables as shown by <a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a> (standard NTP query program).'
516
+ info: 'Statistics of the system variables as shown by the readlist billboard <code>ntpq -c rl</code>. System variables are assigned an association ID of zero and can also be shown in the readvar billboard <code>ntpq -c "rv 0"</code>. These variables are used in the <a href="http://doc.ntp.org/current-stable/discipline.html">Clock Discipline Algorithm</a>, to calculate the lowest and most stable offset.'
517
},
518
519
'ntpd.peers': {
520
title: 'peers',
521
- info: 'Statistics of the peer variables for each peer as shown by <a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a> (standard NTP query program).'
521
+ info: 'Statistics of the peer variables for each peer configured in <code>/etc/ntp.conf</code> as shown by the readvar billboard <code>ntpq -c "rv <association>"</code>, while each peer is assigned a nonzero association ID as shown by <code>ntpq -c "apeers"</code>. The module periodically scans for new/changed peers (default: every 60s). <b>ntpd</b> selects the best possible peer from the available peers to synchronize the clock. A minimum of at least 3 peers is required to properly identify the best possible peer.'
522
}
523
};
524
@@ -1962,6 +1962,52 @@ netdataDashboard.context = {
1962
'rabbitmq.disk_space': {
1963
info: 'Total amount of disk space consumed by the message store(s). See <code><a href="https://www.rabbitmq.com/production-checklist.html#resource-limits-disk-space" target=_"blank">Disk Space Limits</a></code> for further details.',
1964
colors: NETDATA.colors[3]
1965
+ },
1966
+
1967
+ // ------------------------------------------------------------------------
1968
+ // ntpd
1969
+
1970
+ 'ntpd.sys_offset': {
1971
+ info: 'For hosts without any time critical services an offset of < 100 ms should be acceptable even with high network latencies. For hosts with time critical services an offset of about 0.01 ms or less can be achieved by using peers with low delays and configuring optimal <b>poll exponent</b> values.',
1972
+ colors: NETDATA.colors[4]
1973
+ },
1974
+
1975
+ 'ntpd.sys_jitter': {
1976
+ info: 'The jitter statistics are exponentially-weighted RMS averages. The system jitter is defined in the NTPv4 specification; the clock jitter statistic is computed by the clock discipline module.'
1977
+ },
1978
+
1979
+ 'ntpd.sys_frequency': {
1980
+ info: 'The frequency offset is shown in ppm (parts per million) relative to the frequency of the system. The frequency correction needed for the clock can vary significantly between boots and also due to external influences like temperature or radiation.',
1981
+ colors: NETDATA.colors[2],
1982
+ height: 0.6
1983
+ },
1984
+
1985
+ 'ntpd.sys_wander': {
1986
+ info: 'The wander statistics are exponentially-weighted RMS averages.',
1987
+ colors: NETDATA.colors[3],
1988
+ height: 0.6
1989
+ },
1990
+
1991
+ 'ntpd.sys_rootdelay': {
1992
+ info: 'The rootdelay is the roundtrip delay to the primary reference clock, similar to the delay shown by the <code>ping</code> command. A lower delay should result in a (possibly exponentially) lower clock offset.',
1993
+ colors: NETDATA.colors[1]
1994
+ },
1995
+
1996
+ 'ntpd.sys_stratum': {
1997
+ info: 'The distance in "hops" to the primary reference clock',
1998
+ colors: NETDATA.colors[5],
1999
+ height: 0.3
2000
+ },
2001
+
2002
+ 'ntpd.sys_tc': {
2003
+ info: 'Time constants and poll intervals are expressed as exponents of 2. The default poll exponent of 6 corresponds to a poll interval of 64 s. For typical Internet paths, the optimum poll interval is about 64 s. For fast LANs with modern computers, a poll exponent of 4 (16 s) is appropriate. The <a href="http://doc.ntp.org/current-stable/poll.html">poll process</a> sends NTP packets at intervals determined by the clock discipline algorithm.',
2004
+ height: 0.5
2005
+ },
2006
+
2007
+ 'ntpd.sys_precision': {
2008
+ colors: NETDATA.colors[6],
2009
+ height: 0.2
2010
}
2011
+
2012
// ------------------------------------------------------------------------
2013
};