#ident	"@(#)bfu.README	1.5	96/05/17 SMI"

BFU (Blindingly Fast Upgrade, a.k.a. Bonwick/Faulkner Upgrade)

What it is
----------
bfu is a shell script that upgrades your system with a new set of OS/Net
binaries, e.g. the gate's nightly build.  The motivation behind bfu is
to make upgrading your system so painless that you can do it every day.

bfu requires no setup, no configuration information, and no saving or
restoring of files.  It performs a live upgrade of your current running
system in about 5 minutes.

How to use it
-------------
The bfu script is available in the gate's public/bin directory.
The general usage is:

	bfu archive-dir [root-dir]

To do a live upgrade of your current system, you point bfu at a
cpio archive directory *which you know to be good*, e.g.

	bfu /ws/on297-gate/archives/sparc/good

Resolve any conflicts if necessary (see below), then reboot your system.

That's it, you're done!

As a convenience, you can use short-hand invocation:

	bfu good
	bfu nightly-nd
	bfu s297_06

for any archives under the gate's archives directory.

As an additional convenience, if you want to bfu your machine
from the same place you bfu'ed last time, you can simply say:

	bfu again

This feature works by parsing /etc/motd, so don't remove the
"bfu'ed from ..." line if you want to take advantage of it.

Post-bfu environment
--------------------
When bfu completes there's no guarantee that the new commands and
libraries are compatible with the currently running (old) kernel.
Therefore, instead of exiting, bfu puts you into a subshell in which
PATH=/tmp/bfubin and LD_LIBRARY_PATH=/tmp/bfulib.  These directories
contain the old versions of the commands and libraries commonly needed
to resolve conflicts and reboot the system.  You can exit from this
protected environment if you want, but it is not advisable unless
you are sure that there have not been any "flag days" (synchronized
kernel/userland changes) since your last bfu.

Conflict resolution
-------------------
There are over 100 editable "configuration files" like /etc/vfstab and
/etc/remote that come with the OS/Net consolidation.  bfu saves and
restores these files automatically, following a very simple rule:

(1) If you have not modified /etc/mumble, you get the new version.
(2) If you *have* modified /etc/mumble, your version is preserved.

Here are the meanings of the messages you'll see as bfu processes
configuration files:

	update: etc/mumble

		Your version is identical to the old default version
		(you never changed it), so you get the new version.

	restore: etc/mumble

		Your version of /etc/mumble is just an extension of the
		default version (examples: /etc/system, /etc/dfs/dfstab).
		Your version is restored.

	NEW_conflict: etc/mumble

		Your version of /etc/mumble is different than the old
		default version, and the default version has changed.
		Action required: you must manually merge the changes.
		If you do nothing, your version is restored.

	old_conflict: etc/mumble

		Your version of /etc/mumble is different than the default,
		but the default version hasn't changed since the last time
		you bfu'ed, so presumably your changes are still valid.
		Your version is restored.

The historical information that bfu needs for automatic configuration
file processing is kept under /bfu.{child,ancestor,parent,conflicts}.

The first time you run bfu you'll see "NEW_conflict" messages for
several files because bfu will have no history to compare against.
After that, new conflicts should be quite rare.

Note: one good way to avoid the annoyance of first-time conflicts
is to bfu the same stuff you're already running.  In other words,
if you installed Solaris 2.5 FCS from CD, your first bfu should be:

	/ws/on495-gate/public/bin/bfu fcs

That way you know that all the NEW_conflicts represent changes you want,
so you don't have to do anything.  With your bfu history now established,
you can bfu any other archives painlessly.

Alternate system disks
----------------------
Although bfu upgrades the live system by default, you can also use bfu
to upgrade an alternate system disk.  For example, if you mount your
alternate system on /xroot (and /xroot/usr), you can bfu it by saying:

	bfu nightly /xroot

Prologue and epilogue scripts
-----------------------------
After you've used bfu for a while you may find that there are certain
things you usually like to do before and after each bfu.  To simplify
this process, bfu allows you to create scripts called /bfu.prologue
and /bfu.epilogue that are executed automatically.  /bfu.prologue
runs after all sanity checks have passed, but before any actions have
been performed.  /bfu.epilogue runs after all actions are complete,
right before syncing filesystems.

Recovering from system failure during bfu
-----------------------------------------
If your machine dies for some reason while a bfu is in progress,
you can usually recover with this sequence:

	boot net (or boot from an alternate disk)
	mount the afflicted system on /mnt and /mnt/usr
	restore your configuration files:
		cd /mnt/bfu.child; find . -depth -print | cpio -pdmu /mnt
	restart the bfu:
		bfu archive-dir /mnt

Diskless client servers
-----------------------
You can use bfu to upgrade a diskless client server.
The incantation is:

	bfu -c archive-dir exec-dir

where exec-dir is something like /export/exec/Solaris_2.5_sparc.all.
bfu -c will upgrade exec-dir with all usr archives and will upgrade
/export/root/* with the appropriate root archives.  bfu determines
which of the clients in /export/root/* are candidates for upgrade
by grepping for the exec-dir in /export/root/*/etc/vfstab.
It's a hack, but it works.

NOTE: you will have to update the server's tftpboot manually.

How old a system can I upgrade?
-------------------------------
You can bfu any post-KBI-phase-1 system, i.e. any build of Solaris 2.5
or later.

Caveats
-------
Please do not attempt to maintain your own private copy of bfu.
The gate's version is frequently updated so that bfu'ing across
"flag days" (e.g. the large files project) just magically works.
If you maintain your own copy of bfu you will not get these
updates, resulting in a significantly less magical experience.

Bad archives: this seems obvious, but: if you load bad archives,
you're hosed.  If this should ever happen to you, and the resulting
system is not even bootable, you can either (1) boot an alternate
system disk if you have one, (2) boot net, or (3) unplug the system
disk, plug it into another machine, mount it, and fix it there.
Having done one of the above, bfu good archives onto the bad disk.

Disk space: if you run out of disk space during bfu, you're hosed.
bfu performs some initial space checks to guard against this, but
these checks are not perfect since bfu doesn't know exactly what
you're running in the first place.

Overall system activity: don't run bfu while you're changing a lot
of critical state on your system, e.g. during a bringover.

Delayed I/O (UFS bungee jumping): bfu is fast because it uses delayed I/O.
This makes literally an order of magnitude difference in bfu performance
but it does entail some risk.  If your machine dies during bfu (panic,
power outage, etc) you may incur serious filesystem damage in the root
and /usr filesystems.  [ I don't mean to exaggerate the risk.  I've had
this happen to me twice, and both times I was able to recover with fsck.
But you should know what you're getting into. ]

System configuration files: bfu saves off a bunch of files like /etc/vfstab
before the upgrade begins, then restores them when it's done.  Take a look
at the file list in the bfu script to make sure you agree.  Note that things
like /var/mail/foo and /var/spool/calendar/callog.foo don't need to be saved
because they are not part of the archives, and thus are not affected.

Upgrade: using bfu makes it impossible to use suninstall upgrade because
bfu doesn't update the package database or run the class-action scripts.
(Doing so would kill bfu's 5-minute speed.)  Once you've bfu'ed, the only
safe way to upgrade the rest of your system is to do a fresh suninstall.

What bfu is not
---------------
bfu is not a replacement for suninstall.  It doesn't upgrade your
window system, compilers, etc -- just the OS/Net stuff.  It also
doesn't remove obsolete files.  You should still do fresh suninstalls
periodically for these reasons.

Reporting bugs
--------------
If you encounter a bug in bfu, please send mail to bonwick@eng and raf@eng.
One of us will fix it promptly.  We may also entertain reasonable RFE's.
