1Recommendations for KVM CPU model configuration on x86 hosts
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4The information that follows provides recommendations for configuring
5CPU models on x86 hosts. The goals are to maximise performance, while
6protecting guest OS against various CPU hardware flaws, and optionally
7enabling live migration between hosts with heterogeneous CPU models.
8
9
10Two ways to configure CPU models with QEMU / KVM
11^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12
13(1) **Host passthrough**
14
15    This passes the host CPU model features, model, stepping, exactly to
16    the guest. Note that KVM may filter out some host CPU model features
17    if they cannot be supported with virtualization. Live migration is
18    unsafe when this mode is used as libvirt / QEMU cannot guarantee a
19    stable CPU is exposed to the guest across hosts. This is the
20    recommended CPU to use, provided live migration is not required.
21
22(2) **Named model**
23
24    QEMU comes with a number of predefined named CPU models, that
25    typically refer to specific generations of hardware released by
26    Intel and AMD.  These allow the guest VMs to have a degree of
27    isolation from the host CPU, allowing greater flexibility in live
28    migrating between hosts with differing hardware.  @end table
29
30In both cases, it is possible to optionally add or remove individual CPU
31features, to alter what is presented to the guest by default.
32
33Libvirt supports a third way to configure CPU models known as "Host
34model".  This uses the QEMU "Named model" feature, automatically picking
35a CPU model that is similar the host CPU, and then adding extra features
36to approximate the host model as closely as possible. This does not
37guarantee the CPU family, stepping, etc will precisely match the host
38CPU, as they would with "Host passthrough", but gives much of the
39benefit of passthrough, while making live migration safe.
40
41
42Preferred CPU models for Intel x86 hosts
43^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44
45The following CPU models are preferred for use on Intel hosts.
46Administrators / applications are recommended to use the CPU model that
47matches the generation of the host CPUs in use. In a deployment with a
48mixture of host CPU models between machines, if live migration
49compatibility is required, use the newest CPU model that is compatible
50across all desired hosts.
51
52``Skylake-Server``, ``Skylake-Server-IBRS``
53    Intel Xeon Processor (Skylake, 2016)
54
55``Skylake-Client``, ``Skylake-Client-IBRS``
56    Intel Core Processor (Skylake, 2015)
57
58``Broadwell``, ``Broadwell-IBRS``, ``Broadwell-noTSX``, ``Broadwell-noTSX-IBRS``
59    Intel Core Processor (Broadwell, 2014)
60
61``Haswell``, ``Haswell-IBRS``, ``Haswell-noTSX``, ``Haswell-noTSX-IBRS``
62    Intel Core Processor (Haswell, 2013)
63
64``IvyBridge``, ``IvyBridge-IBR``
65    Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
66
67``SandyBridge``, ``SandyBridge-IBRS``
68    Intel Xeon E312xx (Sandy Bridge, 2011)
69
70``Westmere``, ``Westmere-IBRS``
71    Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
72
73``Nehalem``, ``Nehalem-IBRS``
74    Intel Core i7 9xx (Nehalem Class Core i7, 2008)
75
76``Penryn``
77    Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
78
79``Conroe``
80    Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
81
82
83Important CPU features for Intel x86 hosts
84^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85
86The following are important CPU features that should be used on Intel
87x86 hosts, when available in the host CPU. Some of them require explicit
88configuration to enable, as they are not included by default in some, or
89all, of the named CPU models listed above. In general all of these
90features are included if using "Host passthrough" or "Host model".
91
92``pcid``
93  Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix.
94
95  Included by default in Haswell, Broadwell & Skylake Intel CPU models.
96
97  Should be explicitly turned on for Westmere, SandyBridge, and
98  IvyBridge Intel CPU models. Note that some desktop/mobile Westmere
99  CPUs cannot support this feature.
100
101``spec-ctrl``
102  Required to enable the Spectre v2 (CVE-2017-5715) fix.
103
104  Included by default in Intel CPU models with -IBRS suffix.
105
106  Must be explicitly turned on for Intel CPU models without -IBRS
107  suffix.
108
109  Requires the host CPU microcode to support this feature before it
110  can be used for guest CPUs.
111
112``stibp``
113  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
114  operating systems.
115
116  Must be explicitly turned on for all Intel CPU models.
117
118  Requires the host CPU microcode to support this feature before it can
119  be used for guest CPUs.
120
121``ssbd``
122  Required to enable the CVE-2018-3639 fix.
123
124  Not included by default in any Intel CPU model.
125
126  Must be explicitly turned on for all Intel CPU models.
127
128  Requires the host CPU microcode to support this feature before it
129  can be used for guest CPUs.
130
131``pdpe1gb``
132  Recommended to allow guest OS to use 1GB size pages.
133
134  Not included by default in any Intel CPU model.
135
136  Should be explicitly turned on for all Intel CPU models.
137
138  Note that not all CPU hardware will support this feature.
139
140``md-clear``
141  Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127,
142  CVE-2018-12130, CVE-2019-11091) fixes.
143
144  Not included by default in any Intel CPU model.
145
146  Must be explicitly turned on for all Intel CPU models.
147
148  Requires the host CPU microcode to support this feature before it
149  can be used for guest CPUs.
150
151
152Preferred CPU models for AMD x86 hosts
153^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
154
155The following CPU models are preferred for use on Intel hosts.
156Administrators / applications are recommended to use the CPU model that
157matches the generation of the host CPUs in use. In a deployment with a
158mixture of host CPU models between machines, if live migration
159compatibility is required, use the newest CPU model that is compatible
160across all desired hosts.
161
162``EPYC``, ``EPYC-IBPB``
163    AMD EPYC Processor (2017)
164
165``Opteron_G5``
166    AMD Opteron 63xx class CPU (2012)
167
168``Opteron_G4``
169    AMD Opteron 62xx class CPU (2011)
170
171``Opteron_G3``
172    AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
173
174``Opteron_G2``
175    AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
176
177``Opteron_G1``
178    AMD Opteron 240 (Gen 1 Class Opteron, 2004)
179
180
181Important CPU features for AMD x86 hosts
182^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183
184The following are important CPU features that should be used on AMD x86
185hosts, when available in the host CPU. Some of them require explicit
186configuration to enable, as they are not included by default in some, or
187all, of the named CPU models listed above. In general all of these
188features are included if using "Host passthrough" or "Host model".
189
190``ibpb``
191  Required to enable the Spectre v2 (CVE-2017-5715) fix.
192
193  Included by default in AMD CPU models with -IBPB suffix.
194
195  Must be explicitly turned on for AMD CPU models without -IBPB suffix.
196
197  Requires the host CPU microcode to support this feature before it
198  can be used for guest CPUs.
199
200``stibp``
201  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
202  operating systems.
203
204  Must be explicitly turned on for all AMD CPU models.
205
206  Requires the host CPU microcode to support this feature before it
207  can be used for guest CPUs.
208
209``virt-ssbd``
210  Required to enable the CVE-2018-3639 fix
211
212  Not included by default in any AMD CPU model.
213
214  Must be explicitly turned on for all AMD CPU models.
215
216  This should be provided to guests, even if amd-ssbd is also provided,
217  for maximum guest compatibility.
218
219  Note for some QEMU / libvirt versions, this must be force enabled when
220  when using "Host model", because this is a virtual feature that
221  doesn't exist in the physical host CPUs.
222
223``amd-ssbd``
224  Required to enable the CVE-2018-3639 fix
225
226  Not included by default in any AMD CPU model.
227
228  Must be explicitly turned on for all AMD CPU models.
229
230  This provides higher performance than ``virt-ssbd`` so should be
231  exposed to guests whenever available in the host. ``virt-ssbd`` should
232  none the less also be exposed for maximum guest compatibility as some
233  kernels only know about ``virt-ssbd``.
234
235``amd-no-ssb``
236  Recommended to indicate the host is not vulnerable CVE-2018-3639
237
238  Not included by default in any AMD CPU model.
239
240  Future hardware generations of CPU will not be vulnerable to
241  CVE-2018-3639, and thus the guest should be told not to enable
242  its mitigations, by exposing amd-no-ssb. This is mutually
243  exclusive with virt-ssbd and amd-ssbd.
244
245``pdpe1gb``
246  Recommended to allow guest OS to use 1GB size pages
247
248  Not included by default in any AMD CPU model.
249
250  Should be explicitly turned on for all AMD CPU models.
251
252  Note that not all CPU hardware will support this feature.
253
254
255Default x86 CPU models
256^^^^^^^^^^^^^^^^^^^^^^
257
258The default QEMU CPU models are designed such that they can run on all
259hosts.  If an application does not wish to do perform any host
260compatibility checks before launching guests, the default is guaranteed
261to work.
262
263The default CPU models will, however, leave the guest OS vulnerable to
264various CPU hardware flaws, so their use is strongly discouraged.
265Applications should follow the earlier guidance to setup a better CPU
266configuration, with host passthrough recommended if live migration is
267not needed.
268
269``qemu32``, ``qemu64``
270    QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
271
272``qemu64`` is used for x86_64 guests and ``qemu32`` is used for i686
273guests, when no ``-cpu`` argument is given to QEMU, or no ``<cpu>`` is
274provided in libvirt XML.
275
276Other non-recommended x86 CPUs
277^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
278
279The following CPUs models are compatible with most AMD and Intel x86
280hosts, but their usage is discouraged, as they expose a very limited
281featureset, which prevents guests having optimal performance.
282
283``kvm32``, ``kvm64``
284    Common KVM processor (32 & 64 bit variants).
285
286    Legacy models just for historical compatibility with ancient QEMU
287    versions.
288
289``486``, ``athlon``, ``phenom``, ``coreduo``, ``core2duo``, ``n270``, ``pentium``, ``pentium2``, ``pentium3``
290    Various very old x86 CPU models, mostly predating the introduction
291    of hardware assisted virtualization, that should thus not be
292    required for running virtual machines.
293
294
295Syntax for configuring CPU models
296~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297
298The examples below illustrate the approach to configuring the various
299CPU models / features in QEMU and libvirt.
300
301QEMU command line
302^^^^^^^^^^^^^^^^^
303
304Host passthrough:
305
306.. parsed-literal::
307
308  |qemu_system| -cpu host
309
310Host passthrough with feature customization:
311
312.. parsed-literal::
313
314  |qemu_system| -cpu host,-vmx,...
315
316Named CPU models:
317
318.. parsed-literal::
319
320  |qemu_system| -cpu Westmere
321
322Named CPU models with feature customization:
323
324.. parsed-literal::
325
326  |qemu_system| -cpu Westmere,+pcid,...
327
328Libvirt guest XML
329^^^^^^^^^^^^^^^^^
330
331Host passthrough::
332
333    <cpu mode='host-passthrough'/>
334
335Host passthrough with feature customization::
336
337    <cpu mode='host-passthrough'>
338        <feature name="vmx" policy="disable"/>
339        ...
340    </cpu>
341
342Host model::
343
344    <cpu mode='host-model'/>
345
346Host model with feature customization::
347
348    <cpu mode='host-model'>
349        <feature name="vmx" policy="disable"/>
350        ...
351    </cpu>
352
353Named model::
354
355    <cpu mode='custom'>
356        <model name="Westmere"/>
357    </cpu>
358
359Named model with feature customization::
360
361    <cpu mode='custom'>
362        <model name="Westmere"/>
363        <feature name="pcid" policy="require"/>
364        ...
365    </cpu>
366