en_US.ISO8859-1/errata/article.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
  "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
<!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN"
  "http://www.FreeBSD.org/release/XML/release.ent">
%release;
<!ENTITY security PUBLIC "-//FreeBSD//ENTITIES Security Advisory List//EN"
	 "http://www.FreeBSD.org/release/XML/share/xml/security.xml">
<!ENTITY errata PUBLIC "-//FreeBSD//ENTITIES Errata List//EN"
	 "http://www.FreeBSD.org/release/XML/share/xml/errata.xml">
]>

<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">

  <info>
    <title>&os; &release.prev; Errata</title>

    <author><orgname>The &os; Project</orgname></author>

    <pubdate>$FreeBSD: stable/10/release/doc/en_US.ISO8859-1/errata/article.xml 324242 2017-10-03 19:08:16Z gjb $</pubdate>

    <copyright>
      <year>2017</year>

      <holder role="mailto:doc@FreeBSD.org">The &os; Documentation
	Project</holder>
    </copyright>

    <legalnotice xml:id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.intel;
      &tm-attrib.sparc;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>This document lists errata items for &os; &release.prev;,
	containing significant information discovered after the
	release or too late in the release cycle to be otherwise
	included in the release documentation.  This information
	includes security advisories, as well as news relating to the
	software or documentation that could affect its operation or
	usability.  An up-to-date version of this document should
	always be consulted before installing this version of
	&os;.</para>

      <para>This errata document for &os; &release.prev; will be
	maintained until &os; &release.prev; reaches
	end-of-life.</para>
    </abstract>
  </info>

  <sect1 xml:id="intro">
    <title>Introduction</title>

    <para>This errata document contains <quote>late-breaking
	news</quote> about &os; &release.prev; Before installing this
      version, it is important to consult this document to learn about
      any post-release discoveries or problems that may already have
      been found and fixed.</para>

    <para>Any version of this errata document actually distributed
      with the release (for example, on a CDROM distribution) will be
      out of date by definition, but other copies are kept updated on
      the Internet and should be consulted as the <quote>current
	errata</quote> for this release.  These other copies of the
      errata are located at <link
	xlink:href="https://www.FreeBSD.org/releases/" />, plus any
      sites which keep up-to-date mirrors of this location.</para>

    <para>Source and binary snapshots of &os; &release.branch; also
      contain up-to-date copies of this document (as of the time of
      the snapshot).</para>

    <para>For a list of all &os; CERT security advisories, see <link
	xlink:href="https://www.FreeBSD.org/security/"/>.</para>
  </sect1>

  <sect1 xml:id="security">
    <title>Security Advisories</title>

    &security;
  </sect1>

  <sect1 xml:id="errata">
    <title>Errata Notices</title>

    &errata;
  </sect1>

  <sect1 xml:id="open-issues">
    <title>Open Issues</title>

    <itemizedlist>
      <listitem>
	<para>&os;/&arch.i386; &release.prev; running as a guest
	  operating system on <application>VirtualBox</application>
	  can have a problem with disk I/O access.  It depends on some
	  specific hardware configuration and does not depend on a
	  specific version of <application>VirtualBox</application> or
	  host operating system.</para>

	<para>It has been reported that instability may be present on
	  virtual machines running on other hypervisors, such as Xen
	  or KVM.</para>

	<para>It causes various errors and makes &os; quite unstable.
	  Although the cause is still unclear, disabling unmapped I/O
	  works as a workaround.  To disable it, choose
	  <literal>Escape to loader prompt</literal> in the boot menu
	  and enter the following lines from &man.loader.8; prompt,
	  after an <literal>OK</literal>:</para>

	<screen>set vfs.unmapped_buf_allowed=0
boot</screen>

	<para>Note that the following line has to be added to
	  <filename>/boot/loader.conf</filename> after a boot.  It
	  disables unmapped I/O at every boot:</para>

	<programlisting>vfs.unmapped_buf_allowed=0</programlisting>
      </listitem>

      <listitem>
	<para>&os;/&arch.i386;&nbsp;&release.prev; installed on ZFS
	  may crash during boot when the ZFS pool mount is attempted
	  while booting an unmodified <literal>GENERIC</literal>
	  kernel.</para>

	<para>As described in <filename>/usr/src/UPDATING</filename>
	  entry <literal>20121223</literal>, rebuilding the kernel
	  with <literal>options KSTACK_PAGES=4</literal> has been
	  observed to resolve the boot-time crash.  This, however, is
	  not an ideal solution for inclusion in the
	  <literal>GENERIC</literal> kernel configuration, as
	  increasing <literal>KSTACK_PAGES</literal> implicitly
	  decreases available usermode threads in an environment that
	  is already resource-starved.</para>

	<para>Taking into account the heavy resource requirements of
	  ZFS, in addition to the &arch.i386;-specific tuning
	  requirements for general workloads, using ZFS with the
	  &os;/&arch.i386;&nbsp;<literal>GENERIC</literal> kernel
	  is strongly discouraged.</para>

	<para>If installing &os;/&arch.i386; on ZFS, it is possible to
	  configure the system after installation to increase the
	  <literal>KSTACK_PAGES</literal>.</para>

	<para>When prompted by &man.bsdinstall.8; to perform
	  additional post-installation configuration to the system,
	  select <guibutton>[&nbsp;YES&nbsp;]</guibutton>.</para>

	<para>This procedure requires the system sources available
	  locally.  If the <literal>System source code</literal>
	  distribution was not selected during installation, it can
	  be obtained using <application>svnlite</application>:</para>

	<screen>&prompt.root; mkdir -p /usr/src
&prompt.root; svnlite co https://svn.freebsd.org/base/releng/10.4 /usr/src</screen>

	<para>Build the <literal>kernel-toolchain</literal> required
	  to rebuild the kernel:</para>

	<screen>&prompt.root; make -C /usr/src kernel-toolchain</screen>

	<para>Next, create a kernel configuration file to increase the
	  <literal>KSTACK_PAGES</literal> option:</para>

	<screen>&prompt.root; printf "include GENERIC\noptions KSTACK_PAGES=4\n" &gt; <filename>/usr/src/sys/i386/conf/<replaceable>ZFS</replaceable></filename></screen>

	<para>Then build and install the
	  <replaceable>ZFS</replaceable> kernel:</para>

	<screen>&prompt.root; make -C /usr/src buildkernel KERNCONF=<replaceable>ZFS</replaceable>
&prompt.root; make -C /usr/src installkernel KERNCONF=<replaceable>ZFS</replaceable></screen>

	<warning>
	  <para>It is extremely important to take note that, by
	    default, &man.freebsd-update.8; will install the
	    <literal>GENERIC</literal> kernel configuration, and
	    as such, &man.freebsd-update.8; consumers are strongly
	    encouraged to avoid &os;-provided kernel binary upgrades
	    with such configurations.</para>
	</warning>
      </listitem>

      <listitem>
	<para>Due to an incompatibility between &man.bsdconfig.8;
	  and &man.pkg.8;, packages included on the &os;&nbsp;dvd
	  installer will not be recognized by
	  &man.bsdconfig.8;.</para>

	<para>To install packages from the <literal>dvd1.iso</literal>
	  installer, create the <filename
	    class="directory">/dist</filename> target directory, and
	  manually mount the <literal>dvd1.iso</literal>
	  <acronym>ISO</acronym>:</para>

	<screen>&prompt.root; mkdir -p /dist
&prompt.root; mount -t cd9660 /dev/<replaceable>cd0</replaceable> /dist</screen>

	<note>
	  <para>Be sure to use the correct <filename
	      class="directory">/dev</filename> device path for the
	    <literal>dvd1.iso</literal> <acronym>ISO</acronym>
	    installer.</para>
	</note>

	<para>Next, set <envar>REPOS_DIR</envar> to the path of the
	  <filename class="directory">repos/</filename> directory
	  within the installer so &man.pkg.8; will use the correct
	  repository metadata.</para>

	<para>If using &man.sh.1;:</para>

	<screen>&prompt.root; export REPOS_DIR=/dist/packages/repos</screen>

	<para>If using &man.csh.1;:</para>

	<screen>&prompt.root; setenv REPOS_DIR /dist/packages/repos</screen>

	<note>
	  <para>Keep in mind that <envar>REPOS_DIR</envar> will need
	    to be set again after the current shell session is
	    terminated, if continuing to use the packages provided on
	    the <literal>dvd1.iso</literal> installer.</para>
	</note>

	<para>Finally, bootstrap &man.pkg.8; from the
	  <acronym>ISO</acronym>, and install required
	  packages:</para>

	<screen>&prompt.root; pkg bootstrap
&prompt.root; pkg install <replaceable>xorg-server</replaceable> <replaceable>xorg</replaceable> <replaceable>gnome3</replaceable> [...]</screen>
      </listitem>

      <listitem>
	<para>An issue with &os; virtual machines with
	  <application>vagrant</application> was discovered that
	  affects the <application>VirtualBox</application> where the
	  virtual machine will not start on the initial boot invoked
	  with <literal>vagrant up</literal>.</para>

	<para>The issue is due to the virtual machine
	  <acronym>MAC</acronym> being unset, as &os; does not provide
	  a default <filename>Vagrantfile</filename>.</para>

	<para>It has been observed, however, that a subsequent
	  invocation of <literal>vagrant up</literal> will allow the
	  virtual machine to successfully boot, allowing access via
	  <literal>vagrant ssh</literal>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="late-news">
    <title>Late-Breaking News</title>

    <para>No news.</para>
  </sect1>
</article>