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

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