23.16. Timekeeping

The guest virtual machine clock is typically initialized from the host physical machine clock. Most operating systems expect the hardware clock to be kept in UTC, which is the default setting.
Accurate timekeeping on guest virtual machines is a key challenge for virtualization platforms. Different hypervisors attempt to handle the problem of timekeeping in a variety of ways. libvirt provides hypervisor-independent configuration settings for time management, using the <clock> and <timer> elements in the domain XML. The domain XML can be edited using the virsh edit command. For details, see Section 20.22, “Editing a Guest Virtual Machine's XML Configuration Settings”. 

  ...
  <clock offset='localtime'>
    <timer name='rtc' tickpolicy='catchup' track='guest'>
      <catchup threshold='123' slew='120' limit='10000'/>
    </timer>
    <timer name='pit' tickpolicy='delay'/>
  </clock>
  ...

Figure 23.26. Timekeeping

The components of this section of the domain XML are as follows:

Table 23.11. Timekeeping elements

State Description
<clock> The <clock> element is used to determine how the guest virtual machine clock is synchronized with the host physical machine clock. The offset attribute takes four possible values, allowing for fine grained control over how the guest virtual machine clock is synchronized to the host physical machine. Note that hypervisors are not required to support all policies across all time sources
  • utc - Synchronizes the clock to UTC when booted. utc mode can be converted to variable mode, which can be controlled by using the adjustment attribute. If the value is reset, the conversion is not done. A numeric value forces the conversion to variable mode using the value as the initial adjustment. The default adjustment is hypervisor-specific.
  • localtime - Synchronizes the guest virtual machine clock with the host physical machine's configured timezone when booted. The adjustment attribute behaves the same as in utc mode.
  • timezone - Synchronizes the guest virtual machine clock to the requested time zone.
  • variable - Gives the guest virtual machine clock an arbitrary offset applied relative to UTC or localtime, depending on the basis attribute. The delta relative to UTC (or localtime) is specified in seconds, using the adjustment attribute. The guest virtual machine is free to adjust the RTC over time and expect that it will be honored at next reboot. This is in contrast to utc and localtime mode (with the optional attribute adjustment='reset'), where the RTC adjustments are lost at each reboot. In addition, the basis attribute can be either utc (default) or localtime. The clock element may have zero or more <timer> elements.
<timer> See Note
<present> Specifies whether a particular timer is available to the guest virtual machine. Can be set to yes or no.

Note

A <clock> element can have zero or more <timer> elements as children. The <timer> element specifies a time source used for guest virtual machine clock synchronization.
In each <timer> element only the name is required, and all other attributes are optional:
  • name - Selects which timer is being modified. The following values are acceptable: kvmclock, pit, or rtc.
  • track - Specifies the timer track. The following values are acceptable: boot, guest, or wall. track is only valid for name="rtc".
  • tickpolicy - Determines what happens when the deadline for injecting a tick to the guest virtual machine is missed. The following values can be assigned:
    • delay - Continues to deliver ticks at the normal rate. The guest virtual machine time will be delayed due to the late tick.
    • catchup - Delivers ticks at a higher rate in order to catch up with the missed tick. The guest virtual machine time is not displayed once catch up is complete. In addition, there can be three optional attributes, each a positive integer: threshold, slew, and limit.
    • merge - Merges the missed tick(s) into one tick and injects them. The guest virtual machine time may be delayed, depending on how the merge is done.
    • discard - Throws away the missed tick(s) and continues with future injection at its default interval setting. The guest virtual machine time may be delayed, unless there is an explicit statement for handling lost ticks.

Note

The value utc is set as the clock offset in a virtual machine by default. However, if the guest virtual machine clock is run with the localtime value, the clock offset needs to be changed to a different value in order to have the guest virtual machine clock synchronized with the host physical machine clock.

Example 23.1. Always synchronize to UTC

<clock offset="utc" />

Example 23.2. Always synchronize to the host physical machine timezone

<clock offset="localtime" />

Example 23.3. Synchronize to an arbitrary time zone

<clock offset="timezone" timezone="Europe/Paris" />

Example 23.4. Synchronize to UTC + arbitrary offset

<clock offset="variable" adjustment="123456" />