Re: Review of minimal-upgrade chapter (was Re: Request for CVS commit access)
On Sun, Apr 01, 2007 at 03:24:30PM +0200, Javier Fernández-Sanguino Peña wrote:
> On Sun, Apr 01, 2007 at 05:07:27AM -0700, Steve Langasek wrote:
> > This reworks a lot of the documentation for upgrades, which I know you've
> > been working on as well; I've looked over the changes that you've made since
> > I've started, incorporated some of them, and explain here why I think others
> > should be dropped.
> I've gone through it and it looks good to me.
Ok, thanks.
> > - mentioning specific debconf questions (console-common, debconf):
> > these questions will not be asked of all users; it depends on what
> > questions they've answered before, what their debconf settings are in the
> > first place, and so on. If you think debconf needs to be mentioned, I
> > recommend that this be moved to an earlier section and made more generic.
> These questions are asked (from my experience) in both desktop and server
> sarge installations (unless, of course, you setup a high priority for debconf
> already). But, anyway, I don't mind it dropping.
Yes, users may have set high priority; or they may have originally upgraded
from /woody/, which IIRC had 'high' as the default.
I'm happy to rewrite this in a generic form if you think it should be
included, and if someone can suggest a place for insertion.
> > Comments welcome; once this is sorted to a point that it's acceptable to
> > commit, I'm hoping to look at the section on kernel upgrades, to synchronize
> > it with this section.
> Good.
> Currently the kernel upgrade section is written based on these
> recommendations (to try to lower the number and minimise the issues
> if rebooted in the middle of the upgrade):
> - if using 2.4:
> - (if you rely on hotplug -the package- support). Two options:
> - (recommended) upgrade to sarge's 2.6 kernel, test and follow then the
> recommendations for 2.6 sarge kernel upgrades (see below)
> - (not recommended, "upgrade within an upgrade") upgrade to etch's
> 2.6 kernel after a minimal upgrade, test, proceed with full upgrade
I'm not sure that upgrading to 2.6.8 first is beneficial. If the user needs
hotplug in 2.4, they will need udev in 2.6, and the etch udev won't support
either of the sarge kernels reliably. Further, although installing 2.6.8
first before upgrading gives the user a chance to test 2.6 support in a
setting where they can still downgrade to 2.4 to fix things if it's broken,
there are plenty of driver changes between 2.6.8 and 2.6.18 as well, so
2.6.8 is *not* guaranteed to be a good model for success with 2.6.18.
If you think it's going to still be helpful to enough users, I have no
problem with documenting this option, but I think these caveats should be
made clear.
Also, if the user does upgrade the kernel to 2.6.18 after the minimal
upgrade, I don't think we should recommend rebooting to test at that point.
Any testing can be deferred until the end of the dist-upgrade without risks
(the only risk is an unintentional reboot, and then they're no worse off),
and it allows the user to reduce the downtime by only rebooting once at the
end. It also gives the user a chance to clean all old libraries out of
memory, which otherwise wouldn't happen for services that were upgraded
before the upgrade of libraries they depend on.
> *or*
> - (if you do not rely on hotplug). Two options:
> - (recommended, but no risks here) do full upgrade, then upgrade
> to etch's 2.6 kernel
> - (not recommended, "upgrade within upgrade") do minimal upgrade,
> upgrade to etch's 2.6 kernel, test and then do full upgrade.
Again, I see no reason that the kernel upgrade needs to be deferred to the
end, so I think it's simpler to explain to just do the kernel upgrade early,
at the same point as for hotplug users. Do you agree?
> - if using 2.6:
> - (recommended, reduces issues even if it is an "upgrade within an
> upgrade") do minimal upgrade, upgrade the kernel, test and then do full
> upgrade
> *or*
> - (not recommended, risky) do all the upgrade, and then upgrade the kernel
Definitely agreed, except for the "test" part as mentioned above.
> One comment: should we tell the users which packages we expect to be removed
> in these steps. Since you're saying the user should act judiciously(sp?) by
> watching removals it would be good to point out known removals (such as
> base-config)
Yes, that seems like a good idea to me. Short list included, of the most
obvious important packages removed in my tests; feel free to extend it.
> > + <sect2 id="minimal_upgrade_desktop"><heading>Upgrading a desktop system</heading>
> > + <p>This upgrade path has been verified to work on systems with the sarge
> > + <tt>desktop</tt> task installed. It is probably the method that will give
> > + the best results on systems with the <tt>desktop</tt> task installed, or
> > + with the <tt>gnome</tt> or <tt>kde</tt> packages installed.
> Shouldn't we advise people to check first this:
> > -# dpkg -l "libfam*" | grep ^ii
> > -# dpkg -l "xlibmesa-glu*" | grep ^ii
> I've not done any tests with custom desktop environments but there might be some
> circunmstances (xfce? wmaker?) in which the next step:
> > <example>
> > # aptitude install libfam0 xlibmesa-glu
> > </example></p>
> might just need to be this instead:
> # aptitude install xlibmesa-glu
> Do all X11 desktops (xfce/wmaker included) depend on fam in etch?
xfce in sarge doesn't depend on libfam0. wmaker doesn't depend on either of
these libraries. (Kinda funny that installing the server tasks will install
libfam0, but installing some desktops won't, eh?)
Installing xfce4 in etch will pull in libgamin0, which is the same ABI as
libfam0. Installing wmaker in etch still doesn't pull in either lib.
Anyway, the point is taken, so I've re-included some bits about this.
> > + <p>Systems with some X packages installed, but not the full
> > + <tt>desktop</tt> task, require a different method. This method applies in
> > + general to systems with <tt>xfree86-common</tt> installed, including some
> That <tt>xfree86-common</tt> should be <package/xfree86-common/ instead.
Yah, fixed.
> Why not add this in there too (for those who like cut&paste):
> > - <example>
> > -# dpkg -l "xfree86-common*" | grep ^ii
> > - </example>
Sure, added.
> > + removals, it is recommended that you upgrade the kernel at this point.
> > + The reason for this is that the next step will install the latest
> > + <package/udev/ and remove <package/hotplug/, removing hotplug support for
> > + Linux kernels before 2.6.15 at some point during the
> > + <tt>dist-upgrade</tt>. Although this should not remove any kernels you
> I think it should be "removing hotplug support" not (for Linux kernels..)
> since this applies to 2.4 kernels too.
Sorry, I don't understand what you mean. This upgrade removes hotplug
support for all Linux kernels before 2.6.15; that includes Linux 2.4 and
linux 2.6.0-2.6.14. For 2.6 kernels, hotplug support is *normally* provided
by udev -- but the hotplug package *can* be used, if it's installed (which
it won't be on a system using a Debian kernel package).
> > + <p>In the desktop case, it is unfortunately not possible to ensure the
> > + new kernel package is installed immediately after the new <package/udev/
> > + is installed, so there is a window of unknown length when your system
> > + will have no kernel installed with full hotplug support. See <ref
> > + id="newkernel"> for information on configuring your system to not depend
> > + on hotplug for booting.</p>
> Is this comment about hotplug support true for 2.6 kernels?
Yes, it is.
> (I read it and I think about the hotplug package, not the functionality,
> maybe it should be rephrased)
Suggestions welcome, 'hotplug' is the name of the kernel interface.
Updated patch attached now.
Thanks,
--
Steve Langasek Give me a lever long enough and a Free OS
Debian Developer to set it on, and I can move the world.
vorlon@debian.org http://www.debian.org/
Index: en/release-notes.en.sgml
===================================================================
RCS file: /cvs/debian-doc/ddp/manuals.sgml/release-notes/en/release-notes.en.sgml,v
retrieving revision 1.210
diff -u -r1.210 release-notes.en.sgml
--- en/release-notes.en.sgml 31 Mar 2007 22:45:06 -0000 1.210
+++ en/release-notes.en.sgml 1 Apr 2007 23:10:49 -0000
@@ -707,7 +707,7 @@
</sect1>
- <sect1><heading>Prepair a safe environment for the upgrade</heading>
+ <sect1 id="upgrade_preparations"><heading>Prepare a safe environment for the upgrade</heading>
<p>The distribution upgrade should be done either locally from a
textmode virtual console (or a directly connected serial
@@ -1212,22 +1212,23 @@
<sect1 id="minimal_upgrade"><heading>Minimal system upgrade</heading>
- <p>Before you start the full upgrade you have to make a minimal system upgrade
- to ensure you have the basic system libraries upgraded.</p>
+ <p>Because of certain necessary package conflicts between &oldreleasename;
+ and &releasename;, running <tt>aptitude dist-upgrade</tt> directly will
+ often remove large numbers of packages that you will want to keep. We
+ therefore recommend a two-part upgrade process, first a minimal upgrade to
+ overcome these conflicts, then a full <tt>dist-upgrade</tt>.
+ </p>
- <p>First run:
+ <p>First, run:
<example>
# aptitude upgrade
</example>
</p>
-
- <p>This will upgrade a number of packages, include <package/base-files/,
- <package/console-common/, and <package/debconf/. You will be asked information
- about your console keymap as well as the default level and frontend for
- package configuration questions.</p>
- <p>You have to follow the minimal upgrade with:
+ <p>This has the effect of upgrading those packages which can be upgraded
+ without requiring any other packages to be removed or installed.</p>
+ <p>Follow the minimal upgrade with:
<example>
# aptitude install initrd-tools
</example></p>
@@ -1237,65 +1238,123 @@
(<package/libselinux1/). At this point, some running services will be
restarted, including <prgn/xdm/, <prgn/gdm/ and <prgn/kdm/, as a
consequence local X11 sessions will be disconnected.</p>
-
- <p>The following step depends on your system configuration:
- <p><list>
- <item><p>If you are running a system with a Desktop environment, you first
- have to verify if you have <package/libfam0c102/ and <package/xlibmesa-glu/
- installed. You have them installed if you have selected &oldreleasename;'s
- Desktop task but if you have a custom-made environment you have to manually
- verify it:
+ <p>The next step will vary depending on the set of packages that you have
+ installed. These release notes give general advice about which method
+ should be used, but if in doubt, it is recommended that you examine the
+ package removals proposed by each method before proceeding.</p>
+ <p>Some common packages that are expected to be removed include
+ <package/base-config/, <package/hotplug/, <package/xlibs/,
+ <package/netkit-inetd/, <package/python2.3/, <package/xfree86-common/,
+ and <package/xserver-common/. For a more complete list of packages
+ obsoleted in &releasename;, see <ref id="obsolete">.
+ </p>
+
+ <sect2 id="minimal_upgrade_desktop"><heading>Upgrading a desktop system</heading>
+ <p>This upgrade path has been verified to work on systems with the sarge
+ <tt>desktop</tt> task installed. It is probably the method that will give
+ the best results on systems with the <tt>desktop</tt> task installed, or
+ with the <tt>gnome</tt> or <tt>kde</tt> packages installed.
+
+ <p>It is probably <em>not</em> the correct method to use if you do not
+ already have the <package/libfam0c102/ and <package/xlibmesa-glu/ packages
+ installed:
<example>
-# dpkg -l "libfam*" | grep ^ii
-# dpkg -l "xlibmesa-glu*" | grep ^ii
+# dpkg -l libfam0c102 | grep ^ii
+# dpkg -l xlibmesa-glu | grep ^ii
</example>
+ </p>
- if you have them installed then you have to install the latest
- versions from &releasename;. The following command will install both,
- if you have only one of them you should remove the other:
-
+ <p>If you do have a full desktop system installed, run:
<example>
# aptitude install libfam0 xlibmesa-glu
</example></p>
+ </sect2>
+
+ <sect2 id="minimal_upgrade_x_server"><heading>Upgrading a system with some X packages installed</heading>
+ <p>Systems with some X packages installed, but not the full
+ <tt>desktop</tt> task, require a different method. This method applies in
+ general to systems with <package/xfree86-common/ installed, including some
+ server systems which have <package/tasksel/ server tasks installed as some
+ of these tasks include graphical management tools. It is likely the
+ correct method to use on systems which run X, but do not have the full
+ <tt>desktop</tt> task installed.
+ <example>
+# dpkg -l xfree86-common | grep ^ii
+ </example>
+ </p>
+
+ <p>First, check whether you have the <package/libfam0c102/ and
+ <package/xlibmesa-glu/ packages installed.
+ <example>
+# dpkg -l libfam0c102 | grep ^ii
+# dpkg -l xlibmesa-glu | grep ^ii
+ </example>
+ </p>
+
+ <p>If you do not have <package/libfam0c102/ installed, do not include
+ <package/libfam0/ in the following commandline. If you do not have
+ <package/xlibmesa-glu/ installed, do not include it in the following
+ commandline.
+ <footnote>This command will determine whether you need libfam0 and
+ xlibmesa-glu installed, and auto-select them for you:
+ <example>
+# aptitude install x11-common \
+ $(dpkg-query --showformat '${Package} ${Status}\n' -W libfam0c102 xlibmesa-glu \
+ | grep 'ok installed$' | sed -e's/ .*//; s/c102//')
+ </example>
+ </footnote>
+
+ <example>
+# aptitude install <var>libfam0</var> <var>xlibmesa-glu</var> x11-common
+ </example>
+ </p>
+
<p>Note that doing this will also install the File Alteration Monitor
(<package/fam/) as well as the RPC portmapper (<package/portmap/) if
not already available in your system. Both packages will enable a new
network service in the system although they can both be configured to
be bound to the (internal) loopback network device.</p>
+ </sect2>
- <item><p>For all other systems, verify if you have any
- X Window System packages installed by running the following command:
- <example>
-# dpkg -l "xfree86-common*" | grep ^ii
- </example>
+ <sect2 id="minimal_upgrade_server"><heading>Upgrading a system with no X support installed</heading>
+ <p>On a system with no X, no additional aptitude install command should be
+ required, and you can move on to the next step.
+ </p>
+
+ </sect2>
+
+ </sect1>
- Notice that if you selected some server tasks in &oldreleasename; you
- might have parts of it installed. If you have the X Window System
- installed you will need to upgrade to the latest version in
- &releasename;:
+ <sect1 id="upgrading_kernel"><heading>Upgrading the kernel</heading>
+ <p>If your system does not have the <tt>desktop</tt> task installed, or
+ other packages that would cause an unacceptable number of package
+ removals, it is recommended that you upgrade the kernel at this point.
+ The reason for this is that the next step will install the latest
+ <package/udev/ and remove <package/hotplug/, removing hotplug support for
+ Linux kernels before 2.6.15 at some point during the
+ <tt>dist-upgrade</tt>. Although this should not remove any kernels you
+ currently have installed, in some cases your previous kernel will not
+ detect and load drivers for all hardware if booted without compatible
+ hotplug support. See <ref id="upgrade_preparations"> for recommendations
+ on preparing for this possibility if you are upgrading remotely.</p>
+
+ <p>To proceed with this kernel upgrade, run:
<example>
-# aptitude install x11-common
+# aptitude install linux-image-2.6-<var>flavor</var>
</example>
- <p>If you are running a server system, with no X packages
- installed, you do not need to do any additional installation steps.
- </p>
-
- </list></p>
+ See <ref id="newkernel"> for help in determining which flavor of kernel
+ package you should install.</p>
- <p>Note: After this minimal upgrade has finished you might want to
- consider upgrading the kernel before upgrading the full system,
- as described in <ref id="newkernel">.
- Doing so reduces the timeframe in which the system will not
- properly boot if rebooted accidentally.
- This is because the full upgrade described in the next section will
- install a new version of <prgn/udev/ and will remove <prgn/hotplug/.
- This might not be an option for systems with a Desktop environment,
- as large parts of the system will be removed if you do the kernel
- upgrade here.</p>
+ <p>In the desktop case, it is unfortunately not possible to ensure the
+ new kernel package is installed immediately after the new <package/udev/
+ is installed, so there is a window of unknown length when your system
+ will have no kernel installed with full hotplug support. See <ref
+ id="newkernel"> for information on configuring your system to not depend
+ on hotplug for booting.</p>
</sect1>
Reply to: