mirror of
https://github.com/kernelkit/infix.git
synced 2026-07-30 04:33:00 +02:00
doc: add NTP server documentation
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
+174
@@ -0,0 +1,174 @@
|
||||
# NTP Server
|
||||
|
||||
The NTP (Network Time Protocol) server provides accurate time synchronization
|
||||
for network clients. It supports both standalone operation with a local
|
||||
reference clock and hybrid mode where it synchronizes with upstream servers
|
||||
while serving time to downstream clients.
|
||||
|
||||
> [!NOTE]
|
||||
> The NTP server is mutually exclusive with the NTP client in system
|
||||
> configuration context.
|
||||
|
||||
## Standalone Mode
|
||||
|
||||
Configure a standalone NTP server using only a local reference clock:
|
||||
|
||||
```
|
||||
admin@example:/> configure
|
||||
admin@example:/config/> edit ntp
|
||||
admin@example:/config/ntp/> leave
|
||||
```
|
||||
|
||||
When setting up NTP via the CLI the system automatically configures a local
|
||||
reference clock. The default [stratum](#ntp-stratum-levels) is 16 (unsynchronized),
|
||||
which is suitable for isolated networks. For production use, configure a specific
|
||||
stratum level:
|
||||
|
||||
```
|
||||
admin@example:/config/> edit ntp
|
||||
admin@example:/config/ntp/> set refclock-master master-stratum 10
|
||||
admin@example:/config/ntp/> leave
|
||||
```
|
||||
|
||||
## Server Mode
|
||||
|
||||
Synchronize from upstream NTP servers while serving time to clients:
|
||||
|
||||
```
|
||||
admin@example:/config/> edit ntp
|
||||
admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
|
||||
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set iburst true
|
||||
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
|
||||
admin@example:/config/ntp/> edit unicast-configuration 1.pool.ntp.org type uc-server
|
||||
admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> set iburst true
|
||||
admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> end
|
||||
admin@example:/config/ntp/> leave
|
||||
```
|
||||
|
||||
The `unicast-configuration` uses a composite key with both address and type.
|
||||
Both hostnames and IP addresses are supported. The `iburst` option enables
|
||||
fast initial synchronization.
|
||||
|
||||
## Peer Mode
|
||||
|
||||
In peer mode, two NTP servers synchronize with each other bidirectionally.
|
||||
Each server acts as both client and server to the other:
|
||||
|
||||
**First peer:**
|
||||
|
||||
```
|
||||
admin@peer1:/config/> edit ntp
|
||||
admin@peer1:/config/ntp/> edit unicast-configuration 192.168.1.2 type uc-peer
|
||||
admin@peer1:/config/ntp/…/192.168.1.2/type/uc-peer/> end
|
||||
admin@peer1:/config/ntp/> set refclock-master master-stratum 8
|
||||
admin@peer1:/config/ntp/> leave
|
||||
```
|
||||
|
||||
**Second peer:**
|
||||
|
||||
```
|
||||
admin@peer2:/config/> edit ntp
|
||||
admin@peer2:/config/ntp/> edit unicast-configuration 192.168.1.1 type uc-peer
|
||||
admin@peer2:/config/ntp/…/192.168.1.1/type/uc-peer/> end
|
||||
admin@peer2:/config/ntp/> set refclock-master master-stratum 8
|
||||
admin@peer2:/config/ntp/> leave
|
||||
```
|
||||
|
||||
This configuration provides mutual synchronization between peers. If one peer
|
||||
fails, the other continues to serve time to clients.
|
||||
|
||||
> [!NOTE]
|
||||
> The `iburst` and `burst` options are not supported in peer mode.
|
||||
|
||||
### Peer Selection in Symmetric Mode
|
||||
|
||||
When both peers have the same stratum (as in the example above where both are
|
||||
stratum 8), NTP's clock selection algorithm uses the **Reference ID** as the
|
||||
tie-breaker. The Reference ID is typically derived from the peer's IP address
|
||||
when using a local reference clock.
|
||||
|
||||
This means the peer with the **numerically lower IP address** will be selected
|
||||
as the sync source by the other peer. In the example above:
|
||||
|
||||
- peer1 (192.168.1.1) has a lower Reference ID
|
||||
- peer2 (192.168.1.2) will select peer1 as sync source
|
||||
|
||||
This behavior is deterministic and ensures stable clock selection. If you need
|
||||
a specific peer to be selected, configure it with a lower stratum level than
|
||||
the other peer.
|
||||
|
||||
## Timing Configuration
|
||||
|
||||
### Poll Intervals
|
||||
|
||||
Control how often the NTP server polls upstream sources:
|
||||
|
||||
```
|
||||
admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
|
||||
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set minpoll 4
|
||||
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set maxpoll 10
|
||||
admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
|
||||
```
|
||||
|
||||
Poll intervals are specified as powers of 2:
|
||||
- `minpoll 4` = poll every 2^4 = 16 seconds (minimum polling rate)
|
||||
- `maxpoll 10` = poll every 2^10 = 1024 seconds (maximum polling rate)
|
||||
- Defaults: minpoll 6 (64 seconds), maxpoll 10 (1024 seconds)
|
||||
|
||||
Use shorter intervals (minpoll 2-4) for faster convergence in test environments
|
||||
or peer configurations. Use defaults for production servers.
|
||||
|
||||
### Fast Initial Synchronization
|
||||
|
||||
The `makestep` directive is automatically configured with safe defaults (1.0
|
||||
seconds threshold, 3 updates limit) when creating an NTP server. This is
|
||||
critical for embedded systems without RTC that boot with epoch time.
|
||||
|
||||
To customize the values:
|
||||
|
||||
```
|
||||
admin@example:/config/ntp/> edit makestep
|
||||
admin@example:/config/ntp/makestep/> set threshold 2.0
|
||||
admin@example:/config/ntp/makestep/> set limit 1
|
||||
admin@example:/config/ntp/makestep/> end
|
||||
```
|
||||
|
||||
- **threshold** - If clock offset exceeds this (in seconds), step immediately
|
||||
instead of slewing slowly
|
||||
- **limit** - Number of updates during which stepping is allowed. After this,
|
||||
only gradual slewing is used for security
|
||||
|
||||
With these defaults, a device booting at epoch time (1970-01-01) will sync to
|
||||
correct time within seconds instead of hours.
|
||||
|
||||
## Monitoring
|
||||
|
||||
Check NTP server statistics:
|
||||
|
||||
```
|
||||
admin@example:/> show ntp server
|
||||
NTP SERVER CONFIGURATION
|
||||
Local Stratum : 10
|
||||
|
||||
SERVER STATISTICS
|
||||
Packets Received : 142
|
||||
Packets Sent : 142
|
||||
Packets Dropped : 0
|
||||
Send Failures : 0
|
||||
```
|
||||
|
||||
## NTP Stratum Levels
|
||||
|
||||
NTP uses a hierarchical system called **stratum** to indicate distance from
|
||||
authoritative time sources:
|
||||
|
||||
- **Stratum 0**: Reference clocks (atomic clocks)
|
||||
- **Stratum 1**: Servers directly connected to stratum 0 (e.g., GPS receivers)
|
||||
- **Stratum 2-15**: Servers that sync from lower stratum (each hop adds one)
|
||||
- **Stratum 16**: Unsynchronized (invalid)
|
||||
|
||||
The default stratum (16) is not suitable for distributing time in isolated
|
||||
networks, so when setting up an NTP server remember to adjust this value.
|
||||
Use, e.g., `10`, this is a safe, low-priority value that ensures clients will
|
||||
prefer upstream-synchronized servers (stratum 1-9) while still having a
|
||||
fallback time source in isolated networks.
|
||||
@@ -37,6 +37,7 @@ nav:
|
||||
- Services:
|
||||
- Device Discovery: discovery.md
|
||||
- DHCP Server: dhcp.md
|
||||
- NTP Server: ntp.md
|
||||
- System:
|
||||
- Boot Procedure: boot.md
|
||||
- Configuration: system.md
|
||||
|
||||
Reference in New Issue
Block a user