4 This section contains the contents of the old UPGRADE.TXT
8 <title>Upgrading &os;</title>
10 <para>These instructions describe a procedure for doing a binary
11 upgrade from an older version of &os;.</para>
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
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>
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>
41 <para>These upgrade instructions are provided for the use of users
42 upgrading from relatively recent &os; &release.branch;
47 <title>Introduction</title>
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>
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>
59 <title>Upgrade Overview</title>
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
66 <para>System configuration is preserved by retaining and
67 restoring the previous version of the following files:</para>
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>
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>
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>
153 <title>Procedure</title>
155 <para>This section details the upgrade procedure. Particular
156 attention is given to items which substantially differ from a
157 normal installation.</para>
160 <title>Backup</title>
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>
169 <title>Mount Filesystems</title>
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
181 <title>Select Distributions</title>
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>
193 <title>After Installation</title>
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>
205 <title>Upgrading from Source Code</title>
207 <para>Those interested in an upgrade method that allows more
208 flexibility and sophistication should take a look at
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>
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