svn commit: r52814 - head/en_US.ISO8859-1/books/handbook/virtualization

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>[email protected]</email> and
+	  <email>[email protected]</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>[email protected]</email> and
+	  <email>[email protected]</email> in order to
+	  get help.</para>
+      </sect3>
+    </sect2>
   </sect1>
 </chapter>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"