Expand the RTC section of the NTP guide - #1418
Open
DL6ER wants to merge 1 commit into
Open
Conversation
The RTC part of the Network Time Protocol guide was two lines. Cover why the hardware clock matters - a wrong time after a reboot breaks TLS and DNSSEC until the first sync - that Pi-hole only corrects the clock when it has drifted rather than writing on every sync, how device auto-discovery works when `ntp.sync.rtc.device` is left empty, and the previously undocumented `ntp.sync.rtc.utc` setting. Signed-off-by: DL6ER <dl6er@dl6er.de>
✅ Deploy Preview for pihole-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Expands the NTP guide’s RTC section to better explain what the RTC is, why it matters during boot, and how Pi-hole/FTL can keep it aligned after successful time sync, including documenting the ntp.sync.rtc.utc option.
Changes:
- Replaces the brief RTC blurb with a fuller explanation of RTC purpose and impact of incorrect time.
- Documents RTC update behavior and clarifies that
ntp.sync.rtc.setis disabled by default. - Explains RTC device auto-discovery via
ntp.sync.rtc.deviceand adds guidance forntp.sync.rtc.utc(UTC vs localtime).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
yubiuser
reviewed
Aug 21, 2026
yubiuser
left a comment
yubiuser
left a comment
Member
There was a problem hiding this comment.
I think the whole NTP section should be moved from Guides -> Misc > NTP to FTL->NTP
|
|
||
| Network Time Protocol (NTP) is used to synchronise the clocks of devices on a network, ensuring they report the same time. In a home network, NTP helps keep computers, routers, and iot/smart devices running on the same time, ensuring consistency between scheduling events, logging activities, and within time-sensitive applications. It works by connecting to time servers on the internet, which provide accurate time based on atomic clocks. A server on your own network can then relay the information to devices on your network. Operating your own server minimises external traffic and helps keep the time consistent across your devices. | ||
|
|
||
| # Configuring Pi-hole's NTP client and server |
Member
There was a problem hiding this comment.
The TOC section is broken due to two first-level headings. I wonder why no linter picked this up
Suggested change
| ## Configuring Pi-hole's NTP client and server |
| Many computers keep time while powered off using a small, battery-backed hardware clock called the *real time clock* (RTC). The operating system reads it at boot to know the current time before it has had a chance to reach the network. If that clock drifts, or was never set, the system can start up with the wrong time - and being off by even a few minutes is enough to break TLS certificate validation or DNSSEC until the first successful NTP synchronisation. | ||
|
|
||
| This is enabled by the setting `ntp.sync.rtc.set`. | ||
| Pi-hole can keep the hardware clock correct for you. When this is enabled, after each successful synchronisation Pi-hole checks the hardware clock against the accurate time it just obtained and, if the two differ, corrects it. There is no needless writing when the clock is already right. The RTC therefore stays close to the real time, and your system comes up with a good time immediately after a reboot, even before it has reached an NTP server. |
Member
There was a problem hiding this comment.
Suggested change
| Pi-hole can keep the hardware clock correct for you. When this is enabled, after each successful synchronisation Pi-hole checks the hardware clock against the accurate time it just obtained and, if the two differ, corrects it. There is no needless writing when the clock is already right. The RTC therefore stays close to the real time, and your system comes up with a good time immediately after a reboot, even before it has reached an NTP server. | |
| Pi-hole can keep the hardware clock in sync for you. When this is enabled, after each successful synchronisation Pi-hole checks the hardware clock against the accurate time it just obtained from NTP and, if the two differ, corrects it. There is no needless writing when the clock is already right. The RTC therefore stays close to the real time, and your system comes up with a good time immediately after a reboot, even before it has reached an NTP server. |
| This is enabled by the setting `ntp.sync.rtc.set`. | ||
| Pi-hole can keep the hardware clock correct for you. When this is enabled, after each successful synchronisation Pi-hole checks the hardware clock against the accurate time it just obtained and, if the two differ, corrects it. There is no needless writing when the clock is already right. The RTC therefore stays close to the real time, and your system comes up with a good time immediately after a reboot, even before it has reached an NTP server. | ||
|
|
||
| This is disabled by default and enabled with `ntp.sync.rtc.set`. |
Member
There was a problem hiding this comment.
This and the next section duplication the the "off by default" fact. Maybe the two sections can be combined.
Side note: I wonder if the default should be enabling this feature - if there is no RTC it won't harm. If there is one, users benefit automatically from it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The real-time clock part of the NTP guide was two lines. This fleshes it out: why the RTC matters, that Pi-hole only corrects it when it has drifted, how the device is auto-discovered, and the previously undocumented
ntp.sync.rtc.utc.