virt-mem.pod

   1 =head1 NAME
   2
   3 virt-uname - system information for virtual machines
   4
   5 virt-dmesg - print kernel messages for virtual machines
   6
   7 =head1 SUMMARY
   8
   9 virt-uname [-options] [domains...]
  10
  11 virt-dmesg [-options] [domains...]
  12
  13 =head1 DESCRIPTION
  14
  15 These virtualization tools allow you to inspect the status of
  16 virtual machines running Linux.
  17
  18 The tools all use libvirt so are capable of showing stats across a
  19 variety of different virtualization systems.
  20
  21 =head1 COMMON OPTIONS
  22
  23 Each command obeys a common set of options.  The general form is:
  24
  25 virt-I<program> [-options] [domains...]
  26
  27 where I<domains> is a list of guest names to act on.  If no domains
  28 are specified then we act on all active domains by default.
  29
  30 A I<domain> may be specified either by its name or by its ID.  Use
  31 I<virsh list> to get a list of active domain names and IDs.
  32
  33 The virt-mem tools do not work on domains which are not active
  34 (running or paused).  eg. They do not work on shut down domains.
  35
  36 =over 4
  37
  38 =item B<-c uri>, B<--connect uri>
  39
  40 Connect to libvirt URI.  The default is to connect to the default
  41 libvirt URI, normally Xen.
  42
  43 =item B<--csv>
  44
  45 Print the results in CSV format, suitable for importing into a
  46 spreadsheet or database.
  47
  48 This option is only supported if virt-mem was built with CSV support.
  49
  50 =item B<--debug>
  51
  52 Emit debugging information on stderr.  Please supply this if you
  53 report a bug.
  54
  55 =item B<--help>
  56
  57 Display usage summary.
  58
  59 =item B<-t memoryimage>
  60
  61 Test mode.  Instead of checking libvirt for domain information, this
  62 runs the virt-mem tool directly on the memory image supplied.  You may
  63 specify the B<-t> option multiple times.
  64
  65 =item B<--version>
  66
  67 Display version and exit.
  68
  69 =item B<-E auto|littleendian|bigendian>
  70
  71 =item B<-T auto|i386|x86-64|I<address>>
  72
  73 =item B<-W auto|32|64>
  74
  75 These options force the endianness, text address, and word size for
  76 the subsequent domains listed on the command line (or if no domains
  77 are listed, then for all domains).
  78
  79 These default to I<auto> which tries to do automatic detection (using
  80 libvirt, or details from the memory images themselves).  You only need
  81 to use these options if virt-mem tools get the automatic detection
  82 wrong.
  83
  84 Endianness (I<-E>) sets the memory endianness, for data, pointers and
  85 so on.
  86
  87 Text address (I<-T>) sets the base address of the kernel image.  I<-T
  88 i386> means to try some common addresses for i386-based kernels.  I<-T
  89 x86-64> means to try some common addresses for x86-64-based kernels.
  90 I<-T I<address>> sets the address specifically (I<0x> prefix is
  91 allowed to specify hex addresses).
  92
  93 Word size (I<-W>) sets the word size, 32 or 64 bits.
  94
  95 =item B<-A auto|i386|x86-64|...>
  96
  97 This option sets the architecture to one of a collection of known
  98 architectures.  It is equivalent to setting endianness and wordsize in
  99 one go, but not text address.
 100
 101 =back
 102
 103 =head1 EXAMPLES
 104
 105  # virt-uname
 106  f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
 107  SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
 108
 109  # virt-dmesg f9x32kvm | tail
 110  <6>Bluetooth: Core ver 2.11
 111  <6>NET: Registered protocol family 31
 112  <6>Bluetooth: HCI device and connection manager initialized
 113  <6>Bluetooth: HCI socket layer initialized
 114  <6>Bluetooth: L2CAP ver 2.9
 115  <6>Bluetooth: L2CAP socket layer initialized
 116  <6>Bluetooth: RFCOMM socket layer initialized
 117  <6>Bluetooth: RFCOMM TTY layer initialized
 118  <6>Bluetooth: RFCOMM ver 1.8
 119  <7>eth0: no IPv6 routers present
 120
 121 =head1 SHORTCOMINGS
 122
 123 The virt-mem tools spy on the guest's memory image.  There are some
 124 shortcomings to this, described here.
 125
 126 (1) Only works on specific, tested releases of Linux kernels.  Support
 127 for arbitrary Linux kernel versions may be patchy because of changes
 128 in the internal structures used.  Support for non-Linux kernels is
 129 currently non-existent, and probably impossible for Windows because of
 130 lack of an acceptable source license.
 131
 132 (2) Heuristics are used which may mean in the worst case that the
 133 output is wrong.
 134
 135 (3) Structures which are frequently modified may cause errors.  This
 136 could be a problem if, for example, the process table in the guest is
 137 being rapidly updated.
 138
 139 (4) We have to scan memory to find kernel symbols, etc., which can be
 140 quite slow.  Optimizing the memory scanner would help, and caching the
 141 base address of the symbol table(s) would make it dramatically faster.
 142
 143 =head1 SECURITY
 144
 145 The current code tries hard to be secure against malicious guests, for
 146 example guests which set up malicious kernel memory.
 147
 148 =head1 SEE ALSO
 149
 150 L<uname(1)>,
 151 L<dmesg(1)>,
 152 L<virsh(1)>,
 153 L<xm(1)>,
 154 L<http://www.libvirt.org/ocaml/>,
 155 L<http://www.libvirt.org/>,
 156 L<http://et.redhat.com/~rjones/>,
 157 L<http://caml.inria.fr/>
 158
 159 =head1 AUTHORS
 160
 161 Richard W.M. Jones <rjones @ redhat . com>
 162
 163 =head1 COPYRIGHT
 164
 165 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones
 166 http://libvirt.org/
 167
 168 This program is free software; you can redistribute it and/or modify
 169 it under the terms of the GNU General Public License as published by
 170 the Free Software Foundation; either version 2 of the License, or
 171 (at your option) any later version.
 172
 173 This program is distributed in the hope that it will be useful,
 174 but WITHOUT ANY WARRANTY; without even the implied warranty of
 175 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 176 GNU General Public License for more details.
 177
 178 You should have received a copy of the GNU General Public License
 179 along with this program; if not, write to the Free Software
 180 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 181
 182 =head1 REPORTING BUGS
 183
 184 Bugs can be viewed on the Red Hat Bugzilla page:
 185 L<https://bugzilla.redhat.com/>.
 186
 187 If you find a bug in virt-mem, please follow these steps to report it:
 188
 189 =over 4
 190
 191 =item 1. Check for existing bug reports
 192
 193 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 194 Someone may already have reported the same bug, and they may even
 195 have fixed it.
 196
 197 =item 2. Capture debug and error messages
 198
 199 Run
 200
 201 virt-I<program> --debug > virt-mem.log 2>&1
 202
 203 and keep I<virt-mem.log>.  It contains error messages which you should
 204 submit with your bug report.
 205
 206 =item 3. Get version of virt-mem and version of libvirt.
 207
 208 Run
 209
 210 virt-I<program> --version
 211
 212 =item 4. Submit a bug report.
 213
 214 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 215 Please describe the problem in as much detail as possible.
 216
 217 Remember to include the version numbers (step 3) and the debug
 218 messages file (step 2).
 219
 220 =item 5. Assign the bug to rjones @ redhat.com
 221
 222 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 223 spaces).  You can also send me an email with the bug number if you
 224 want a faster response.
 225
 226 =back