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.3 2003/08/05 07:45:42 asmodai 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>localtime</filename>,
  86 <filename>login.access</filename>,
  87 <filename>login.conf</filename>,
  88 <filename>mail</filename>,
  89 <filename>mail.rc</filename>,
  90 <filename>make.conf</filename>,
  91 <filename>manpath.config</filename>,
  92 <filename>master.passwd</filename>,
  93 <filename>modems</filename>,
  94 <filename>motd</filename>,
  95 <filename>namedb</filename>,
  96 <filename>networks</filename>,
  97 <filename>newsyslog.conf</filename>,
  98 <filename>nsmb.conf</filename>,
  99 <filename>pam.conf</filename>,
 100 <filename>passwd</filename>,
 101 <filename>periodic</filename>,
 102 <filename>ppp</filename>,
 103 <filename>printcap</filename>,
 104 <filename>profile</filename>,
 105 <filename>pwd.db</filename>,
 106 <filename>rc.conf</filename>,
 107 <filename>rc.conf.local</filename>,
 108 <filename>rc.firewall</filename>,
 109 <filename>rc.local</filename>,
 110 <filename>remote</filename>,
 111 <filename>resolv.conf</filename>,
 112 <filename>rmt</filename>,
 113 <filename>sendmail.cf</filename>,
 114 <filename>sendmail.cw</filename>,
 115 <filename>services</filename>,
 116 <filename>shells</filename>,
 117 <filename>skeykeys</filename>,
 118 <filename>spwd.db</filename>,
 119 <filename>ssh</filename>,
 120 <filename>syslog.conf</filename>,
 121 <filename>ttys</filename>,
 122 <filename>uucp</filename>
 123 </para>
 124
 125       <para>The versions of these files which correspond to the new
 126       version are moved to <filename>/etc/upgrade/</filename>.  The
 127       system administrator may peruse these new versions and merge
 128       components as desired.  Note that many of these files are
 129       interdependent, and the best merge procedure is to copy all
 130       site-specific data from the current files into the new.</para>
 131
 132       <para>During the upgrade procedure, the administrator is
 133       prompted for a location into which all files from
 134       <filename>/etc/</filename> are saved.  In the event that local
 135       modifications have been made to other files, they may be
 136       subsequently retrieved from this location.</para>
 137
 138     </sect3>
 139   </sect2>
 140
 141   <sect2>
 142     <title>Procedure</title>
 143
 144     <para>This section details the upgrade procedure.  Particular
 145     attention is given to items which substantially differ from a
 146     normal installation.</para>
 147
 148     <sect3>
 149       <title>Backup</title>
 150
 151       <para>User data and system configuration should be backed up
 152       before upgrading.  While the upgrade procedure does its best
 153       to prevent accidental mistakes, it is possible to partially or
 154       completely destroy data and configuration information.</para>
 155     </sect3>
 156
 157     <sect3>
 158       <title>Mount Filesystems</title>
 159
 160       <para>The disklabel editor is entered with the nominated disk's
 161       filesystem devices listed.  Prior to commencing the upgrade, the
 162       administrator should make a note of the device names and
 163       corresponding mountpoints.  These mountpoints should be entered
 164       here.  <emphasis>Do not</emphasis>set the <quote>newfs
 165       flag</quote> for any filesystems, as this will cause data
 166       loss.</para>
 167     </sect3>
 168
 169     <sect3>
 170       <title>Select Distributions</title>
 171
 172       <para>When selecting distributions, there are no constraints
 173       on which must be selected.  As a general rule, the <literal>bin</literal>
 174       distribution should be selected for an update, and the <literal>man</literal>
 175       distribution if manpages are already installed.  Other
 176       distributions may be selected beyond those originally
 177       installed if the administrator wishes to add additional
 178       functionality.</para>
 179     </sect3>
 180
 181     <sect3 id="fstab">
 182       <title>After Installation</title>
 183
 184       <para>Once the installation procedure has completed, the
 185       administrator is prompted to examine the new configuration
 186       files.  At this point, checks should be made to ensure that the
 187       system configuration is valid.  In particular, the
 188       <filename>/etc/rc.conf</filename> and
 189       <filename>/etc/fstab</filename> files should be checked.</para>
 190     </sect3>
 191   </sect2>
 192
 193   <sect2>
 194     <title>Upgrading from Source Code</title>
 195
 196     <para>Those interested in an upgrade method that allows more
 197     flexibility and sophistication should take a look at
 198     <ulink
 199     url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/cutting-edge.html">The
 200     Cutting Edge</ulink> in the &os; Handbook.  This procedure involves
 201     rebuilding all of &os; from source code.  It requires reliable
 202     network connectivity, extra disk space, and time, but has
 203     advantages for networks and other more complex
 204     installations.  This is roughly the same procedure as is used for
 205     track the -STABLE or -CURRENT development branches.</para>
 206
 207     <para><filename>/usr/src/UPDATING</filename> contains important
 208     information on updating a &os; system from source code.  It lists
 209     various issues resulting from changes in &os; that may affect an
 210     upgrade.<para>
 211   </sect2>
 212 </sect1>