[depends on #514] Document NTP as the canonical clock reference, with yum "HTTPS Error 301" as one symptom

[gounthar]

Before submitting the pull request, you must agree with the following statements by checking both boxes with a 'x'.

• "I accept that my contribution is placed under the CC BY-SA 2.0 license [1]."
• "My contribution complies with the Developer Certificate of Origin [2]."

[1] https://creativecommons.org/licenses/by-sa/2.0/
[2] https://docs.xcp-ng.org/project/contributing/#developer-certificate-of-origin-dco

Important

Stacked on #514, and should be merged after it. The first commit here is that PR's
docs/management/time-synchronization.md page, so the diff shows it too. It cannot be
left out: onBrokenLinks is throw, and this PR links to that page. Once #514 merges,
a rebase drops it from this diff. Review the last two commits.

This replaces the earlier approach of expanding the NTP section in hosts-pools.md.
@stormi asked for the clock details to live in one place with the yum topic linking to
it, and that is the page in #514, so the material moved there rather than being written
twice. hosts-pools.md keeps its short section and gains a link.

Adds the troubleshooting entry @olivierlambert asked for in https://xcp-ng.org/forum/topic/11558 back in November 2025:

Classic 🙂 Maybe we should even provide a documentation about this in our troubleshooting section

The symptom is this, and it is one of the first things a fresh install can throw at someone:

http://mirrors.xcp-ng.org/8/8.3/base/x86_64/repodata/repomd.xml: [Errno 14] HTTPS Error 301 - Moved Permanently
Trying other mirror.
...
failure: repodata/repomd.xml from xcp-ng-base: [Errno 256] No more mirrors to try.

Read as an operator, that says our mirrors moved and the repo file is stale. So people edit xcp-ng.repo, run yum clean all, wipe /var/cache/yum, and none of it helps.

The mirrors are fine. mirrors.xcp-ng.org → HTTPS → geo-local mirror ends in a 200; curl -L walks it happily. What fails is the TLS leg. A host whose date precedes the mirror certificate's notBefore cannot complete the handshake, because from where it is standing the certificate is not yet valid.

The message blames the redirect because of how yum reports errors. In urlgrabber, _hdr_retrieve rewrites self.scheme/self.url the moment it sees a Location: header, before anything is attempted at the new address; the pycurl.error handler then formats from RESPONSE_CODE, which is still 301 from the hop that succeeded, and drops the real libcurl string. So the 301 you are shown is the last thing that went right. Generally: in yum, a transport failure after a redirect is reported as the redirect.

Why it seems worth a page rather than a forum answer

https://xcp-ng.org/forum/topic/9560 is the same symptom on 8.2, from 2024, and it ends with nobody knowing. That is the thread search returns for this error string. Meanwhile 11558 was solved by the reporter themselves, so it never became a support exchange either. Two threads, no landing page.

One thing I had not seen before, included in the page

On the host I looked at, chronyd was both running and enabled, network and DNS fine, and this was the whole of /etc/chrony.conf:

driftfile /var/lib/chrony/drift
makestep 1.0 3
rtcsync
logdir /var/log/chrony

No server, no pool. chronyc sources returned Number of sources = 0. Every check an operator would normally run comes back healthy; the only one that reveals it is chronyc sources, which nobody runs until they already suspect the clock. The host just keeps its installation date, and the first symptom shows up months later as a yum error about a redirect. Likely origin is setting the time manually at install.

That is also why the page says to add the servers to chrony.conf, not merely to run makestep — otherwise the fix is lost at the next boot.

Changes

• docs/management/hosts-pools.md: the existing Time synchronization (NTP) section becomes the reference for clocks: what a wrong date actually breaks, how to configure the servers, and how to check the sources and step the clock. Two sub-headings so the troubleshooting entries can link straight at the fix.
• docs/troubleshooting/common-problems.md: new section for the yum error, placed next to the existing Server loses time on 14th gen Dell hardware entry so the two clock problems sit together. It carries the diagnosis and the 301 explanation, and hands off to the NTP section for the fix.
• docs/management/updates.md: a warning under Prerequisites → Access to the repository, since that is the page people are reading when they hit this.

Checked

• Verified absent before writing: no page under docs/ contained 301, Moved Permanently or certificate is not yet valid.
• Anchor #yum-fails-with-https-error-301---moved-permanently generated with the repo's own github-slugger, not guessed.
• npm run build passes, which matters here because onBrokenLinks and onBrokenAnchors are both set to throw, and this PR now crosses between three pages.
• Fix verified end to end on a host that was stuck on 2024-09-08: after correcting the clock, yum check-update returned the full July 2026 Various changes and fixes #1 batch for 8.3 LTS, exit 0, with the repository file exactly as shipped.

Updated after review

• @stormi asked for one place that covers NTP properly, with this topic linking to it for details. The chrony material moved into Time synchronization (NTP) in hosts-pools.md, which already existed and was thin. It now opens with why a wrong clock matters, including two symptoms that name something other than the clock: this 301, and the installer's Signature Key Import Failed.
• @thomas-dkmt asked for one note with bullets instead of two notes. Both of those notes turned out to be generic clock facts, so they moved to the NTP section and are a single bulleted note there. The yum entry keeps one note.
• Command blocks now use <Terminal> like the rest of these files. Error output stays in plain fences.
• Rebased on master, and the four commits are squashed into one since the content was restructured anyway.

One thing I would still like a second opinion on

I state that correcting the date does not invalidate the host's own certificate, since XAPI issues it with a ten-year validity. Checked on one host (notBefore 2026-06-10, notAfter 2036-06-07). Worth someone confirming that is the rule and not that host's history.

Separately, and out of scope here: should the installer or xsconsole warn when a host ends up with zero configured time sources? Happy to open that somewhere else if it is worth raising.