24.11. Virtual machine timer management with libvirt

Accurate time keeping on virtualized guests 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. Note that not all options are supported for all hypervisors. The domain XML can be edited using the virsh edit command. See Editing a guest's configuration file for details.

<clock>

The clock element is used to determine how the guest clock is synchronized with the host clock. The clock element has the following attributes:

offset

Determines how the guest clock is offset from the host clock. The offset attribute has the following possible values:

Table 24.1. Offset attribute values

Value	Description
utc	The guest clock will be synchronized to UTC when booted.
localtime	The guest clock will be synchronized to the host's configured timezone when booted, if any.
timezone	The guest clock will be synchronized to a given timezone, specified by the `timezone` attribute.
variable	The guest 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 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.

timezone
The timezone to which the guest clock is to be synchronized.
adjustment
The delta for guest clock synchronization. In seconds, relative to UTC.

Example 24.1. Always synchronize to UTC

<clock offset="utc" />

Example 24.2. Always synchronize to the host timezone

<clock offset="localtime" />

Example 24.3. Synchronize to an arbitrary timezone

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

Example 24.4. Synchronize to UTC + arbitrary offset

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

<timer>

A clock element can have zero or more timer elements as children. The timer element specifies a time source used for guest clock synchronization. The timer element has the following attributes. Only the name is required, all other attributes are optional.

name

The name of the time source to use.

Table 24.2. name attribute values

Value	Description
platform	The master virtual time source which may be used to drive the policy of other time sources.
pit	Programmable Interval Timer - a timer with periodic interrupts.
rtc	Real Time Clock - a continuously running timer with periodic interrupts.
hpet	High Precision Event Timer - multiple timers with periodic interrupts.
tsc	Time Stamp Counter - counts the number of ticks since reset, no interrupts.

wallclock

Specifies whether the wallclock should track host or guest time. Only valid for a name value of platform or rtc.

Table 24.3. wallclock attribute values

Value	Description
host	RTC wallclock always tracks host time.
guest	RTC wallclock always tracks guest time.

tickpolicy

The policy used to pass ticks on to the guest.

Table 24.4. tickpolicy attribute values

Value	Description
none	Continue to deliver at normal rate (i.e. ticks are delayed).
catchup	Deliver at a higher rate to catch up.
merge	Ticks merged into one single tick.
discard	All missed ticks are discarded.

frequency
Used to set a fixed frequency, measured in Hz. This attribute is only relevant for a name value of tsc. All other timers operate at a fixed frequency (pit, rtc), or at a frequency fully controlled by the guest (hpet).

mode

Determines how the time source is exposed to the guest. This attribute is only relevant for a name value of tsc. All other timers are always emulated.

Table 24.5. mode attribute values

Value	Description
auto	Native if safe, otherwise emulated.
native	Always native.
emulate	Always emulate.
paravirt	Native + para-virtualized.

present

Used to override the default set of timers visible to the guest. For example, to enable or disable the HPET.

Table 24.6. present attribute values

Value	Description
yes	Force this timer to the visible to the guest.
no	Force this timer to not be visible to the guest.

Example 24.5. Clock synchronizing to local time with RTC and PIT timers, and the HPET timer disabled

<clock mode="localtime">
	<timer name="rtc" tickpolicy="catchup" wallclock="guest" />
	<timer name="pit" tickpolicy="none" />
	<timer name="hpet" present="no" />
</clock>