release/doc/en_US.ISO8859-1/installation/common/upgrade.sgml

   1 <!--
   2         $FreeBSD$
   3
   4         This section contains the contents of the old UPGRADE.TXT
   5         file.
   6 -->
   7 <sect1 id="upgrading">
   8   <title>Upgrading &os;</title>
   9
  10   <para>These instructions describe a procedure for doing a binary
  11   upgrade from an older version of &os;.</para>
  12
  13   <warning>
  14     <para>While the &os; upgrade procedure does its best to
  15     safeguard against accidental loss of data, it is still more than
  16     possible to <emphasis>wipe out your entire disk</emphasis> with
  17     this installation!  Please do not accept the final confirmation
  18     request unless you have adequately backed up any important data
  19     files.</para>
  20   </warning>
  21
  22   <important>
  23     <para>These notes assume that you are using the version of
  24     &man.sysinstall.8; supplied with the version of &os; to which you
  25     intend to upgrade.  Using a mismatched version of &man.sysinstall.8; is
  26     almost guaranteed to cause problems and has been known to leave
  27     systems in an unusable state.  The most commonly made mistake in
  28     this regard is the use of an old copy of &man.sysinstall.8; from
  29     an existing installation to upgrade to a newer version of
  30     &os;.  This is <emphasis>not</emphasis> recommended.</para>
  31   </important>
  32
  33   <warning>
  34     <para>Binary upgrades to &os; &release.current; from &os; 4-STABLE
  35       are not supported at this time.  There are some files present in
  36       a &os; 4-STABLE whose presence can be disruptive, but are not
  37       removed by a binary upgrade.  One notable example is that an old
  38       <filename>/usr/include/g++</filename> directory will cause C++
  39       programs to compile incorrectly (or not at all).</para>
  40
  41     <para>These upgrade instructions are provided for the use of users
  42       upgrading from relatively recent &os; &release.branch;
  43       snapshots.</para>
  44   </warning>
  45
  46   <sect2>
  47     <title>Introduction</title>
  48
  49     <para>The upgrade procedure replaces distributions selected by the
  50     user with those corresponding to the new &os; release.  It
  51     preserves standard system configuration data, as well as user
  52     data, installed packages and other software.</para>
  53
  54     <para>Administrators contemplating an upgrade are encouraged to
  55     study this section in its entirety before commencing an upgrade.
  56     Failure to do so may result in a failed upgrade or loss of data.</para>
  57
  58     <sect3>
  59       <title>Upgrade Overview</title>
  60
  61       <para>Upgrading of a distribution is performed by extracting the
  62       new version of the component over the top of the previous
  63       version.  Files belonging to the old distribution are not
  64       deleted.</para>
  65
  66       <para>System configuration is preserved by retaining and
  67       restoring the previous version of the following files:</para>
  68
  69       <para><filename>Xaccel.ini</filename>,
  70 <filename>XF86Config</filename>,
  71 <filename>adduser.conf</filename>,
  72 <filename>aliases</filename>,
  73 <filename>aliases.db</filename>,
  74 <filename>amd.map</filename>,
  75 <filename>crontab</filename>,
  76 <filename>csh.cshrc</filename>,
  77 <filename>csh.login</filename>,
  78 <filename>csh.logout</filename>,
  79 <filename>cvsupfile</filename>,
  80 <filename>dhclient.conf</filename>,
  81 <filename>disktab</filename>,
  82 <filename>dm.conf</filename>,
  83 <filename>dumpdates</filename>,
  84 <filename>exports</filename>,
  85 <filename>fbtab</filename>,
  86 <filename>fstab</filename>,
  87 <filename>ftpusers</filename>,
  88 <filename>gettytab</filename>,
  89 <filename>gnats</filename>,
  90 <filename>group</filename>,
  91 <filename>hosts</filename>,
  92 <filename>hosts.allow</filename>,
  93 <filename>hosts.equiv</filename>,
  94 <filename>hosts.lpd</filename>,
  95 <filename>inetd.conf</filename>,
  96 <filename>localtime</filename>,
  97 <filename>login.access</filename>,
  98 <filename>login.conf</filename>,
  99 <filename>mail</filename>,
 100 <filename>mail.rc</filename>,
 101 <filename>make.conf</filename>,
 102 <filename>manpath.config</filename>,
 103 <filename>master.passwd</filename>,
 104 <filename>motd</filename>,
 105 <filename>namedb</filename>,
 106 <filename>networks</filename>,
 107 <filename>newsyslog.conf</filename>,
 108 <filename>nsmb.conf</filename>,
 109 <filename>nsswitch.conf</filename>,
 110 <filename>pam.conf</filename>,
 111 <filename>passwd</filename>,
 112 <filename>periodic</filename>,
 113 <filename>ppp</filename>,
 114 <filename>printcap</filename>,
 115 <filename>profile</filename>,
 116 <filename>pwd.db</filename>,
 117 <filename>rc.conf</filename>,
 118 <filename>rc.conf.local</filename>,
 119 <filename>rc.firewall</filename>,
 120 <filename>rc.local</filename>,
 121 <filename>remote</filename>,
 122 <filename>resolv.conf</filename>,
 123 <filename>rmt</filename>,
 124 <filename>sendmail.cf</filename>,
 125 <filename>sendmail.cw</filename>,
 126 <filename>services</filename>,
 127 <filename>shells</filename>,
 128 <filename>skeykeys</filename>,
 129 <filename>spwd.db</filename>,
 130 <filename>ssh</filename>,
 131 <filename>syslog.conf</filename>,
 132 <filename>ttys</filename>,
 133 <filename>uucp</filename>
 134 </para>
 135
 136       <para>The versions of these files which correspond to the new
 137       version are moved to <filename>/etc/upgrade/</filename>.  The
 138       system administrator may peruse these new versions and merge
 139       components as desired.  Note that many of these files are
 140       interdependent, and the best merge procedure is to copy all
 141       site-specific data from the current files into the new.</para>
 142
 143       <para>During the upgrade procedure, the administrator is
 144       prompted for a location into which all files from
 145       <filename>/etc/</filename> are saved.  In the event that local
 146       modifications have been made to other files, they may be
 147       subsequently retrieved from this location.</para>
 148
 149     </sect3>
 150   </sect2>
 151
 152   <sect2>
 153     <title>Procedure</title>
 154
 155     <para>This section details the upgrade procedure.  Particular
 156     attention is given to items which substantially differ from a
 157     normal installation.</para>
 158
 159     <sect3>
 160       <title>Backup</title>
 161
 162       <para>User data and system configuration should be backed up
 163       before upgrading.  While the upgrade procedure does its best
 164       to prevent accidental mistakes, it is possible to partially or
 165       completely destroy data and configuration information.</para>
 166     </sect3>
 167
 168     <sect3>
 169       <title>Mount Filesystems</title>
 170
 171       <para>The disklabel editor is entered with the nominated disk's
 172       filesystem devices listed.  Prior to commencing the upgrade, the
 173       administrator should make a note of the device names and
 174       corresponding mountpoints.  These mountpoints should be entered
 175       here.  <emphasis>Do not</emphasis> set the <quote>newfs
 176       flag</quote> for any filesystems, as this will cause data
 177       loss.</para>
 178     </sect3>
 179
 180     <sect3>
 181       <title>Select Distributions</title>
 182
 183       <para>When selecting distributions, there are no constraints
 184       on which must be selected.  As a general rule, the <literal>base</literal>
 185       distribution should be selected for an update, and the <literal>man</literal>
 186       distribution if manpages are already installed.  Other
 187       distributions may be selected beyond those originally
 188       installed if the administrator wishes to add additional
 189       functionality.</para>
 190     </sect3>
 191
 192     <sect3 id="fstab">
 193       <title>After Installation</title>
 194
 195       <para>Once the installation procedure has completed, the
 196       administrator is prompted to examine the new configuration
 197       files.  At this point, checks should be made to ensure that the
 198       system configuration is valid.  In particular, the
 199       <filename>/etc/rc.conf</filename> and
 200       <filename>/etc/fstab</filename> files should be checked.</para>
 201     </sect3>
 202   </sect2>
 203
 204   <sect2>
 205     <title>Upgrading from Source Code</title>
 206
 207     <para>Those interested in an upgrade method that allows more
 208     flexibility and sophistication should take a look at
 209     <ulink
 210     url="&url.books.handbook;/cutting-edge.html">The
 211     Cutting Edge</ulink> in the &os; Handbook.  This procedure involves
 212     rebuilding all of &os; from source code.  It requires reliable
 213     network connectivity, extra disk space, and time, but has
 214     advantages for networks and other more complex
 215     installations.  This is roughly the same procedure as is used for
 216     track the -STABLE or -CURRENT development branches.</para>
 217
 218     <para><filename>/usr/src/UPDATING</filename> contains important
 219     information on updating a &os; system from source code.  It lists
 220     various issues resulting from changes in &os; that may affect an
 221     upgrade.</para>
 222   </sect2>
 223 </sect1>