Red Hat Enterprise Linux 9 Essentials Book now available.
Purchase a copy of Red Hat Enterprise Linux 9 (RHEL 9) Essentials
Red Hat Enterprise Linux 9 Essentials Print and eBook (PDF) editions contain 34 chapters and 298 pages
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
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
