os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Patches from the author.

Browse source 
PR:		4512
Submitted by:	Nik Clayton <nik@iii.co.uk>
This commit is contained in:
John Fieber 1997-09-14 03:53:16 +00:00
parent 9fcd8309be
commit eb0cfbead0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=1957
1 changed files with 496 additions and 277 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

305
en/tutorials/upgrade/upgrade.docb
View file

@ -1,34 +1,64 @@
<!-- $Id: upgrade.docb,v 1.1 1997-06-25 16:57:02 jfieber Exp $ -->
<!-- $Id: upgrade.docb,v 1.2 1997-09-14 03:53:16 jfieber Exp $ -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
<bookinfo>
<bookbiblio>
<title/Upgrading FreeBSD from source/
<title/<quote>Making the world</quote> your own/
<authorgroup>
<author>
<firstname/Nik/
<surname/Clayton/
<affiliation>
<address><email/Nik.Clayton@blueberry.co.uk/</address>
<address><email/Nik.Clayton@iii.co.uk/</address>
</affiliation>
</author>
</authorgroup>
<pubdate>$Date: 1997-06-25 16:57:02 $</pubdate>
<pubdate>$Date: 1997-09-14 03:53:16 $</pubdate>
</bookbiblio>
</bookinfo>
<preface>
<title/Overview/
<para>After following the instructions in the handbook, and acquiring the
latest copies of the FreeBSD source code, you now want to upgrade your
system to the latest and greatest. There are a number of steps to go
through in order to do this.</para>
<para>This document assumes that you have downloaded a version of the
FreeBSD source code and placed it in <filename>/usr/src</filename>. This
might be the latest version from the -current development branch, or
perhaps you're just tracking -stable. Either way, you have the source
code and now need to update your system.</para>
<para>This document takes you through those steps one by one.</para>
<para>There are a number of steps to perform to do this, and a few
pitfalls to avoid along the way. This document takes you through
those necessary steps one by one.</para>
<warning>
<title>Take a backup</title>
<para>I cannot stress highly enough how important it is to take a backup
of your system <emphasis>before</emphasis> you do this. While remaking
the world is (as long as you follow these instructions) an easy task to
do, there will inevitably be times when you make mistakes, or when
mistakes made by others in the source tree render your system
unbootable.</para>
<para>Make sure you've taken a backup. And have a fixit floppy to
hand. I've never needed to use them, and, touch wood, I never will,
but it's always better to be safe than sorry.</para>
</warning>
<note>
<title>2.1.7 specific</title>
<para>This document was written and tested with FreeBSD
2.1.7-RELEASE. That was a while ago (at the time of writing
2.2.5-RELEASE is perhaps 30 days away. Most of the information pertains
to all versions of FreeBSD greater than 2.1. Where there are specific
differences between versions (and where I'm aware of them) I'll note
them. If you know of a difference between different versions that
impacts on this document, please let me know.</para>
</note>
</preface>
<chapter>
@ -68,8 +98,8 @@
from a running system, which will drop it to single user mode.</para>
<para>Alternatively, reboot the system, and at the boot prompt, enter the
-s flag. The system will then boot single user. At the shell prompt you
should then run
<option>-s</option> flag. The system will then boot single user. At the
shell prompt you should then run
<informalexample>
<screen><prompt/#/ <userinput/fsck -p/
@ -82,6 +112,15 @@
mounts all the other UFS filesystems referenced in
<filename>/etc/fstbab</filename> and then turns swapping on.</para>
<para>For extra speed, you can also do
<informalexample>
<screen><prompt/#/ <userinput/mount -u -o async -t ufs -a/</screen>
</informalexample>
which remounts all your UFS filesystems for asynchronous access. The
trade off is that if the power suddenly fails while the system is being
rebuilt you are more likely to suffer from filesystem corruption.</para>
</chapter>
<chapter>
@ -116,12 +155,26 @@
<para>Other shells have their own constructs to do the same
thing.</para>
<para>Alternatively, if you don't care to use shell redirection, you
could use <command>script</command> to save a copy of all the
output.</para>
<informalexample>
<screen><prompt/#/ <userinput>script /var/tmp/mw.out</userinput>
Script started, output file is /var/tmp/mw.out
<prompt/#/ <userinput/make world/
<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>
<prompt/#/ <userinput/exit/
Script done, &hellip;
</screen>
</informalexample>
</note>
<para>Then go and make yourself several cups of tea. Remaking the world is
a long process. One of our servers, a 200Mhz P6 with fairly
run-of-the-mill SCSI disks, 64MB RAM and 256MB swap it takes a shade under
two hours to complete.</para>
run-of-the-mill SCSI disks, 64MB RAM and 256MB swap it takes a shade
under two hours to complete.</para>
<para>One of the 32MB (128MB swap), P133 machines takes about 5
hours.</para>
@ -158,8 +211,9 @@
<screen><prompt/#/ <userinput>cp -rp /etc /etc.old</userinput></screen>
</informalexample>
will do the trick (-r does a recursive copy, -p preserves times,
ownerships on files and suchlike).</para>
will do the trick (<option>-r</option> does a recursive copy,
<option>-p</option> preserves times, ownerships on files and
suchlike).</para>
</sect1>
<sect1>
@ -200,7 +254,8 @@
to get rid of them is to do
<informalexample>
<screen><prompt/#/ <userinput>find -d . -type d | /usr/bin/perl -lne \
<screen><prompt/#/ <userinput>cd /var/tmp/root</userinput>
<prompt/#/ <userinput>find -d . -type d | /usr/bin/perl -lne \
'opendir(D,$_);@f=readdir(D);rmdir if $#f != 1;closedir(D);'</userinput></screen>
</informalexample>
@ -226,9 +281,9 @@
<command/ls -a/ to catch them.</para>
<para>The simplest way to do this is to use the <command/diff/ command to
compare the two files. Use either the '-c' for the context output format,
or '-u' for the unified output format. I find it easier to read context
diffs.</para>
compare the two files. Use either the <option>-c</option> for the context
output format, or <option>-u</option> for the unified output format. I
find it easier to read context diffs.</para>
<para>For example,
@ -337,7 +392,7 @@
</tgroup>
</informaltable></para>
<para>That is not an exhaustive list, and changes to FreeBSd in the future
<para>That is not an exhaustive list, and changes to FreeBSD in the future
may necessitate moving files from the <emphasis/Copy/ column to the
<emphasis/Merge/ column. But you get the idea.</para>
@ -346,13 +401,12 @@
and correct before you reboot.</para>
<note>
<title><filename>/etc/rc.conf</filename></title>
<title><filename>/etc/rc.conf</filename> and
<filename>/etc/rc.network</filename></title>
<para>I note from the mailing lists that
<filename>/etc/sysconfig</filename> is being renamed to
<filename>/etc/rc.conf</filename>, and that the contents of the file may
be altering. I can not currently build a system to include these changes
in this document.</para>
<para>Starting with FreeBSD 2.2.2-RELEASE,
<filename/sysconfig/ has been renamed to <filename/rc.conf/, and
<filename/netstart/ has been renamed to <filename/rc.network/.</para>
</note>
</chapter>
@ -371,8 +425,8 @@
<para>This gives you a reference for when things go wrong&hellip; Run a
quick diff over these two files to see if anything's missing. If you use
slices in your disk partitioning (which may not be necessary on a
'dangerously dedicated' disk) then these slices have almost certainly not
been made.</para>
<quote>dangerously dedicated</quote> disk) then these slices have almost
certainly not been made.</para>
<para>Note down the devices that exist in <filename/dev1.out/ and not
<filename/dev2.out/, and the necessary commands to remake them.</para>
@ -407,17 +461,6 @@
<filename>/etc</filename> (which is probably a good idea, you may as well
generate it fresh), run <command/tzsetup/ (in
<filename>/usr/sbin</filename>) to set your timezone.</para>
</chapter>
<chapter>
<title/Rebooting/
<para>You're now done. After you've verified that everything appears to be
in the right place (pay particular attention to the <emphasis/emphasised/
files listed earlier), you can reboot the system. A simple
<command/fastboot/ should do it.</para>
</chapter>
<chapter>
@ -433,8 +476,32 @@
<filename/LINT/ config file to see if there are any new options which you
should take advantage of.</para>
<para>Once your new kernel is built and installed, reboot.</para>
<para>A previous version of this document suggested rebooting before
rebuilding the kernel. This is wrong because: </para>
<itemizedlist>
<listitem><para>Commands like <command/ps/, <command/ifconfig/ and
<command/sysctl/ may fail. This could leave your machine unable to
connect to the network.</para></listitem>
<listitem><para>Basic utilities like <command/mount/ could fail,
making it impossible to mount <filename>/</filename>,
<filename>/usr</filename> and so on. This is unlikely if you're
tracking a -stable candidate, but more likely if you're tracking
-current during a large merge.</para></listitem>
</itemizedlist>
<para>For these reasons, it is always best to rebuild and install a
new kernel before rebooting.</para>
</chapter>
<chapter>
<title/Rebooting/
<para>You're now done. After you've verified that everything appears to be
in the right place (pay particular attention to the <emphasis/emphasised/
files listed earlier), you can reboot the system. A simple
<command/fastboot/ should do it.</para>
</chapter>
<chapter>
@ -476,9 +543,10 @@
linked).</para>
<para>At the end of the day, it's your call. You might be happy
re-making the world every fortnight say, and let changes accumulate over
that fortnight. Or you might want to re-make just those things that have
changed, and are confident you can spot all the dependencies.</para>
re-making the world every fortnight say, and let changes accumulate
over that fortnight. Or you might want to re-make just those things
that have changed, and are confident you can spot all the
dependencies.</para>
<para>And, of course, this all depends on how often you want to upgrade,
and whether you are tracking -stable, a release candidate (2.2 at the
@ -492,6 +560,105 @@
problems.</para>
</sect1>
<sect1>
<title>My compile failed with lots of signal 12 (or other signal number)
errors</title>
<para>This is normally indicative of hardware problems. (Re)making the
world is an effective way to stress test your hardware, and will
frequently throw up memory problems. These normally manifest themselves
as the compiler mysteriously dieing on receipt of strange
signals.</para>
<para>A sure indicator of this is if you can restart the make and it
dies at a different point in the process.</para>
<para>In this instance there is little you can do except start swapping
around the components in your machine to determine which one is
failing.</para>
</sect1>
<sect1>
<title>Can I remove <filename>/usr/obj</filename> when I've
finished?</title>
<para>That depends on how you want to make the world on future
occasions.</para>
<para><filename>/usr/obj</filename> contains all the object files
that were produced during the compilation phase. Normally, one of the
first steps in the <quote/make world/ process is to remove this
directory and start afresh. In this case, keeping
<filename>/usr/obj</filename> around after you've finished makes
little sense, and will free up a large chunk of disk space (currently
about 150MB).</para>
<para>However, if you know what you're doing you can have <quote/make
world/ skip this step. This will make subsequent builds run much
faster, since most of sources will not need to be recompiled. The flip
side of this is that subtle dependency problems can creep in, causing
your build to fail in odd ways. This frequently generates noise on the
FreeBSD mailing lists, when one person complains that their build has
failed, not realising that it's because they've tried to cut
corners.</para>
<para>If you want to live dangerously then make the world, passing the
<quote/NOCLEAN/ definition to make, like this;
<informalexample>
<screen><prompt/#/ <userinput>make -DNOCLEAN world</userinput></screen>
</informalexample>
</para>
</sect1>
<sect1>
<title>My compile failed with a particular error, which I've now
fixed. Do I need to remake the world (and lose the result of the
previous build) or can I continue from where I left off?</title>
<para>This depends on how far through the process you got before you
found a problem.</para>
<para><emphasis>In general</emphasis> (and this is not a hard and fast
rule) the <quote>make world</quote> process builds new copies
essential tools (such as <command>gcc</command>, and
<command>make</command>) and the system libraries. These tools and
libraries are then installed. The new tools and libraries are then
used to rebuild themselves, and are installed again. The entire system
(now including regular user programs, such as <command>ls</command> or
<command>grep</command>) is then rebuilt with the new system
files.</para>
<para>If you're at the last state, and you know it (because you've
looked through the output that you were storing) then you can (fairly
safely) do
<informalexample>
<screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
<prompt/#/ <userinput>cd /usr/src</userinput>
<prompt/#/ <userinput/make -DNOCLEAN all/
</screen>
</informalexample>
which will not undo the work of the previous <quote>make
world</quote>.</para>
<para>If you see the message
<screen>
--------------------------------------------------------------
Building everything..
--------------------------------------------------------------
</screen>
in the <quote>make world</quote> output then it's probably fairly safe
to do so.</para>
<para>If you don't see that message, or you're not sure, then it's always
better to be safe than sorry, and restart the build from
scratch.</para>
</sect1>
<sect1>
<title/Can I use one machine as a <emphasis/master/ to upgrade lots of
machines?/
@ -534,6 +701,58 @@ Antonio
<para>Which sounds interesting. Note that, of course, you will not
upgrade the target machines <filename>/etc</filename> directory (and
others as outlined above) by doing this.</para>
<note>
<title>2.2.2-RELEASE and up</title>
<para>My FreeBSD 2.2.2-RELEASE system shows a <quote>reinstall</quote>
target in <filename>/usr/src/Makefile</filename>. The comment for
this includes:</para>
<programlisting>
# reinstall
#
# If you have a build server, you can NFS mount the source and obj directories
# and do a 'make reinstall' on the *client* to install new binaries from the
# most recent server build.
</programlisting>
<para>I have no idea how well this works, or whether it is present in
earlier versions of FreeBSD. I mention it here for
completeness.</para>
</note>
</sect1>
</chapter>
<chapter>
<title>Contributors</title>
<para>The following people have contributed to this document in some form
or another. Either by directly suggesting alterations and improvements,
or by their messages to the FreeBSD mailing lists, from which I have
shamelessly cribbed information. My thanks to them.</para>
<itemizedlist>
<listitem>
<para>Kees Jan Koster, &lt;<ulink url="mailto:kjk1@ukc.ac.uk">kjk1@ukc.ac.uk</ulink>&gt;</para>
</listitem>
<listitem>
<para>A Joseph Kosy, &lt;<ulink url="mailto:koshy@india.hp.com">koshy@india.hp.com</ulink>&gt;</para>
</listitem>
<listitem>
<para>Greg Lehey, &lt;<ulink url="mailto:grog@lemis.com">grog@lemis.com</ulink>&gt;</para>
</listitem>
<listitem>
<para>Wes Peters, &lt;<ulink
url="mailto:softweyr@xmission.com">softweyr@xmission.com</ulink>&gt;</para>
</listitem>
<listitem>
<para>Joseph Stein, &lt;<ulink url="mailto:joes@joes.users.spiritone.com">joes@joes.users.spiritone.com</ulink>&gt;</para>
</listitem>
</itemizedlist>
</chapter>
</book>