svn commit: r52814 - head/en_US.ISO8859-1/books/handbook/virtualization
Benedict Reuschling
bcr at FreeBSD.org
Mon Feb 11 18:34:33 UTC 2019
Author: bcr
Date: Mon Feb 11 18:34:32 2019
New Revision: 52814
URL: https://svnweb.freebsd.org/changeset/doc/52814
Log:
Add a troubleshooting section to the Xen chapter.
In the discussion leading up to r52813, rgrimes@ suggested to add a
troubleshooting section to the Xen chapter to help with debugging issues.
In particular, users should know where Xen 4.11 and higher logs important
information relevant for debugging. There are also a couple of options
that increase the verbosity of the dom0 and enable iommu debugging. These
were divided up into two subsections: one for the host and the other for
the guest.
Thanks go out to royger@ for providing the information and putting together
a documentation patch before I could.
Suggested by: rgrimes
Patch by: royger
Approved by: bcr
Differential Revision: https://reviews.freebsd.org/D19107
Modified:
head/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml Mon Feb 11 18:15:48 2019 (r52813)
+++ head/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml Mon Feb 11 18:34:32 2019 (r52814)
@@ -1719,5 +1719,107 @@ freebsd 1 1024
the operating system has been installed and can be used as a
virtual machine.</para>
</sect2>
+
+ <sect2 xml:id="virtualization-host-xen-troubleshooting">
+ <title>Troubleshooting</title>
+
+ <para>This section contains basic information in order to help
+ troubleshoot issues found when using &os; as a &xen; host or
+ guest.</para>
+
+ <sect3 xml:id="virtualization-host-xen-troubleshooting-host">
+ <title>Host Boot Troubleshooting</title>
+
+ <para>Please note that the following troubleshooting tips
+ are intended for &xen; 4.11 or newer. If you are still
+ using &xen; 4.7 and having issues consider migrating to
+ a newer version of &xen;.</para>
+
+ <para>In order to troubleshoot host boot issues you will
+ likely need a serial cable, or a debug USB cable. Verbose
+ &xen; boot output can be obtained by adding options to the
+ <literal>xen_cmdline</literal> option found in
+ <filename>loader.conf</filename>. A couple of relevant
+ debug options are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>iommu=debug</literal>: can be used to print
+ additional diagnostic information about the
+ iommu.</para>
+ </listitem>
+ <listitem>
+ <para><literal>dom0=verbose</literal>: can be used to
+ print additional diagnostic information about the
+ dom0 build process.</para>
+ </listitem>
+ <listitem>
+ <para><literal>sync_console</literal>: flag to force
+ synchronous console output. Useful for debugging to
+ avoid losing messages due to rate limiting.
+ Never use this option in production environments since
+ it can allow malicious guests to perform DoS attacks
+ against &xen; using the console.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>&os; should also be booted in verbose mode in order
+ to identify any issues. To activate verbose booting, run
+ this command:</para>
+
+ <screen>&prompt.root; <userinput>sysrc -f /boot/loader.conf boot_verbose="YES"</userinput></screen>
+
+ <para>If none of these options help solving the problem,
+ please send the serial boot log to
+ <email>freebsd-xen at FreeBSD.org</email> and
+ <email>xen-devel at lists.xenproject.org</email>
+ for further analysis.</para>
+ </sect3>
+
+ <sect3 xml:id="virtualization-host-xen-troubleshooting-guest">
+ <title>Guest Creation Troubleshooting</title>
+
+ <para>Issues can also arise when creating guests, the
+ following attempts to provide some help for those trying
+ to diagnose guest creation issues.</para>
+
+ <para>The most common cause of guest creation failures is the
+ <literal>xl</literal> command spitting some error and
+ exiting with a return code different than 0. If the error
+ provided is not enough to help identify the issue, more
+ verbose output can also be obtained from
+ <literal>xl</literal> by using the <literal>v</literal>
+ option repeatedly.</para>
+
+ <screen>&prompt.root; <userinput>xl -vvv create freebsd.cfg</userinput>
+Parsing config from freebsd.cfg
+libxl: debug: libxl_create.c:1693:do_domain_create: Domain 0:ao 0x800d750a0: create: how=0x0 callback=0x0 poller=0x800d6f0f0
+libxl: debug: libxl_device.c:397:libxl__device_disk_set_backend: Disk vdev=xvda spec.backend=unknown
+libxl: debug: libxl_device.c:432:libxl__device_disk_set_backend: Disk vdev=xvda, using backend phy
+libxl: debug: libxl_create.c:1018:initiate_domain_create: Domain 1:running bootloader
+libxl: debug: libxl_bootloader.c:328:libxl__bootloader_run: Domain 1:not a PV/PVH domain, skipping bootloader
+libxl: debug: libxl_event.c:689:libxl__ev_xswatch_deregister: watch w=0x800d96b98: deregister unregistered
+domainbuilder: detail: xc_dom_allocate: cmdline="", features=""
+domainbuilder: detail: xc_dom_kernel_file: filename="/usr/local/lib/xen/boot/hvmloader"
+domainbuilder: detail: xc_dom_malloc_filemap : 326 kB
+libxl: debug: libxl_dom.c:988:libxl__load_hvm_firmware_module: Loading BIOS: /usr/local/share/seabios/bios.bin
+...</screen>
+
+ <para>If the verbose output does not help diagnose the issue
+ there are also QEMU and &xen; toolstack logs in
+ <filename>/var/log/xen</filename>. Note that the name of
+ the domain is appended to the log name, so if the domain
+ is named <literal>freebsd</literal> you should find a
+ <filename>/var/log/xen/xl-freebsd.log</filename> and likely
+ a <filename>/var/log/xen/qemu-dm-freebsd.log</filename>.
+ Both log files can contain useful information for debugging.
+ If none of this helps solve the issue, please send the
+ description of the issue you are facing and as much
+ information as possible to
+ <email>freebsd-xen at FreeBSD.org</email> and
+ <email>xen-devel at lists.xenproject.org</email> in order to
+ get help.</para>
+ </sect3>
+ </sect2>
</sect1>
</chapter>
More information about the svn-doc-all
mailing list