8.10. Virtual Machine Timer Management with libvirt

Accurate time keeping on guest virtual machines is a key challenge for virtualization platforms. Different hypervisors attempt to handle the problem of time keeping 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. See Section 14.6, “Editing a Guest Virtual Machine's configuration file” for details.
The <clock> element is used to determine how the guest virtual machine clock is synchronized with the host physical machine clock. The clock element has the following attributes:
  • offset determines how the guest virtual machine clock is offset from the host physical machine clock. The offset attribute has the following possible values:

    Table 8.1. Offset attribute values

    ValueDescription
    utcThe guest virtual machine clock will be synchronized to UTC when booted.
    localtimeThe guest virtual machine clock will be synchronized to the host physical machine's configured timezone when booted, if any.
    timezoneThe guest virtual machine clock will be synchronized to a given timezone, specified by the timezone attribute.
    variableThe guest virtual machine clock will be synchronized to an arbitrary offset from UTC. The delta relative to UTC is specified in seconds, using the adjustment attribute. The guest virtual machine is free to adjust the Real Time Clock (RTC) over time and expect that it will be honored following the next reboot. This is in contrast to utc mode, where any RTC adjustments are lost at each reboot.

    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.
  • The timezone attribute determines which timezone is used for the guest virtual machine clock.
  • The adjustment attribute provides the delta for guest virtual machine clock synchronization. In seconds, relative to UTC.

Example 8.1. Always synchronize to UTC

<clock offset="utc" />

Example 8.2. Always synchronize to the host physical machine timezone

<clock offset="localtime" />

Example 8.3. Synchronize to an arbitrary timezone

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

Example 8.4. Synchronize to UTC + arbitrary offset

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

8.10.1. timer Child Element for clock

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. The timer element has the following attributes. Only the name is required, all other attributes are optional.
The name attribute dictates the type of the time source to use, and can be one of the following:

Table 8.2. name attribute values

ValueDescription
pitProgrammable Interval Timer - a timer with periodic interrupts.
rtcReal Time Clock - a continuously running timer with periodic interrupts.
tscTime Stamp Counter - counts the number of ticks since reset, no interrupts.
kvmclockKVM clock - recommended clock source for KVM guest virtual machines. KVM pvclock, or kvm-clock lets guest virtual machines read the host physical machine’s wall clock time.