20.15. 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. Note that for Windows guest virtual machines the guest virtual machine must be set in localtime.

  ...
  <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 20.21. Timekeeping

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

Table 20.12. Time keeping elements

StateDescription
<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 timezone using the timezone attribute.
  • 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
<frequency> This is an unsigned integer specifying the frequency at which name="tsc" runs.
<mode>The mode attribute controls how the name="tsc" <timer> is managed, and can be set to: auto, native, emulate, paravirt, or smpsafe. Other timers are always emulated.
<present>Specifies whether a particular timer is available to the guest virtual machine. Can be set to yes or no

Note

Each <timer> element must contain a name attribute, and may have the following attributes depending on the name specified.
  • <name> - selects which timer is being modified. The following values are acceptable:kvmclock (QEMU-KVM), pit(QEMU-KVM), or rtc(QEMU-KVM), or tsc(libxl only). Note that platform is currently unsupported.
  • 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 whens the deadline for injecting a tick to the guest virtual machine is missed. The following values can be assigned:
    • delay -will continue 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 catchup is complete. In addition, there can be three optional attributes, each a positive integer, as follows: 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