virt-what.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-what - detect if we are running in a virtual machine
   6
   7 =head1 SUMMARY
   8
   9 virt-what [options]
  10
  11 =head1 DESCRIPTION
  12
  13 C<virt-what> is a shell script which can be used to detect if the
  14 program is running in a virtual machine.
  15
  16 The program prints out a list of "facts" about the virtual machine,
  17 derived from heuristics.  One fact is printed per line.
  18
  19 If nothing is printed and the script exits with code 0 (no error),
  20 then it can mean I<either> that the program is running on bare-metal
  21 I<or> the program is running inside a type of virtual machine which we
  22 don't know about or cannot detect.
  23
  24 =head1 FACTS
  25
  26 =over 4
  27
  28 =item B<docker>
  29
  30 This is a Docker container.
  31
  32 Status: confirmed by Charles Nguyen
  33
  34 =item B<hyperv>
  35
  36 This is Microsoft Hyper-V hypervisor.
  37
  38 Status: confirmed by RWMJ
  39
  40 =item B<ibm_systemz>
  41
  42 This is an IBM SystemZ (or other S/390) hardware partitioning system.
  43 Additional facts listed below may also be printed.
  44
  45 =item B<ibm_systemz-direct>
  46
  47 This is Linux running directly on a IBM SystemZ hardware partitioning
  48 system.
  49
  50 This is expected to be a highly unusual configuration - if
  51 you see this result you should treat it with suspicion.
  52
  53 Status: not confirmed
  54
  55 =item B<ibm_systemz-lpar>
  56
  57 This is Linux running directly on an LPAR on an IBM SystemZ
  58 hardware partitioning system.
  59
  60 Status: not confirmed
  61
  62 =item B<ibm_systemz-zvm>
  63
  64 This is a z/VM guest running in an LPAR on an IBM SystemZ
  65 hardware partitioning system.
  66
  67 Status: confirmed by RWMJ using a Fedora guest running in z/VM
  68
  69 =item B<linux_vserver>
  70
  71 This is printed for backwards compatibility with older virt-what which
  72 could not distinguish between a Linux VServer container guest and
  73 host.
  74
  75 =item B<linux_vserver-guest>
  76
  77 This process is running in a Linux VServer container.
  78
  79 Status: contributed by Barış Metin
  80
  81 =item B<linux_vserver-host>
  82
  83 This process is running as the Linux VServer host (VxID 0).
  84
  85 Status: contributed by Barış Metin and Elan Ruusamäe
  86
  87 =item B<lxc>
  88
  89 This process is running in a Linux LXC container.
  90
  91 Status: contributed by Marc Fournier
  92
  93 =item B<kvm>
  94
  95 This guest is running on the KVM hypervisor using hardware
  96 acceleration.
  97
  98 Note that if the hypervisor is using software acceleration
  99 you should I<not> see this, but should see the C<qemu> fact
 100 instead.
 101
 102 Status: confirmed by RWMJ.
 103
 104 =item B<openvz>
 105
 106 The guest appears to be running inside an OpenVZ or Virtuozzo
 107 container.
 108
 109 Status: contributed by Evgeniy Sokolov
 110
 111 =item B<parallels>
 112
 113 The guest is running inside Parallels Virtual Platform
 114 (Parallels Desktop, Parallels Server).
 115
 116 Status: contributed by Justin Clift
 117
 118 =item B<powervm_lx86>
 119
 120 The guest is running inside IBM PowerVM Lx86 Linux/x86 emulator.
 121
 122 Status: data originally supplied by Jeffrey Scheel, confirmed by
 123 Yufang Zhang and RWMJ
 124
 125 =item B<qemu>
 126
 127 This is QEMU hypervisor using software emulation.
 128
 129 Note that for KVM (hardware accelerated) guests you should I<not> see
 130 this.
 131
 132 Status: confirmed by RWMJ.
 133
 134 =item B<uml>
 135
 136 This is a User-Mode Linux (UML) guest.
 137
 138 Status: contributed by Laurent Léonard
 139
 140 =item B<virt>
 141
 142 Some sort of virtualization appears to be present, but we are not sure
 143 what it is.  In some very rare corner cases where we know that
 144 virtualization is hard to detect, we will try a timing attack to see
 145 if certain machine instructions are running much more slowly than they
 146 should be, which would indicate virtualization.  In this case, the
 147 generic fact C<virt> is printed.
 148
 149 =item B<virtage>
 150
 151 This is Hitachi Virtualization Manager (HVM) Virtage
 152 hardware partitioning system.
 153
 154 Status: data supplied by Bhavna Sarathy, not confirmed
 155
 156 =item B<virtualbox>
 157
 158 This is a VirtualBox guest.
 159
 160 Status: contributed by Laurent Léonard
 161
 162 =item B<virtualpc>
 163
 164 The guest appears to be running on Microsoft VirtualPC.
 165
 166 Status: not confirmed
 167
 168 =item B<vmware>
 169
 170 The guest appears to be running on VMware hypervisor.
 171
 172 Status: confirmed by RWMJ
 173
 174 =item B<xen>
 175
 176 The guest appears to be running on Xen hypervisor.
 177
 178 Status: confirmed by RWMJ
 179
 180 =item B<xen-dom0>
 181
 182 This is the Xen dom0 (privileged domain).
 183
 184 Status: confirmed by RWMJ
 185
 186 =item B<xen-domU>
 187
 188 This is a Xen domU (paravirtualized guest domain).
 189
 190 Status: confirmed by RWMJ
 191
 192 =item B<xen-hvm>
 193
 194 This is a Xen guest fully virtualized (HVM).
 195
 196 Status: confirmed by RWMJ
 197
 198 =back
 199
 200 =head1 EXIT STATUS
 201
 202 Programs that use or wrap C<virt-what> should check that the exit
 203 status is 0 before they attempt to parse the output of the command.
 204
 205 A non-zero exit status indicates some error, for example, an
 206 unrecognized command line argument.  If the exit status is non-zero
 207 then the output "facts" (if any were printed) cannot be guaranteed and
 208 should be ignored.
 209
 210 The exit status does I<not> have anything to do with whether the
 211 program is running on baremetal or under virtualization, nor with
 212 whether C<virt-what> managed detection "correctly" (which is basically
 213 unknowable given the large variety of virtualization systems out there
 214 and that some systems deliberately emulate others).
 215
 216 =head1 RUNNING VIRT-WHAT FROM OTHER PROGRAMS
 217
 218 C<virt-what> is designed so that you can easily run it from
 219 other programs or wrap it up in a library.
 220
 221 Your program should check the exit status (see the section above).
 222
 223 Some programming languages (notably Python: issue 1652) erroneously
 224 mask the C<SIGPIPE> signal and do not restore it when executing
 225 subprocesses.  C<virt-what> is a shell script and some shell commands
 226 do not work correctly when you do this.  You may see warnings from
 227 C<virt-what> similar to this:
 228
 229  echo: write error: Broken pipe
 230
 231 The solution is to set the C<SIGPIPE> signal handler back to C<SIG_DFL>
 232 before running C<virt-what>.
 233
 234 =head1 IMPORTANT NOTE
 235
 236 Most of the time, using this program is the I<wrong> thing to do.
 237 Instead you should detect the specific features you actually want to
 238 use.  (As an example, if you wanted to issue Xen hypervisor commands
 239 you would look for the C</proc/xen/privcmd> file).
 240
 241 However people keep asking for this, so we provide it.  There are a
 242 few legitimate uses:
 243
 244 =over 4
 245
 246 =item Bug reporting tool
 247
 248 If you think that virtualization could affect how your program runs,
 249 then you might use C<virt-what> to report this in a bug reporting
 250 tool.
 251
 252 =item Status display and monitoring tools
 253
 254 You might include this information in status and monitoring programs.
 255
 256 =item System tuning (sometimes)
 257
 258 You might use this program to tune an operating system so it runs
 259 better as a virtual machine of a particular hypervisor.  However if
 260 installing paravirtualized drivers, it's better to check for the
 261 specific features your drivers need (eg. for the presence of PCI devices).
 262
 263 =back
 264
 265 =head1 SEE ALSO
 266
 267 L<http://people.redhat.com/~rjones/virt-what/>,
 268 L<http://www.vmware.com/>,
 269 L<http://www.microsoft.com/windows/products/winfamily/virtualpc>,
 270 L<http://xensource.com/>,
 271 L<http://bellard.org/qemu/>,
 272 L<http://kvm.qumranet.com/>,
 273 L<http://openvz.org/>
 274
 275 =head1 AUTHORS
 276
 277 Richard W.M. Jones <rjones @ redhat . com>
 278
 279 =head1 COPYRIGHT
 280
 281 (C) Copyright 2008-2011 Red Hat Inc.,
 282 L<http://people.redhat.com/~rjones/virt-what/>
 283
 284 This program is free software; you can redistribute it and/or modify
 285 it under the terms of the GNU General Public License as published by
 286 the Free Software Foundation; either version 2 of the License, or
 287 (at your option) any later version.
 288
 289 This program is distributed in the hope that it will be useful,
 290 but WITHOUT ANY WARRANTY; without even the implied warranty of
 291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 292 GNU General Public License for more details.
 293
 294 You should have received a copy of the GNU General Public License
 295 along with this program; if not, write to the Free Software
 296 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 297
 298 =head1 REPORTING BUGS
 299
 300 Bugs can be viewed on the Red Hat Bugzilla page:
 301 L<https://bugzilla.redhat.com/>.
 302
 303 If you find a bug in virt-what, please follow these steps to report it:
 304
 305 =over 4
 306
 307 =item 1. Check for existing bug reports
 308
 309 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 310 Someone may already have reported the same bug, and they may even
 311 have fixed it.
 312
 313 =item 2. Capture debug and error messages
 314
 315 Run
 316
 317  virt-what > virt-what.log 2>&1
 318
 319 and keep I<virt-what.log>.  It may contain error messages which you
 320 should submit with your bug report.
 321
 322 =item 3. Get version of virt-what.
 323
 324 Run
 325
 326  virt-what --version
 327
 328 =item 4. Submit a bug report.
 329
 330 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 331 Please describe the problem in as much detail as possible.
 332
 333 Remember to include the version numbers (step 3) and the debug
 334 messages file (step 2) and as much other detail as possible.
 335
 336 =item 5. Assign the bug to rjones @ redhat.com
 337
 338 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 339 spaces).  You can also send me an email with the bug number if you
 340 want a faster response.
 341
 342 =back