Skip to content

Commit 9a2aa16

Browse files
troglobittroglobit
committed
doc: add NTP server documentation
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
1 parent 86f702b commit 9a2aa16

File tree

2 files changed

+161
-0
lines changed

2 files changed

+161
-0
lines changed

‎doc/ntp.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# NTP Server
2+
3+
The NTP (Network Time Protocol) server provides accurate time synchronization
4+
for network clients. It supports both standalone operation with a local
5+
reference clock and hybrid mode where it synchronizes with upstream servers
6+
while serving time to downstream clients.
7+
8+
> [!NOTE]
9+
> The NTP server is mutually exclusive with the NTP client in system
10+
> configuration context.
11+
12+
## Standalone Mode
13+
14+
Configure a standalone NTP server using only a local reference clock:
15+
16+
```
17+
admin@example:/> configure
18+
admin@example:/config/> edit ntp
19+
admin@example:/config/ntp/> leave
20+
```
21+
22+
When setting up NTP via the CLI the system automatically configures a local
23+
reference clock with [stratum](#ntp-stratum-levels) 10.
24+
25+
View the configuration:
26+
27+
```
28+
admin@example:/> show running-config
29+
"ietf-ntp:ntp": {
30+
"refclock-master": {
31+
"master-stratum": 10
32+
}
33+
}
34+
```
35+
36+
## Server Mode
37+
38+
Synchronize from upstream NTP servers while serving time to clients:
39+
40+
```
41+
admin@example:/config/> edit ntp
42+
admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
43+
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set iburst true
44+
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
45+
admin@example:/config/ntp/> edit unicast-configuration 1.pool.ntp.org type uc-server
46+
admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> set iburst true
47+
admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> end
48+
admin@example:/config/ntp/> leave
49+
```
50+
51+
The `unicast-configuration` uses a composite key with both address and type.
52+
Both hostnames and IP addresses are supported. The `iburst` option enables
53+
fast initial synchronization. The local reference clock (stratum 10) is
54+
automatically configured as a fallback.
55+
56+
## Peer Mode
57+
58+
In peer mode, two NTP servers synchronize with each other bidirectionally.
59+
Each server acts as both client and server to the other:
60+
61+
**First peer:**
62+
63+
```
64+
admin@peer1:/config/> edit ntp
65+
admin@peer1:/config/ntp/> edit unicast-configuration 192.168.1.2 type uc-peer
66+
admin@peer1:/config/ntp/…/192.168.1.2/type/uc-peer/> end
67+
admin@peer1:/config/ntp/> set refclock-master master-stratum 8
68+
admin@peer1:/config/ntp/> leave
69+
```
70+
71+
**Second peer:**
72+
73+
```
74+
admin@peer2:/config/> edit ntp
75+
admin@peer2:/config/ntp/> edit unicast-configuration 192.168.1.1 type uc-peer
76+
admin@peer2:/config/ntp/…/192.168.1.1/type/uc-peer/> end
77+
admin@peer2:/config/ntp/> set refclock-master master-stratum 8
78+
admin@peer2:/config/ntp/> leave
79+
```
80+
81+
This configuration provides mutual synchronization between peers. If one peer
82+
fails, the other continues to serve time to clients.
83+
84+
> [!NOTE]
85+
> The `iburst` and `burst` options are not supported in peer mode.
86+
87+
## Timing Configuration
88+
89+
### Poll Intervals
90+
91+
Control how often the NTP server polls upstream sources:
92+
93+
```
94+
admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
95+
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set minpoll 4
96+
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set maxpoll 10
97+
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
98+
```
99+
100+
Poll intervals are specified as powers of 2:
101+
- `minpoll 4` = poll every 2^4 = 16 seconds (minimum polling rate)
102+
- `maxpoll 10` = poll every 2^10 = 1024 seconds (maximum polling rate)
103+
- Defaults: minpoll 6 (64 seconds), maxpoll 10 (1024 seconds)
104+
105+
Use shorter intervals (minpoll 2-4) for faster convergence in test environments
106+
or peer configurations. Use defaults for production servers.
107+
108+
### Initial Synchronization
109+
110+
Enable clock stepping for systems that boot with incorrect time:
111+
112+
```
113+
admin@example:/config/ntp/> edit makestep
114+
admin@example:/config/ntp/makestep/> set threshold 1.0
115+
admin@example:/config/ntp/makestep/> set limit 3
116+
admin@example:/config/ntp/makestep/> end
117+
```
118+
119+
The `makestep` directive is automatically configured with safe defaults (1.0
120+
seconds threshold, 3 updates limit) when creating an NTP server. This is
121+
critical for embedded systems without RTC that boot with epoch time.
122+
123+
- **threshold** - If clock offset exceeds this (in seconds), step immediately
124+
instead of slewing slowly
125+
- **limit** - Number of updates during which stepping is allowed. After this,
126+
only gradual slewing is used for security
127+
128+
With these defaults, a device booting at epoch time (1970-01-01) will sync to
129+
correct time within seconds instead of hours.
130+
131+
## Monitoring
132+
133+
Check NTP server statistics:
134+
135+
```
136+
admin@example:/> show ntp server
137+
NTP SERVER CONFIGURATION
138+
Local Stratum : 10
139+
140+
SERVER STATISTICS
141+
Packets Received : 142
142+
Packets Sent : 142
143+
Packets Dropped : 0
144+
Send Failures : 0
145+
```
146+
147+
## NTP Stratum Levels
148+
149+
NTP uses a hierarchical system called **stratum** to indicate distance from
150+
authoritative time sources:
151+
152+
- **Stratum 0**: Reference clocks (atomic clocks, GPS receivers)
153+
- **Stratum 1**: Servers directly connected to stratum 0
154+
- **Stratum 2-15**: Servers that sync from lower stratum (each hop adds one)
155+
- **Stratum 16**: Unsynchronized (invalid)
156+
157+
**Default Stratum 10**: Infix uses stratum 10 as the default for local
158+
reference clocks. This is a safe, low-priority value that ensures clients
159+
will prefer upstream-synchronized servers (stratum 1-9) while still having
160+
a fallback time source in isolated networks.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ nav:
3737
- Services:
3838
- Device Discovery: discovery.md
3939
- DHCP Server: dhcp.md
40+
- NTP Server: ntp.md
4041
- System:
4142
- Boot Procedure: boot.md
4243
- Configuration: system.md

0 commit comments

Comments
 (0)