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<hyperv>
  29
  30 This is Microsoft Hyper-V hypervisor.
  31
  32 Status: confirmed by RWMJ
  33
  34 =item B<ibm_systemz>
  35
  36 This is an IBM SystemZ (or other S/390) hardware partitioning system.
  37 Additional facts listed below may also be printed.
  38
  39 =item B<ibm_systemz-direct>
  40
  41 This is Linux running directly on a IBM SystemZ hardware partitioning
  42 system.
  43
  44 This is expected to be a highly unusual configuration - if
  45 you see this result you should treat it with suspicion.
  46
  47 Status: not confirmed
  48
  49 =item B<ibm_systemz-lpar>
  50
  51 This is Linux running directly on an LPAR on an IBM SystemZ
  52 hardware partitioning system.
  53
  54 Status: not confirmed
  55
  56 =item B<ibm_systemz-zvm>
  57
  58 This is a z/VM guest running in an LPAR on an IBM SystemZ
  59 hardware partitioning system.
  60
  61 Status: confirmed by RWMJ using a Fedora guest running in z/VM
  62
  63 =item B<linux_vserver>
  64
  65 This process is running in a Linux VServer container.
  66
  67 Status: contributed by Barış Metin
  68
  69 =item B<kvm>
  70
  71 This guest is running on the KVM hypervisor using hardware
  72 acceleration.
  73
  74 Note that if the hypervisor is using software acceleration
  75 you should I<not> see this, but should see the C<qemu> fact
  76 instead.
  77
  78 Status: confirmed by RWMJ.
  79
  80 =item B<openvz>
  81
  82 The guest appears to be running inside an OpenVZ or Virtuozzo
  83 container.
  84
  85 Status: contributed by Evgeniy Sokolov
  86
  87 =item B<parallels>
  88
  89 The guest is running inside Parallels Virtual Platform
  90 (Parallels Desktop, Parallels Server).
  91
  92 Status: contributed by Justin Clift
  93
  94 =item B<powervm_lx86>
  95
  96 The guest is running inside IBM PowerVM Lx86 Linux/x86 emulator.
  97
  98 Status: data supplied by Jeffrey Scheel, not confirmed
  99
 100 =item B<qemu>
 101
 102 This is QEMU hypervisor using software emulation.
 103
 104 Note that for KVM (hardware accelerated) guests you should I<not> see
 105 this.
 106
 107 Status: confirmed by RWMJ.
 108
 109 =item B<uml>
 110
 111 This is a User-Mode Linux (UML) guest.
 112
 113 Status: contributed by Laurent Léonard
 114
 115 =item B<virtage>
 116
 117 This is Hitachi Virtualization Manager (HVM) Virtage
 118 hardware partitioning system.
 119
 120 Status: data supplied by Bhavna Sarathy, not confirmed
 121
 122 =item B<virtualbox>
 123
 124 This is a VirtualBox guest.
 125
 126 Status: contributed by Laurent Léonard
 127
 128 =item B<virtualpc>
 129
 130 The guest appears to be running on Microsoft VirtualPC.
 131
 132 Status: not confirmed
 133
 134 =item B<vmware>
 135
 136 The guest appears to be running on VMware hypervisor.
 137
 138 Status: confirmed by RWMJ
 139
 140 =item B<xen>
 141
 142 The guest appears to be running on Xen hypervisor.
 143
 144 Status: confirmed by RWMJ
 145
 146 =item B<xen-dom0>
 147
 148 This is the Xen dom0 (privileged domain).
 149
 150 Status: confirmed by RWMJ
 151
 152 =item B<xen-domU>
 153
 154 This is a Xen domU (paravirtualized guest domain).
 155
 156 Status: confirmed by RWMJ
 157
 158 =item B<xen-hvm>
 159
 160 This is a Xen guest fully virtualized (HVM).
 161
 162 Status: confirmed by RWMJ
 163
 164 =back
 165
 166 =head1 EXIT STATUS
 167
 168 Programs that use or wrap C<virt-what> should check that the exit
 169 status is 0 before they attempt to parse the output of the command.
 170
 171 A non-zero exit status indicates some error, for example, an
 172 unrecognized command line argument.  If the exit status is non-zero
 173 then the output "facts" (if any were printed) cannot be guaranteed and
 174 should be ignored.
 175
 176 The exit status does I<not> have anything to do with whether the
 177 program is running on baremetal or under virtualization, nor with
 178 whether C<virt-what> managed detection "correctly" (which is basically
 179 unknowable given the large variety of virtualization systems out there
 180 and that some systems deliberately emulate others).
 181
 182 =head1 IMPORTANT NOTE
 183
 184 Most of the time, using this program is the I<wrong> thing to do.
 185 Instead you should detect the specific features you actually want to
 186 use.  (As an example, if you wanted to issue Xen hypervisor commands
 187 you would look for the C</proc/xen/privcmd> file).
 188
 189 However people keep asking for this, so we provide it.  There are a
 190 few legitimate uses:
 191
 192 =over 4
 193
 194 =item Bug reporting tool
 195
 196 If you think that virtualization could affect how your program runs,
 197 then you might use C<virt-what> to report this in a bug reporting
 198 tool.
 199
 200 =item Status display and monitoring tools
 201
 202 You might include this information in status and monitoring programs.
 203
 204 =back
 205
 206 =head1 SEE ALSO
 207
 208 L<http://people.redhat.com/~rjones/virt-what/>,
 209 L<http://www.vmware.com/>,
 210 L<http://www.microsoft.com/windows/products/winfamily/virtualpc>,
 211 L<http://xensource.com/>,
 212 L<http://bellard.org/qemu/>,
 213 L<http://kvm.qumranet.com/>,
 214 L<http://openvz.org/>
 215
 216 =head1 AUTHORS
 217
 218 Richard W.M. Jones <rjones @ redhat . com>
 219
 220 =head1 COPYRIGHT
 221
 222 (C) Copyright 2008-2011 Red Hat Inc.,
 223 L<http://people.redhat.com/~rjones/virt-what/>
 224
 225 This program is free software; you can redistribute it and/or modify
 226 it under the terms of the GNU General Public License as published by
 227 the Free Software Foundation; either version 2 of the License, or
 228 (at your option) any later version.
 229
 230 This program is distributed in the hope that it will be useful,
 231 but WITHOUT ANY WARRANTY; without even the implied warranty of
 232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 233 GNU General Public License for more details.
 234
 235 You should have received a copy of the GNU General Public License
 236 along with this program; if not, write to the Free Software
 237 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 238
 239 =head1 REPORTING BUGS
 240
 241 Bugs can be viewed on the Red Hat Bugzilla page:
 242 L<https://bugzilla.redhat.com/>.
 243
 244 If you find a bug in virt-what, please follow these steps to report it:
 245
 246 =over 4
 247
 248 =item 1. Check for existing bug reports
 249
 250 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 251 Someone may already have reported the same bug, and they may even
 252 have fixed it.
 253
 254 =item 2. Capture debug and error messages
 255
 256 Run
 257
 258  virt-what > virt-what.log 2>&1
 259
 260 and keep I<virt-what.log>.  It may contain error messages which you
 261 should submit with your bug report.
 262
 263 =item 3. Get version of virt-what.
 264
 265 Run
 266
 267  virt-what --version
 268
 269 =item 4. Submit a bug report.
 270
 271 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 272 Please describe the problem in as much detail as possible.
 273
 274 Remember to include the version numbers (step 3) and the debug
 275 messages file (step 2) and as much other detail as possible.
 276
 277 =item 5. Assign the bug to rjones @ redhat.com
 278
 279 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 280 spaces).  You can also send me an email with the bug number if you
 281 want a faster response.
 282
 283 =back