From e509d0db46e19cf6cfa72372b67e7a66dd9f0ddf Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Mon, 3 Aug 2026 19:11:01 +0200 Subject: [PATCH 1/8] docs(management): add a time synchronization page Wrong clocks cause failures across the product that rarely name the clock: TLS validation against the mirrors when fetching updates, pool join, and certificate validity windows. NTP was documented only in passing, in the installer walkthrough, the answer file reference and the pool requirements. Gather it into one page: why the date matters, how to set the sources at install time and afterwards, how to check them, and how to correct a clock that is already wrong. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 161 ++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/management/time-synchronization.md diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md new file mode 100644 index 00000000..b4dc2303 --- /dev/null +++ b/docs/management/time-synchronization.md @@ -0,0 +1,161 @@ +--- +sidebar_position: 8 +--- + +# Time synchronization + +XCP-ng keeps the dom0 clock with `chronyd`. A host whose date is wrong carries on working +normally until something needs to trust that date, and the failures it produces then rarely +mention time at all. This page covers why the clock matters, how to configure NTP, and how +to check and correct it. + +## ⏰ Why the clock must be correct {#why-the-clock-must-be-correct} + +- **Access to the repositories.** Updates are fetched over HTTPS, and TLS validates the + server's certificate against the host's own date. A host set far in the past cannot + complete the handshake, because from where it is standing the mirror's certificate is not + valid yet. The error `yum` prints in that situation does not mention time. +- **Pool membership.** A host joining a pool must have its clock synchronized with the pool + master. See [Pool Requirements](../../installation/requirements#pool-requirements). +- **Certificates.** Certificates are only valid inside a validity window. A host whose date + falls outside that window will reject, or be rejected by, connections that would otherwise + succeed. +- **Logs and scheduled operations.** Correlating events across the hosts of a pool, and + anything that runs on a schedule such as backups, depend on the hosts agreeing on what + time it is. + +## 🕰️ How XCP-ng keeps time {#how-xcp-ng-keeps-time} + +The time daemon on dom0 is `chronyd`, configured through `/etc/chrony.conf`. + +The shipped configuration enables `rtcsync`, so chronyd keeps the hardware clock in step +with the system clock on its own. There is no need to copy a corrected time to the hardware +clock by hand, and a correction survives a reboot. + +## 🔧 Configuring the time sources {#configuring-the-time-sources} + +### During installation + +The installer asks for the timezone and the time at step 11, and lets you either give it NTP +servers or set the time manually. Always give it an NTP server. See +[Install XCP-ng](../../installation/install-xcp-ng). + +:::warning +If you set the time manually at this step, the host can end up with `chronyd` running but no +time source configured at all. It will keep whatever date it was installed with. See +[Checking the time sources](#checking-the-time-sources) below. +::: + +### During an automated installation + +The installation answer file accepts one or more NTP servers through the `` +element. See [Answer file](../../appendix/answerfile). + +### On an installed host + +You can configure NTP from `xsconsole`, or by editing `/etc/chrony.conf` directly and +restarting the service. + +## 🔍 Checking the time sources {#checking-the-time-sources} + +Check that the service is running, and that it actually has something to synchronize with: + +```bash +systemctl status chronyd +chronyc sources +``` + +Both matter, and the second is the one that gets skipped. `chronyd` can be running and +enabled while having **no time sources configured at all**: + +``` +# chronyc sources +210 Number of sources = 0 +``` + +The service is then behaving exactly as configured, and doing nothing. Every other check an +operator would normally run looks healthy, which is what makes this one worth running early +rather than late. + +When sources are configured, `chronyc sources` lists them. In the `MS` column, the second +character is the state of that source: `*` marks the one currently being used, `+` marks +another acceptable source being combined with it, and `?` means the source is unreachable. +At least one source should reach the `*` state. + +To see the offset chrony believes it has, and whether it has settled: + +```bash +chronyc tracking +``` + +## 🛠️ Correcting a wrong clock {#correcting-a-wrong-clock} + +Start with `chronyc sources`, because the answer decides which of the two paths below +applies. + +### If sources are listed + +Correct the clock and check the result: + +```bash +chronyc makestep +date +``` + +`chronyc makestep` is what does the work here. By default chrony corrects an offset by +slewing the clock gradually, which never converges for an offset of months or years. + +### If `Number of sources = 0` + +Do not start with `makestep`. It will report success and move nothing, because chrony has no +measured offset to step to. Add time sources to `/etc/chrony.conf` first: + +``` +server 0.centos.pool.ntp.org iburst +server 1.centos.pool.ntp.org iburst +server 2.centos.pool.ntp.org iburst +server 3.centos.pool.ntp.org iburst +``` + +Then restart the service and confirm that a source has become reachable, as described in +[Checking the time sources](#checking-the-time-sources): + +```bash +systemctl restart chronyd +chronyc sources +``` + +Once a source is reachable, correct the clock: + +```bash +chronyc makestep +date +``` + +:::note +Correcting the date does not invalidate the host's own certificate. XAPI issues it with a +ten-year validity, so a host installed with a wrong date still holds a certificate that +covers the corrected date. `xe host-refresh-server-certificate` is not needed for this. +::: + +:::tip +If `date` is wrong again after every power cycle, the motherboard's RTC battery is probably +dead and should be replaced. `rtcsync` can only keep the hardware clock in step while the +host is running; it cannot help a clock that loses its value when the power goes. +::: + +## 🌐 Isolated networks {#isolated-networks} + +Hosts without access to the internet cannot reach the public NTP pool, and the symptom is +the same as having no sources at all: `chronyc sources` lists servers that never leave the +`?` state. + +On such a network, point `/etc/chrony.conf` at a time source that hosts can actually reach, +such as an appliance on the same network or a local server that is itself synchronized. + +## 🎱 Pools {#pools} + +Keep every host in a pool synchronized, ideally against the same sources. A host whose clock +disagrees with the pool master is not merely inconvenient: clock synchronization is one of +the requirements for joining a pool in the first place, alongside the others listed in +[Pool Requirements](../../installation/requirements#pool-requirements). From 630a4ba2f6416bf8e598adbdba5c58fc076d398a Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Tue, 11 Aug 2026 17:23:04 +0200 Subject: [PATCH 2/8] docs(ntp): apply review wording, and drop the CentOS vendor pool Review suggestions from @thomas-dkmt on the intro, the TLS bullet, rtcsync, the installer step, the source states, makestep, the isolated-network prose and the pool paragraph. The source states and the recovery procedure become lists rather than running prose. @rzr: the sample configuration used the CentOS vendor zone, which is not ours to use. It now points at the generic public pool. The code blocks inside the numbered procedure are indented under their items, so it renders as one list rather than restarting at each fence. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 87 +++++++++++++------------ 1 file changed, 46 insertions(+), 41 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index b4dc2303..80afe6b4 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -4,17 +4,17 @@ sidebar_position: 8 # Time synchronization -XCP-ng keeps the dom0 clock with `chronyd`. A host whose date is wrong carries on working -normally until something needs to trust that date, and the failures it produces then rarely -mention time at all. This page covers why the clock matters, how to configure NTP, and how -to check and correct it. +XCP-ng keeps the dom0 clock synchronized using `chronyd`. A host whose date is wrong keeps +working normally until something needs to trust that date. When that happens, the resulting +failures rarely point to the clock as the cause. This page explains why the clock matters, how +to configure NTP, and how to check and correct it. ## ⏰ Why the clock must be correct {#why-the-clock-must-be-correct} - **Access to the repositories.** Updates are fetched over HTTPS, and TLS validates the - server's certificate against the host's own date. A host set far in the past cannot - complete the handshake, because from where it is standing the mirror's certificate is not - valid yet. The error `yum` prints in that situation does not mention time. + server's certificate against the host's own date. If the host's clock is set too far in the + past, the TLS handshake fails because, from the host's perspective, the mirror's certificate + is not yet valid. The error `yum` prints in that situation does not mention time. - **Pool membership.** A host joining a pool must have its clock synchronized with the pool master. See [Pool Requirements](../../installation/requirements#pool-requirements). - **Certificates.** Certificates are only valid inside a validity window. A host whose date @@ -28,16 +28,16 @@ to check and correct it. The time daemon on dom0 is `chronyd`, configured through `/etc/chrony.conf`. -The shipped configuration enables `rtcsync`, so chronyd keeps the hardware clock in step -with the system clock on its own. There is no need to copy a corrected time to the hardware -clock by hand, and a correction survives a reboot. +The default configuration enables `rtcsync`, allowing chronyd to keep the hardware clock +synchronized with the system clock automatically. There is no need to manually update the +hardware clock after correcting the system time, and the correction persists across reboots. ## 🔧 Configuring the time sources {#configuring-the-time-sources} ### During installation -The installer asks for the timezone and the time at step 11, and lets you either give it NTP -servers or set the time manually. Always give it an NTP server. See +At step 11, the installer prompts you to enter the time, select a time zone and either +configure NTP servers or set the time manually. Always configure at least one NTP server. See [Install XCP-ng](../../installation/install-xcp-ng). :::warning @@ -73,13 +73,17 @@ enabled while having **no time sources configured at all**: 210 Number of sources = 0 ``` -The service is then behaving exactly as configured, and doing nothing. Every other check an +Then, the service behaves exactly as configured, and does nothing. Every other check an operator would normally run looks healthy, which is what makes this one worth running early rather than late. When sources are configured, `chronyc sources` lists them. In the `MS` column, the second -character is the state of that source: `*` marks the one currently being used, `+` marks -another acceptable source being combined with it, and `?` means the source is unreachable. +character is the state of that source: + +- `*` marks the one currently being used. +- `+` marks another acceptable source being combined with it. +- `?` means the source is unreachable. + At least one source should reach the `*` state. To see the offset chrony believes it has, and whether it has settled: @@ -102,35 +106,37 @@ chronyc makestep date ``` -`chronyc makestep` is what does the work here. By default chrony corrects an offset by -slewing the clock gradually, which never converges for an offset of months or years. +`chronyc makestep` is what does the work here. By default, chrony corrects time offsets by +gradually slewing the system clock, which never converges for an offset of months or years. ### If `Number of sources = 0` Do not start with `makestep`. It will report success and move nothing, because chrony has no -measured offset to step to. Add time sources to `/etc/chrony.conf` first: +measured offset to step to. -``` -server 0.centos.pool.ntp.org iburst -server 1.centos.pool.ntp.org iburst -server 2.centos.pool.ntp.org iburst -server 3.centos.pool.ntp.org iburst -``` +1. Add time sources to `/etc/chrony.conf`: -Then restart the service and confirm that a source has become reachable, as described in -[Checking the time sources](#checking-the-time-sources): + ``` + server 0.pool.ntp.org iburst + server 1.pool.ntp.org iburst + server 2.pool.ntp.org iburst + server 3.pool.ntp.org iburst + ``` -```bash -systemctl restart chronyd -chronyc sources -``` +2. Restart the service and confirm that a source has become reachable, as described in + [Checking the time sources](#checking-the-time-sources): -Once a source is reachable, correct the clock: + ```bash + systemctl restart chronyd + chronyc sources + ``` -```bash -chronyc makestep -date -``` +3. Once a source is reachable, correct the clock: + + ```bash + chronyc makestep + date + ``` :::note Correcting the date does not invalidate the host's own certificate. XAPI issues it with a @@ -146,16 +152,15 @@ host is running; it cannot help a clock that loses its value when the power goes ## 🌐 Isolated networks {#isolated-networks} -Hosts without access to the internet cannot reach the public NTP pool, and the symptom is -the same as having no sources at all: `chronyc sources` lists servers that never leave the -`?` state. +Hosts without Internet access cannot reach the public NTP pool. The result is the same as +having no sources at all: `chronyc sources` lists servers that never leave the `?` state. -On such a network, point `/etc/chrony.conf` at a time source that hosts can actually reach, +On such networks, point `/etc/chrony.conf` at a time source that hosts can actually reach, such as an appliance on the same network or a local server that is itself synchronized. ## 🎱 Pools {#pools} Keep every host in a pool synchronized, ideally against the same sources. A host whose clock -disagrees with the pool master is not merely inconvenient: clock synchronization is one of -the requirements for joining a pool in the first place, alongside the others listed in +differs from the pool master is not just inconvenient: clock synchronization is one of +the requirements for joining a pool, along with the other requirements listed in [Pool Requirements](../../installation/requirements#pool-requirements). From ba4d349192728d817bc29bc88ae6f824fff2b451 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Tue, 11 Aug 2026 19:08:22 +0200 Subject: [PATCH 3/8] docs(ntp): name the condition rather than the network, and rzr's wording Two reviewers disliked "Isolated networks" and suggested "Offline" and "offgrid". Neither works here: offline already means a host being down in these docs, and offgrid appears nowhere in them. Two people tripping on the same word is still a signal, so the section names the condition instead. @rzr: "point to" rather than "point at", and say that the local server acts as the reference time for the network rather than only being synchronized. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index 80afe6b4..2081304d 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -150,13 +150,14 @@ dead and should be replaced. `rtcsync` can only keep the hardware clock in step host is running; it cannot help a clock that loses its value when the power goes. ::: -## 🌐 Isolated networks {#isolated-networks} +## 🌐 Networks without internet access {#networks-without-internet-access} Hosts without Internet access cannot reach the public NTP pool. The result is the same as having no sources at all: `chronyc sources` lists servers that never leave the `?` state. -On such networks, point `/etc/chrony.conf` at a time source that hosts can actually reach, -such as an appliance on the same network or a local server that is itself synchronized. +On such networks, point `/etc/chrony.conf` to a time source that hosts can actually reach, +such as an appliance on the same network, or a local server that is itself synchronized and +acts as the reference time for the network. ## 🎱 Pools {#pools} From 112b80e963e37d5ac50375359bf9907a4682c572 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Wed, 12 Aug 2026 09:50:51 +0200 Subject: [PATCH 4/8] docs(ntp): show a healthy chronyc sources listing, and explain the - state rzr asked for the expected output next to the failure case. Taking it off an 8.3 host rather than composing it turned up a gap in the legend: it listed *, + and ?, but a normal four-source listing is mostly -, which was not described anywhere. A reader comparing the prose to their own output had nothing to match it against. Adds the healthy systemctl and chronyc sources output, the - state, and the first MS character for the source type. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 28 +++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index 2081304d..a8527654 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -77,14 +77,34 @@ Then, the service behaves exactly as configured, and does nothing. Every other c operator would normally run looks healthy, which is what makes this one worth running early rather than late. -When sources are configured, `chronyc sources` lists them. In the `MS` column, the second -character is the state of that source: +On a host that is synchronizing normally, the same two commands look like this: + +``` +# systemctl status chronyd +● chronyd.service - NTP client/server + Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled; vendor preset: enabled) + Active: active (running) since Wed 2026-08-12 08:38:14 CEST; 46min ago + +# chronyc sources +210 Number of sources = 4 +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +^* vps1.websters-computers.> 2 7 377 59 -361us[ -444us] +/- 8522us +^+ meshflow.net 3 9 377 118 +203us[ +122us] +/- 12ms +^+ mail.rapidooo.fr 2 9 377 113 -1029us[-1110us] +/- 9934us +^- 88-185-213-3.subs.proxad> 3 8 377 506 +688us[ +491us] +/- 49ms +``` + +In the `MS` column, the first character is the source type, `^` for a server, and the second +is the state of that source: - `*` marks the one currently being used. -- `+` marks another acceptable source being combined with it. +- `+` marks another acceptable source, combined with it. +- `-` marks a source chrony is measuring but has excluded from the combination. - `?` means the source is unreachable. -At least one source should reach the `*` state. +At least one source should reach the `*` state. Seeing `-` on some of the others is normal +and does not need correcting. To see the offset chrony believes it has, and whether it has settled: From 73a28cbc816356f5c8810422f4d82e7524359450 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Mon, 17 Aug 2026 14:23:11 +0200 Subject: [PATCH 5/8] Answer the review on time synchronization, with measurements Nine points from review. Three of them were questions with checkable answers rather than wording, so they got checked on an 8.3 host. The certificate note was wrong. It said a corrected date always stays inside the host certificate's validity, so no refresh is needed. The certificate is ten years wide and anchored on the clock at generation time: notBefore Jun 2 2026, notAfter May 30 2036 on the test host. A host that installed itself believing the year was 2010 therefore holds a certificate that expired in 2020, and correcting the clock leaves it expired. The note now says most corrections are fine, how to check the window against the date, and how to regenerate when it is outside. host-refresh-server-certificate takes host as a required parameter, and host-emergency-reset-server-certificate is the local one for a host already being rejected. Whether chronyd self-heals a wrong date at startup: yes, given a source. Stock chrony.conf carries makestep 1.0 3. A clock put 45 days in the past was corrected between five and ten seconds after chronyd started. The page had claimed chrony only slews and never converges for large offsets, which is true after those first three updates and not at boot. That reframes the manual correction as the narrower case it is. Xen Orchestra does not configure NTP on hosts. Its xoa network ntp and the NTP field in the deploy form both target the XOA appliance, which keeps its own Debian clock. Checked by grepping a clone of the XO tree: every hit outside docs is one locale string and the deploy form that uses it, and chrony appears nowhere. The rest: the correction section is now a diagnosis working outward from configuration to firewall, with stepping the clock demoted to a stopgap; xsconsole is the documented route and editing chrony.conf by hand is marked last resort in both places it appeared; the reference to a numbered installer step is gone; the manual-time warning no longer reads as though the date stops incrementing; example server names are placeholders; and the Pools section folded into the pool bullet it was duplicating, which also picks up the point about drift after joining. Still open, and not mine to answer: the suggestion that the support team would have useful input on the diagnosis order. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 142 +++++++++++++++--------- 1 file changed, 90 insertions(+), 52 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index a8527654..d83daa6e 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -16,7 +16,10 @@ to configure NTP, and how to check and correct it. past, the TLS handshake fails because, from the host's perspective, the mirror's certificate is not yet valid. The error `yum` prints in that situation does not mention time. - **Pool membership.** A host joining a pool must have its clock synchronized with the pool - master. See [Pool Requirements](../../installation/requirements#pool-requirements). + master, and must stay synchronized afterwards. A failed join tells you what is wrong. Drift + that sets in later does not: it surfaces as hosts disagreeing about when things happened, + each of them convinced by its own clock. Keep every host in a pool on the same time sources. + See [Pool Requirements](../../installation/requirements#pool-requirements). - **Certificates.** Certificates are only valid inside a validity window. A host whose date falls outside that window will reject, or be rejected by, connections that would otherwise succeed. @@ -32,18 +35,30 @@ The default configuration enables `rtcsync`, allowing chronyd to keep the hardwa synchronized with the system clock automatically. There is no need to manually update the hardware clock after correcting the system time, and the correction persists across reboots. +It also sets `makestep 1.0 3`, which lets chronyd jump the clock rather than ease it into +place, for the first three updates after the service starts. A host that boots with a badly +wrong date therefore fixes itself within seconds, as long as it can reach a time source. +Measured on 8.3: a clock put 45 days in the past was corrected between five and ten seconds +after `chronyd` started. + +After those three updates chronyd only slews, which for an offset of months or years never +converges. That is the case the manual correction below exists for, along with the host that +had no time source to begin with. + ## 🔧 Configuring the time sources {#configuring-the-time-sources} ### During installation -At step 11, the installer prompts you to enter the time, select a time zone and either -configure NTP servers or set the time manually. Always configure at least one NTP server. See +The installer prompts you to enter the time, select a time zone, and either configure NTP +servers or set the time manually. Always configure at least one NTP server. See [Install XCP-ng](../../installation/install-xcp-ng). :::warning If you set the time manually at this step, the host can end up with `chronyd` running but no -time source configured at all. It will keep whatever date it was installed with. See -[Checking the time sources](#checking-the-time-sources) below. +time source configured at all. The clock still ticks, but nothing ever checks it: it drifts +from the date you typed, and if that date was wrong, it stays wrong. This is also the one +case that does not fix itself at boot, since `makestep` needs a source to measure against. +See [Checking the time sources](#checking-the-time-sources) below. ::: ### During an automated installation @@ -53,8 +68,17 @@ element. See [Answer file](../../appendix/answerfile). ### On an installed host -You can configure NTP from `xsconsole`, or by editing `/etc/chrony.conf` directly and -restarting the service. +Use `xsconsole`. Its NTP screen adds and removes time servers and restarts `chronyd` for you. + +:::warning +Editing `/etc/chrony.conf` by hand is a last resort, for when no other route works. Reach for +`xsconsole` first. + +Xen Orchestra does not configure NTP on hosts. Its `xoa network ntp` command sets the time +servers of the XOA appliance itself, which is a Debian VM keeping its own clock, and the NTP +field in the XOA deployment form does the same for the appliance being deployed. Neither +touches the chrony configuration of the hosts XO manages. +::: ## 🔍 Checking the time sources {#checking-the-time-sources} @@ -89,10 +113,10 @@ On a host that is synchronizing normally, the same two commands look like this: 210 Number of sources = 4 MS Name/IP address Stratum Poll Reach LastRx Last sample =============================================================================== -^* vps1.websters-computers.> 2 7 377 59 -361us[ -444us] +/- 8522us -^+ meshflow.net 3 9 377 118 +203us[ +122us] +/- 12ms -^+ mail.rapidooo.fr 2 9 377 113 -1029us[-1110us] +/- 9934us -^- 88-185-213-3.subs.proxad> 3 8 377 506 +688us[ +491us] +/- 49ms +^* ntp1.example.net 2 7 377 59 -361us[ -444us] +/- 8522us +^+ ntp2.example.net 3 9 377 118 +203us[ +122us] +/- 12ms +^+ ntp3.example.net 2 9 377 113 -1029us[-1110us] +/- 9934us +^- ntp4.example.net 3 8 377 506 +688us[ +491us] +/- 49ms ``` In the `MS` column, the first character is the source type, `^` for a server, and the second @@ -114,54 +138,75 @@ chronyc tracking ## 🛠️ Correcting a wrong clock {#correcting-a-wrong-clock} -Start with `chronyc sources`, because the answer decides which of the two paths below -applies. +A host with working time sources does not usually have a wrong clock, because chronyd steps +it within seconds of starting. So a clock that is still wrong is telling you that something +upstream of it is broken. Find that first. Stepping the clock by hand gets you working again +today, and if you stop there the date is wrong again in a few weeks. -### If sources are listed +Work outward, from the configuration to the network: -Correct the clock and check the result: +1. **Are there any sources?** `chronyc sources`. `Number of sources = 0` means none were + ever configured, which is the manual-time-at-install case. Add them with `xsconsole`. +2. **Are they reachable?** Sources stuck at `?` are configured but unanswered. NTP goes out + over UDP 123, so a firewall between the host and its servers produces exactly this, as + does a network with no route to the public pool. See + [Networks without internet access](#networks-without-internet-access). +3. **Is the daemon healthy?** `systemctl status chronyd`, and `journalctl -u chronyd` for + what it made of its configuration at startup. +4. **Was the configuration changed underneath you?** `rpm -V chrony` reports whether + `/etc/chrony.conf` still matches the package. Hand edits and `xsconsole` both show up here. + +Once sources are reachable, restarting the daemon corrects the clock on its own, because the +`makestep` allowance applies again from a fresh start: ```bash -chronyc makestep +systemctl restart chronyd +chronyc sources date ``` -`chronyc makestep` is what does the work here. By default, chrony corrects time offsets by -gradually slewing the system clock, which never converges for an offset of months or years. +### Stepping the clock immediately -### If `Number of sources = 0` +If you need the correct date right now and the daemon has been running for a while, its +`makestep` allowance is already spent and it will only slew: -Do not start with `makestep`. It will report success and move nothing, because chrony has no -measured offset to step to. +```bash +chronyc makestep +date +``` + +This is a stopgap. It needs at least one reachable source to have something to step to, and +on a host with `Number of sources = 0` it reports success while moving nothing. It also does +nothing about the reason the clock was wrong, so treat it as buying time for the diagnosis +above rather than as the end of it. -1. Add time sources to `/etc/chrony.conf`: +:::note +**Check the host certificate after a large correction.** - ``` - server 0.pool.ntp.org iburst - server 1.pool.ntp.org iburst - server 2.pool.ntp.org iburst - server 3.pool.ntp.org iburst - ``` +XAPI issues the host certificate with a ten-year validity, anchored on the clock at the time +it was generated. Small corrections stay comfortably inside that window, so most of the time +there is nothing to do. -2. Restart the service and confirm that a source has become reachable, as described in - [Checking the time sources](#checking-the-time-sources): +A big correction is different. A host that installed itself believing the year was 2010 holds +a certificate valid 2010 to 2020, and moving the clock to the real date leaves that +certificate expired. A clock set far into the future at install produces the mirror image: a +certificate that is not valid yet once the date is corrected backwards. - ```bash - systemctl restart chronyd - chronyc sources - ``` +Check the window against the corrected date: -3. Once a source is reachable, correct the clock: +```bash +openssl x509 -in /etc/xensource/xapi-ssl.pem -noout -dates +date -u +``` - ```bash - chronyc makestep - date - ``` +If the current date falls outside `notBefore` to `notAfter`, regenerate the certificate: -:::note -Correcting the date does not invalidate the host's own certificate. XAPI issues it with a -ten-year validity, so a host installed with a wrong date still holds a certificate that -covers the corrected date. `xe host-refresh-server-certificate` is not needed for this. +```bash +xe host-refresh-server-certificate host= +``` + +On a host whose certificate is already rejected, and which therefore cannot be reached the +usual way, `xe host-emergency-reset-server-certificate` runs locally on the host itself. ::: :::tip @@ -175,13 +220,6 @@ host is running; it cannot help a clock that loses its value when the power goes Hosts without Internet access cannot reach the public NTP pool. The result is the same as having no sources at all: `chronyc sources` lists servers that never leave the `?` state. -On such networks, point `/etc/chrony.conf` to a time source that hosts can actually reach, -such as an appliance on the same network, or a local server that is itself synchronized and +On such networks, point the hosts at a time source they can actually reach, using `xsconsole` +as above: an appliance on the same network, or a local server that is itself synchronized and acts as the reference time for the network. - -## 🎱 Pools {#pools} - -Keep every host in a pool synchronized, ideally against the same sources. A host whose clock -differs from the pool master is not just inconvenient: clock synchronization is one of -the requirements for joining a pool, along with the other requirements listed in -[Pool Requirements](../../installation/requirements#pool-requirements). From c848a9bbc0ef7b0ada9037a8d80b9a1ddfd78ce4 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Mon, 17 Aug 2026 14:49:41 +0200 Subject: [PATCH 6/8] Correct the certificate note: two certificates, two commands The note I pushed earlier told the reader to check the dates on xapi-ssl.pem and then run host-refresh-server-certificate. Those are different certificates. The refresh command renews the internal pool certificate and leaves the TLS one alone, so following the note would have printed success and fixed nothing. Found by reproducing the failure rather than reasoning about it. On an 8.3 host, with the clock moved to 2016 and chronyd stopped, host-refresh-server-certificate produced a pool certificate valid 2016-08-17 to 2026-08-15. Restoring the clock left that certificate expired by two days, which is the failure the note describes, observed rather than deduced. xapi-ssl.pem was untouched throughout, which is what exposed the wrong pairing. xe help is explicit once you read it: host-reset-server-certificate "deletes the current TLS server certificate", host-refresh-server- certificate refreshes the "internal" one. The note now carries both paths in a table, tells the reader to check both windows, and warns against the substitution I had just made. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 32 +++++++++++++++---------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index d83daa6e..744339d1 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -183,29 +183,35 @@ above rather than as the end of it. :::note **Check the host certificate after a large correction.** -XAPI issues the host certificate with a ten-year validity, anchored on the clock at the time -it was generated. Small corrections stay comfortably inside that window, so most of the time +XAPI issues certificates with a ten-year validity, anchored on the clock at the moment they +are generated. Small corrections stay comfortably inside that window, so most of the time there is nothing to do. -A big correction is different. A host that installed itself believing the year was 2010 holds -a certificate valid 2010 to 2020, and moving the clock to the real date leaves that -certificate expired. A clock set far into the future at install produces the mirror image: a -certificate that is not valid yet once the date is corrected backwards. +A big correction is different. A host that generated its certificates believing the year was +2016 holds them valid 2016 to 2026, and moving the clock to the real date can leave them +expired. A clock set far into the future produces the mirror image: certificates not valid +yet once the date is corrected backwards. -Check the window against the corrected date: +There are two, and they are refreshed by different commands: + +| Certificate | What it is | Regenerate with | +|---|---|---| +| `/etc/xensource/xapi-ssl.pem` | The TLS certificate clients see, including Xen Orchestra | `xe host-reset-server-certificate` | +| `/etc/xensource/xapi-pool-tls.pem` | The internal certificate hosts use between themselves | `xe host-refresh-server-certificate host=` | + +Check both windows against the corrected date: ```bash openssl x509 -in /etc/xensource/xapi-ssl.pem -noout -dates +openssl x509 -in /etc/xensource/xapi-pool-tls.pem -noout -dates date -u ``` -If the current date falls outside `notBefore` to `notAfter`, regenerate the certificate: - -```bash -xe host-refresh-server-certificate host= -``` +If the date falls outside `notBefore` to `notAfter`, regenerate the one concerned using the +table above. Do not reach for `host-refresh-server-certificate` to fix `xapi-ssl.pem`: it +refreshes the internal certificate, reports success, and leaves the TLS one untouched. -On a host whose certificate is already rejected, and which therefore cannot be reached the +On a host whose TLS certificate is already rejected, and which therefore cannot be reached the usual way, `xe host-emergency-reset-server-certificate` runs locally on the host itself. ::: From c2b19bbcbf77c6097b6cfba48f49d9f145037342 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Mon, 17 Aug 2026 15:10:21 +0200 Subject: [PATCH 7/8] Drop the emoji from this page's headings Review raised that #525 removes emoji from headings across the docs, and asked whether this page should follow. It should: #522 and #524 were the two competing approaches and both are closed, so #525 is the only live option and it is approved. A new page landing with six emoji headings would put back a small part of what that PR takes out. Heading text and anchors are untouched, so no links move. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index 744339d1..71f7a5af 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -9,7 +9,7 @@ working normally until something needs to trust that date. When that happens, th failures rarely point to the clock as the cause. This page explains why the clock matters, how to configure NTP, and how to check and correct it. -## ⏰ Why the clock must be correct {#why-the-clock-must-be-correct} +## Why the clock must be correct {#why-the-clock-must-be-correct} - **Access to the repositories.** Updates are fetched over HTTPS, and TLS validates the server's certificate against the host's own date. If the host's clock is set too far in the @@ -27,7 +27,7 @@ to configure NTP, and how to check and correct it. anything that runs on a schedule such as backups, depend on the hosts agreeing on what time it is. -## 🕰️ How XCP-ng keeps time {#how-xcp-ng-keeps-time} +## How XCP-ng keeps time {#how-xcp-ng-keeps-time} The time daemon on dom0 is `chronyd`, configured through `/etc/chrony.conf`. @@ -45,7 +45,7 @@ After those three updates chronyd only slews, which for an offset of months or y converges. That is the case the manual correction below exists for, along with the host that had no time source to begin with. -## 🔧 Configuring the time sources {#configuring-the-time-sources} +## Configuring the time sources {#configuring-the-time-sources} ### During installation @@ -80,7 +80,7 @@ field in the XOA deployment form does the same for the appliance being deployed. touches the chrony configuration of the hosts XO manages. ::: -## 🔍 Checking the time sources {#checking-the-time-sources} +## Checking the time sources {#checking-the-time-sources} Check that the service is running, and that it actually has something to synchronize with: @@ -136,7 +136,7 @@ To see the offset chrony believes it has, and whether it has settled: chronyc tracking ``` -## 🛠️ Correcting a wrong clock {#correcting-a-wrong-clock} +## Correcting a wrong clock {#correcting-a-wrong-clock} A host with working time sources does not usually have a wrong clock, because chronyd steps it within seconds of starting. So a clock that is still wrong is telling you that something @@ -221,7 +221,7 @@ dead and should be replaced. `rtcsync` can only keep the hardware clock in step host is running; it cannot help a clock that loses its value when the power goes. ::: -## 🌐 Networks without internet access {#networks-without-internet-access} +## Networks without internet access {#networks-without-internet-access} Hosts without Internet access cannot reach the public NTP pool. The result is the same as having no sources at all: `chronyc sources` lists servers that never leave the `?` state. From 1dbc53c179e009df65340a1820216915c25c36f4 Mon Sep 17 00:00:00 2001 From: Bruno Verachten Date: Mon, 17 Aug 2026 15:22:35 +0200 Subject: [PATCH 8/8] Link the cross-references into their sentences Review noted that "See X" sat disconnected from the sentence before it, and that the same shape recurred across the page. All five now carry the connection in the sentence rather than leaving the reader to infer it: Pool Requirements what else a host must meet before it can join Install XCP-ng where this falls in the installation sequence Checking the time how to recognise that state on a running host Answer file its syntax Networks without folded into the clause about no route to the pool Two other uses of "see" on the page are ordinary verbs, "to see the offset" and "the certificate clients see", and are left alone. No link targets or anchors change. Signed-off-by: Bruno Verachten --- docs/management/time-synchronization.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/management/time-synchronization.md b/docs/management/time-synchronization.md index 71f7a5af..9493354e 100644 --- a/docs/management/time-synchronization.md +++ b/docs/management/time-synchronization.md @@ -19,7 +19,8 @@ to configure NTP, and how to check and correct it. master, and must stay synchronized afterwards. A failed join tells you what is wrong. Drift that sets in later does not: it surfaces as hosts disagreeing about when things happened, each of them convinced by its own clock. Keep every host in a pool on the same time sources. - See [Pool Requirements](../../installation/requirements#pool-requirements). + See [Pool Requirements](../../installation/requirements#pool-requirements) for the other + conditions a host has to meet before it can join. - **Certificates.** Certificates are only valid inside a validity window. A host whose date falls outside that window will reject, or be rejected by, connections that would otherwise succeed. @@ -50,21 +51,23 @@ had no time source to begin with. ### During installation The installer prompts you to enter the time, select a time zone, and either configure NTP -servers or set the time manually. Always configure at least one NTP server. See -[Install XCP-ng](../../installation/install-xcp-ng). +servers or set the time manually. Always configure at least one NTP server (see +[Install XCP-ng](../../installation/install-xcp-ng) for where this falls in the installation +sequence). :::warning If you set the time manually at this step, the host can end up with `chronyd` running but no time source configured at all. The clock still ticks, but nothing ever checks it: it drifts from the date you typed, and if that date was wrong, it stays wrong. This is also the one case that does not fix itself at boot, since `makestep` needs a source to measure against. -See [Checking the time sources](#checking-the-time-sources) below. +[Checking the time sources](#checking-the-time-sources) below shows how to recognise that +state on a running host. ::: ### During an automated installation The installation answer file accepts one or more NTP servers through the `` -element. See [Answer file](../../appendix/answerfile). +element (see [Answer file](../../appendix/answerfile) for its syntax). ### On an installed host @@ -149,8 +152,8 @@ Work outward, from the configuration to the network: ever configured, which is the manual-time-at-install case. Add them with `xsconsole`. 2. **Are they reachable?** Sources stuck at `?` are configured but unanswered. NTP goes out over UDP 123, so a firewall between the host and its servers produces exactly this, as - does a network with no route to the public pool. See - [Networks without internet access](#networks-without-internet-access). + does a network with no route to the public pool, which + [Networks without internet access](#networks-without-internet-access) below covers. 3. **Is the daemon healthy?** `systemctl status chronyd`, and `journalctl -u chronyd` for what it made of its configuration at startup. 4. **Was the configuration changed underneath you?** `rpm -V chrony` reports whether