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 RUNNING VIRT-WHAT FROM OTHER PROGRAMS
 183
 184 C<virt-what> is designed so that you can easily run it from
 185 other programs or wrap it up in a library.
 186
 187 Your program should check the exit status (see the section above).
 188
 189 Some programming languages (notably Python: issue 1652) erroneously
 190 mask the C<SIGPIPE> signal and do not restore it when executing
 191 subprocesses.  C<virt-what> is a shell script and some shell commands
 192 do not work correctly when you do this.  You may see warnings from
 193 C<virt-what> similar to this:
 194
 195  echo: write error: Broken pipe
 196
 197 The solution is to set the C<SIGPIPE> signal handler back to C<SIG_DFL>
 198 before running C<virt-what>.
 199
 200 =head1 IMPORTANT NOTE
 201
 202 Most of the time, using this program is the I<wrong> thing to do.
 203 Instead you should detect the specific features you actually want to
 204 use.  (As an example, if you wanted to issue Xen hypervisor commands
 205 you would look for the C</proc/xen/privcmd> file).
 206
 207 However people keep asking for this, so we provide it.  There are a
 208 few legitimate uses:
 209
 210 =over 4
 211
 212 =item Bug reporting tool
 213
 214 If you think that virtualization could affect how your program runs,
 215 then you might use C<virt-what> to report this in a bug reporting
 216 tool.
 217
 218 =item Status display and monitoring tools
 219
 220 You might include this information in status and monitoring programs.
 221
 222 =back
 223
 224 =head1 SEE ALSO
 225
 226 L<http://people.redhat.com/~rjones/virt-what/>,
 227 L<http://www.vmware.com/>,
 228 L<http://www.microsoft.com/windows/products/winfamily/virtualpc>,
 229 L<http://xensource.com/>,
 230 L<http://bellard.org/qemu/>,
 231 L<http://kvm.qumranet.com/>,
 232 L<http://openvz.org/>
 233
 234 =head1 AUTHORS
 235
 236 Richard W.M. Jones <rjones @ redhat . com>
 237
 238 =head1 COPYRIGHT
 239
 240 (C) Copyright 2008-2011 Red Hat Inc.,
 241 L<http://people.redhat.com/~rjones/virt-what/>
 242
 243 This program is free software; you can redistribute it and/or modify
 244 it under the terms of the GNU General Public License as published by
 245 the Free Software Foundation; either version 2 of the License, or
 246 (at your option) any later version.
 247
 248 This program is distributed in the hope that it will be useful,
 249 but WITHOUT ANY WARRANTY; without even the implied warranty of
 250 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 251 GNU General Public License for more details.
 252
 253 You should have received a copy of the GNU General Public License
 254 along with this program; if not, write to the Free Software
 255 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 256
 257 =head1 REPORTING BUGS
 258
 259 Bugs can be viewed on the Red Hat Bugzilla page:
 260 L<https://bugzilla.redhat.com/>.
 261
 262 If you find a bug in virt-what, please follow these steps to report it:
 263
 264 =over 4
 265
 266 =item 1. Check for existing bug reports
 267
 268 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 269 Someone may already have reported the same bug, and they may even
 270 have fixed it.
 271
 272 =item 2. Capture debug and error messages
 273
 274 Run
 275
 276  virt-what > virt-what.log 2>&1
 277
 278 and keep I<virt-what.log>.  It may contain error messages which you
 279 should submit with your bug report.
 280
 281 =item 3. Get version of virt-what.
 282
 283 Run
 284
 285  virt-what --version
 286
 287 =item 4. Submit a bug report.
 288
 289 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 290 Please describe the problem in as much detail as possible.
 291
 292 Remember to include the version numbers (step 3) and the debug
 293 messages file (step 2) and as much other detail as possible.
 294
 295 =item 5. Assign the bug to rjones @ redhat.com
 296
 297 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 298 spaces).  You can also send me an email with the bug number if you
 299 want a faster response.
 300
 301 =back