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