--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+virt-dmesg - Print kernel messages from a Linux virtual machine
+
+=head1 SYNOPSIS
+
+ virt-dmesg [--options] domname
+
+ virt-uname [--options] domname
+
+ virt-dmesg --dump-kernel domname | strings | less
+
+=head1 DESCRIPTION
+
+B<virt-dmesg> prints the kernel messages from a running Linux virtual
+machine. It is like L<dmesg(1)> except that it works on virtual
+machines instead of the host.
+
+virt-dmesg requires memory snooping features only available in the
+QEMU and KVM hypervisors, and so at present it will only work for QEMU
+and KVM virtual machines. It may be possible to add support for other
+hypervisors in future.
+
+virt-dmesg works by snooping the memory of the virtual machine,
+reading and downloading the kernel memory, and then using heuristics
+to find the kernel symbols. The advantage of this is that it should
+work for most Linux virtual machines, regardless of version and
+distro. The disadvantage is that heuristics are not guaranteed to be
+successful. For reliable access to many Linux kernel structures,
+including process tables and much more, please use the I<kdump>,
+I<virsh dump> and/or L<crash(8)> utilities instead.
+
+=head1 USAGE FOR GETTING KERNEL MESSAGES (DMESG)
+
+To display the kernel messages (dmesg), where I<Guest> is the libvirt
+name of a running Linux virtual machine do:
+
+ virt-dmesg Guest
+
+=head1 USAGE FOR GETTING KERNEL VERSION (UNAME, UTSNAME)
+
+If virt-dmesg is invoked with the I<--uname> option or if virt-uname
+is a hard link to the virt-dmesg program, then the program shows the
+system "utsname", the strings returned by the utsname(2) system call
+or the L<uname(1)> program:
+
+ virt-uname Guest
+
+ virt-dmesg --uname Guest
+
+=head1 USAGE FOR DUMPING KERNEL
+
+Instead of having virt-dmesg attempt to heuristically parse the kernel
+image, you can have virt-dmesg simply dump the kernel image to stdout.
+You can pass this to L<hexdump(1)> or L<strings(1)> to look for
+strings or other secrets in the kernel:
+
+ virt-dmesg --dump-kernel Guest | strings | less
+
+A tip: to find the kernel messages, try searching for the following
+patterns:
+
+ ^<5>.*Linux
+ ^<[0-9]>
+
+or for other strings that you suspect might be in the kernel output
+such as common initialization strings or error messages.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display brief help.
+
+=item B<-c> URI
+
+=item B<--connect> URI
+
+If using libvirt, connect to the given I<URI>. If omitted, then we
+connect to the default libvirt hypervisor.
+
+=item B<--dump-kernel>
+
+Dump the kernel to stdout. This prints lots of binary data, so it is
+best to pipe this through a program such as L<strings(1)>.
+
+=item B<--uname>
+
+Print utsname strings (ie. kernel version) instead of kernel messages.
+
+If virt-uname is a hard link to virt-dmesg, then this is the default.
+
+=item B<-v>
+
+Enable verbose messages for debugging.
+
+=item B<-V>
+
+=item B<--version>
+
+Display version number and exit.
+
+=back
+
+=head1 DIAGNOSTICS
+
+=head2 "cannot find kernel"
+
+We can't find the kernel at any known address. We don't scan the
+whole of the guest memory, because that would take far too long.
+Instead we look in a small number of locations where Linux kernels are
+commonly found. If none of these locations appear to contain a kernel
+then you will see this error message.
+
+Assuming that the guest really is running Linux, use the I<virt-dmesg
+-v> option to see what addresses the program is checking.
+
+Compare this to the contents of C</proc/kallsyms> or C</boot/config-*>
+B<inside> the guest.
+
+If the kernel is located at a completely different address, or if the
+address is correct but virt-dmesg does not appear to detect the kernel
+there, please file a bug (see L</REPORTING BUGS> below).
+
+=head2 "could not find kernel log buffer in kernel image"
+
+The kernel symbols (C<log_buf>, C<log_buf_len>, C<log_end>,
+C<logged_chars>) are not exported in C</proc/kallsyms> in the guest
+kernel.
+
+Ask your Linux distributor to enable all of these kernel configuration
+options:
+
+ CONFIG_KALLSYMS=y
+ CONFIG_KALLSYMS_ALL=y
+ CONFIG_KALLSYMS_EXTRA_PASS=y
+
+=head1 SEE ALSO
+
+L<dmesg(1)>,
+L<uname(1)>,
+L<crash(8)>,
+L<http://libvirt.org/>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2008-2011 Red Hat Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+=head1 REPORTING BUGS
+
+You can see current bugs reported against virt-dmesg at the following
+URL:
+
+https://bugzilla.redhat.com/buglist.cgi?component=virt-dmesg
+
+If the bug you are experiencing is not listed there, please file a new
+bug here:
+
+https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=virt-dmesg
+
+Give as much detail as possible. Include:
+
+=over 4
+
+=item *
+
+The version of virt-dmesg, libvirt and qemu/KVM.
+
+=item *
+
+How you obtained virt-dmesg (packaged in Fedora, compiled from source,
+etc.)
+
+=item *
+
+The version of the guest you are trying to inspect.
+
+It's is also useful to have C</proc/kallsyms> and C</boot/config-*>
+from inside the guest.
+
+=item *
+
+The full output of virt-dmesg when you add the I<-v> (debugging)
+option.
+
+=back
git.annexia.org / virt-dmesg.git / blobdiff