Date: Fri, 11 Oct 2002 13:55:15 -0700 (PDT) From: Tim Kientzle <kientzle@acm.org> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/43941: Rationale for Upgrade Sequence Message-ID: <200210112055.g9BKtFqQ017731@www.freebsd.org>
index | next in thread | raw e-mail
>Number: 43941
>Category: docs
>Synopsis: Rationale for Upgrade Sequence
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Fri Oct 11 14:00:07 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator: Tim Kientzle
>Release:
>Organization:
>Environment:
>Description:
Mark Linimon suggested that I "get this exact reasoning added to the official docs, it's the clearest explanation I've seen yet." This was in response to a posting I made to freebsd-stable explaining some of the rationale behind the buildworld/buildkernel/installkernel/installworld sequence. I've attached the text of my posting below. I hope you find it useful.
>How-To-Repeat:
>Fix:
The following is an edited version of
my post to FreeBSD-stable mailing
list on 11 Oct, 2002, in response to a question
about why the "old" build sequence was no longer
considered sufficient:
------------------------------------------
Problem: You're currently running an old system, consisting
of old compiler, old kernel, old world, and old configuration files.
(By "world" here, I mean the core system binaries, libraries,
and programming files. The compiler is part of "world", but
has a few special concerns, which is why I've named it separately
here.) You have source code for a new system and want to compile
and install it over the old system. How should this be done?
This problem is a bit more subtle than it might seem, and the
FreeBSD developers have found it necessary over the years to
change the recommended approach fairly dramatically as new
kinds of unavoidable dependencies come to light. The following
describes the rationale behind the current update sequence
(being used by 5.0, for example).
Any successful update sequence must deal with the
following issues:
* The old compiler might not be able to compile
the new kernel. (Old compilers sometimes have bugs.)
So, the new kernel should be built with the new compiler.
In particular, the new compiler must be built before
the new kernel is built. This does not necessarily
mean that the new compiler must be _installed_ before
building the new kernel, however.
* The new world might rely on new kernel features.
So, the new kernel must be installed before the new world
is installed.
These first two issues are the basis for the
core buildworld/buildkernel/installkernel/installworld
sequence that I'll describe in a moment. They
are not the only concerns, however:
* The old world might not run correctly on the new kernel,
so you must install the new world immediately
upon installing the new kernel.
* Some configuration changes must be done before
the new world is installed, but others might break
the old world. Hence, two different configuration
upgrade steps are generally needed.
* For the most part, the update process only replaces
or adds files; existing old files are not deleted.
In a few cases, this can cause problems. As a result,
the update procedure will sometimes specify certain files
that should be manually deleted at certain steps.
This may or may not be automated in the future.
These concerns have led to the following recommended
sequence. Note that the detailed sequence for
particular updates may require additional steps,
but this core process should remain unchanged for some
time:
1) make buildworld
This first compiles the new compiler and
a few related tools, then uses the new compiler
to compile the rest of the new world. The result
ends up in /usr/obj.
2) make buildkernel
Unlike the older config/make approach,
this uses the _new_ compiler residing in
/usr/obj. This protects you against compiler/kernel
mismatches.
3) make installkernel
Place the new kernel and kernel modules onto the disk.
4) Reboot to single user mode.
Single user mode minimizes problems from
updating software that's already running.
It also minimizes any problems from
running the old world on a new kernel.
(Curiously, when moving from 4.x to 5.0,
you're still running the old kernel here,
because the new kernel is in a different
place and the boot loader hasn't been
updated yet.)
5) mergemaster -p
This does some initial configuration file updates
in preparation for the new world.
6) make installworld
Copies the world from /usr/obj.
You now have a new kernel and new world on disk.
7) mergemaster
Now you can update the remaining configuration files,
since you have a new world on disk.
8) reboot
A full machine reboot is needed now
to load the new kernel and new world
with new configuration files.
Note that if you're upgrading from, say,
4.6.2 to 4.7, then this procedure may not
be absolutely necessary, since you're
unlikely to run into serious mismatches
between compiler/kernel/world/configuration.
The older approach of "make world" followed
by building and installing a new kernel
might work well enough for minor updates.
But, when upgrading across major releases,
people who don't follow this procedure
should expect some problems.
Also, note that many upgrades (4.x to 5.0,
for instance) may require specific additional
steps (renaming or deleting specific files
prior to installworld, for instance). Read
the UPDATING file carefully, especially at
the end, where the currently recommended upgrade
sequence is spelled out.
This procedure has evolved over time
as the developers have found it impossible
to completely prevent certain kinds of
mismatch problems. Hopefully, the current
procedure will remain stable for a long time.
Note that upgrading from 3.x or earlier
is a bit trickier; read UPDATING carefully.
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200210112055.g9BKtFqQ017731>