More incorporation of redundant information. Definitely very much a WIP.

Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-02-06 17:20:15 +00:00
parent 1463965233
commit ccf51f5cca
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43806

View file

@ -1543,6 +1543,18 @@ before running "/usr/sbin/freebsd-update install"</screen>
run in the order specified here. This section summarizes
the function of each command.</para>
<step>
<para>If the build world process has previously been run on
this system, a copy of the previous build may still exist
in <filename class="directory">/usr/obj</filename>. To speed up the new build world
process, and possibly save some dependency headaches,
remove this directory if it already exists:</para>
<screen>&prompt.root; <userinput>cd /usr/obj</userinput>
&prompt.root; <userinput>chflags -R noschg *</userinput>
&prompt.root; <userinput>rm -rf *</userinput></screen>
</step>
<step>
<para>Compile the new compiler and a few related
tools, then use the new compiler to compile the rest of
@ -1577,11 +1589,12 @@ before running "/usr/sbin/freebsd-update install"</screen>
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
<para>Once in single-user mode, run this command if the
<para>Once in single-user mode, run these commands if the
system is formatted with UFS:</para>
<screen>&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput></screen>
&prompt.root; <userinput>mount -a -t ufs</userinput>
&prompt.root; <userinput>swapon -a</userinput></screen>
<para>If the system is instead formatted with ZFS, run these
two commands. This example assumes a zpool name of
@ -1592,18 +1605,22 @@ before running "/usr/sbin/freebsd-update install"</screen>
</step>
<step>
<para>Then, for either filesystem, run:</para>
<para>Then, for either file system, if the <acronym>CMOS</acronym> clock is set to local time
(this is true if the output of &man.date.1; does not show
the correct time and zone), run:</para>
<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
</step>
<step>
<para>Next, perform some initial configuration file updates
in preparation for the new world. For instance, this step
may add new groups or new system accounts which have been
<para>Next, perform some initial configuration file updates to <filename class="directory">/etc</filename>
in preparation for the new world. The following command compares
only those files that are essential for the success of
<buildtarget>installworld</buildtarget>. For instance, this step
may add new groups, system accounts, or startup scripts which have been
added to &os; since the last update. This is necessary so
that the <buildtarget>installworld</buildtarget> step will
be able to use the new system accounts and groups.</para>
be able to use any new system accounts, groups, and scripts.</para>
<screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
@ -1646,42 +1663,51 @@ before running "/usr/sbin/freebsd-update install"</screen>
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</step>
</procedure>
<indexterm><primary>single-user mode</primary></indexterm>
<para>If the system can have a window of down-time, consider compiling the system in single user mode instead
of compiling the system in multi-user
mode, and then dropping into single user mode for the
installation.
Reinstalling the system touches a lot of important system
files, all the standard system binaries, libraries, and
include files. Changing these on a running system,
particularly one with active users, is asking for
trouble.</para>
</sect2>
<sect2 xml:id="src-updating">
<title>Check <filename>/etc/make.conf</filename></title>
<title>Configuration Files</title>
<indexterm>
<primary><filename>make.conf</filename></primary>
</indexterm>
<para>The following sections clearly describe each step,
especially when using a custom kernel configuration.</para>
<para>Available &man.make.1; options are shown in
&man.make.conf.5; and
<filename>/usr/share/examples/etc/make.conf</filename>. These
settings can be added to <filename>/etc/make.conf</filename>
to control the way &man.make.1; runs and how it builds
programs. Changes to some settings can have far-reaching and
<para>This section describes the configuration files used by the
build world process.</para>
<para>The options available to &man.make.1; are described in
&man.make.conf.5; and some common examples are included in
<filename>/usr/share/examples/etc/make.conf</filename>.
Any options which are added to <filename>/etc/make.conf</filename>
will control the way &man.make.1; runs and how it builds
programs. Such options take
effect every time &man.make.1; is used, including compiling
applications from the Ports Collection, compiling custom C
programs, or building the &os; operating system.</para>
<para>Changes to some settings can have far-reaching and
potentially surprising effects. Read the comments in both
locations and keep in mind that the defaults have been chosen
for a combination of performance and safety.</para>
<para>Options set in <filename>/etc/make.conf</filename> take
effect every time &man.make.1; is used, including compiling
applications from the Ports Collection or user-written C
programs, or building the &os; operating system.</para>
</sect2>
<sect2 xml:id="src-conf">
<title>Check <filename>/etc/src.conf</filename></title>
<indexterm>
<primary><filename>src.conf</filename></primary>
</indexterm>
<para><filename>/etc/src.conf</filename> controls the building
of the operating system from source code. Unlike
<para>How
the operating system is built from source code is controlled by <filename>/etc/src.conf</filename>. Unlike
<filename>/etc/make.conf</filename>, the contents of
<filename>/etc/src.conf</filename> only take effect when the
&os; operating system itself is being built. Descriptions of
@ -1689,116 +1715,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
&man.src.conf.5;. Be cautious about disabling seemingly
unneeded kernel modules and build options. Sometimes there
are unexpected or subtle interactions.</para>
</sect2>
<sect2 xml:id="updating-etc">
<title>Update the Files in <filename>/etc</filename></title>
<para><filename>/etc</filename> contains a
large part of the system's configuration information, as well
as scripts that are run at system startup. Some of these
scripts change between &os; versions.</para>
<para>Some of the configuration files are used in the day to
day running of the system, such as
<filename>/etc/group</filename>.</para>
<para>There have been occasions when the installation part of
<command>make installworld</command> expected certain
usernames or groups to exist. When performing an upgrade, it
is likely that these users or groups do not yet exist. In
some cases <command>make buildworld</command> will check to
see if these users or groups exist.</para>
<para>The solution is to run &man.mergemaster.8; in
pre-buildworld mode with <option>-p</option>. This compares
only those files that are essential for the success of
<buildtarget>buildworld</buildtarget> or
<buildtarget>installworld</buildtarget>.</para>
<tip>
<para>To check which files are owned by the group being
renamed or deleted:</para>
<screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen>
<para>This command will show all files owned by group
<replaceable>GID</replaceable>, which can be either a group
name or a numeric group ID.</para>
</tip>
</sect2>
<sect2 xml:id="makeworld-singleuser">
<title>Drop to Single User Mode</title>
<indexterm><primary>single-user mode</primary></indexterm>
<para>Consider compiling the system in single user mode.
Reinstalling the system touches a lot of important system
files, all the standard system binaries, libraries, and
include files. Changing these on a running system,
particularly one with active users, is asking for
trouble.</para>
<indexterm><primary>multi-user mode</primary></indexterm>
<para>Another method is to compile the system in multi-user
mode, and then drop into single user mode for the
installation. With this method, hold off on the following
steps until the build has completed. Drop to single user mode
in order to run <buildtarget>installkernel</buildtarget> or
<buildtarget>installworld</buildtarget>.</para>
<para>To enter single user mode from a running system:</para>
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
<para>Alternatively, reboot the system, and at the boot prompt,
select the <quote>single user</quote> option. Once at the
single user mode shell prompt, run:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput>
&prompt.root; <userinput>swapon -a</userinput></screen>
<para>This checks the file systems, remounts
<filename>/</filename> read/write, mounts all the other UFS
file systems referenced in <filename>/etc/fstab</filename>,
and turns swapping on.</para>
<note>
<para>If the CMOS clock is set to local time and not to GMT
(this is true if the output of &man.date.1; does not show
the correct time and zone), run the following
command:</para>
<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
<para>This ensures that the local time-zone settings get set
up correctly.</para>
</note>
</sect2>
<sect2 xml:id="cleaning-usr-obj">
<title>Remove <filename>/usr/obj</filename></title>
<para>As parts of the system are rebuilt, they are, by default,
placed in subdirectories of <filename>/usr/obj</filename>.
The directories shadow those under
<filename>/usr/src</filename>.</para>
<para>To speed up the <command>make buildworld</command>
process, and possibly save some dependency headaches,
remove this directory if it already exists.</para>
<para>Some files below <filename>/usr/obj</filename> may have
the immutable flag set which must be removed first using
&man.chflags.1;.</para>
<screen>&prompt.root; <userinput>cd /usr/obj</userinput>
&prompt.root; <userinput>chflags -R noschg *</userinput>
&prompt.root; <userinput>rm -rf *</userinput></screen>
</sect2>
</sect2>
<sect2 xml:id="make-buildworld">
<title>Recompile the Base System</title>
@ -2005,16 +1922,9 @@ Script done, &hellip;</screen>
problems. See &man.init.8; for details about
<varname>kern.securelevel</varname> and &man.chflags.1; for
details about the various file flags.</para>
</sect2>
<sect2 xml:id="new-kernel-singleuser">
<title>Reboot into Single User Mode</title>
<indexterm><primary>single-user mode</primary></indexterm>
<para>Reboot into single user mode to test that the new kernel
works using the instructions in
<xref linkend="makeworld-singleuser"/>.</para>
works.</para>
</sect2>
<sect2 xml:id="make-installworld">
@ -2160,11 +2070,6 @@ Script done, &hellip;</screen>
<filename>/etc</filename> are not in
<filename>/usr/src/etc</filename>.</para>
<para>If you are using &man.mergemaster.8; (as recommended),
you can skip forward to the
<link linkend="updating-upgrading-rebooting">next
section</link>.</para>
<para>The simplest way to merge files by hand is to install
the files into a new directory, and then work through them
looking for differences.</para>
@ -2376,15 +2281,6 @@ Script done, &hellip;</screen>
<screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
</sect2>
<sect2 xml:id="updating-upgrading-rebooting">
<title>Rebooting</title>
<para>Verify that everything appears to be in the right place,
then reboot the system using &man.shutdown.8;:</para>
<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
</sect2>
<sect2 xml:id="make-delete-old-libs">
<title>Deleting obsolete libraries</title>
@ -2607,10 +2503,10 @@ Building everything..
</varlistentry>
<varlistentry>
<term>What do I do if something goes wrong?</term>
<term>What if something goes wrong?</term>
<listitem>
<para>Make absolutely sure that the environment has no
<para>First, make absolutely sure that the environment has no
extraneous cruft from earlier builds:</para>
<screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>