Bug#394929: [Etch] installation-guide-i386 - several steps are misleading or cannot be finished
Package: installation-guide-i386
Version: 20060726
Tags: d-i, etch
Overall experience with the current incarnation of the installation
guide with regard to appendix "D.3. Installing Debian GNU/Linux from a
Unix/Linux System" is that it's missing sevaral steps ore some of them
are misleading. Similar problems are also mirrored in the Ubuntu's
instalation guide, which I already reported in their BTS [1].
Disclaimer: please excuse my frequent references to the Ubuntu docs,
but I first encountered the same problems there and then quickly realized
that they may also affect Debian as well (and they do, indeed). It's
just that their docs already exist and are linkable, so I can point
to the right places instead of copying their content.
This report is the result of several days of intensive testing and
documenting problems with using debootstrap as a tool for installing
Debian Etch. I was encouraged to post such a bug report after consulting
debian-boot mailing list first [2].
Goal of this document
My main goal with manual installation using bootstrap was to install
a basesystem only, with equivalent settings that the debian-installer
does using official installation media. During that course I discovered
smaller and bigger issues, which are described in detail below.
D.3.1. Getting Started
From my observation, for a plain basesystem the required minimum space
is about 300MB. For default desktop installation it's about 2,7GB.
A side note: instalation leaves all of the downloaded .deb files in the
/var/cache/apt/archives directory. It can vary from 30MB to several
hundreds of MB. Maybe it would be advisable to add:
# apt-get autoclean
somewhere near the end of the guide?
D.3.2. Install debootstrap
Side note: I created two simple scripts for easy integrating debootstrap
with a running Linux installation (in my case PCLinuxOS and Gentoo), as
well as easy removal of the debootstrap files. This way I would be able
to remove them from the host OS after installing basesystem, but before
booting into newly installed Debian.
# mkdir -p ~/work
# cd ~/work
# wget http://ics.p.lodz.pl/~wiktorw/debootstrap/insert.sh
# wget http://ics.p.lodz.pl/~wiktorw/debootstrap/remove.sh
# wget http://ftp.pl.debian.org/debian/pool/main/d/debootstrap/debootstrap_0.3.3_all.deb
# ar -x debootstrap_0.3.3_all.deb data.tar.gz
# tar xzf data.tar.gz
# sh insert.sh #### (and "sh remove.sh" for removal)
You can use them freely if you find them useful. Nonetheless, original
instructions for merging debootstrap with host OS are perfectly fine.
D.3.3. Run debootstrap
In the example debootstrap invocation there is a following mirror site
mentioned: "http://http.us.debian.org/debian";. While this works with US
mirror, for most other national mirrors this url pattern is invalid.
Suggested is to replace "http://http.us.debian.org/debian"; with
"http://ftp.us.debian.org/debian":
# /usr/sbin/debootstrap --arch ARCH etch \
/mnt/debinst http://ftp.us.debian.org/debian #### suggested
This way one can easily substitute ftp.us.debian.org with other national
mirror, by simply changing the country code.
D.3.4. Configure The Base System
Before chrooting into newly installed envirnoment, it's advisable to
mount /dev directory of the host system inside chroot. From within
a running Linux installation this can be done via:
# mount -o bind /dev /mnt/debian/dev #### suggested
# LANG=C chroot /mnt/debian /bin/bash
This step ensures that all device nodes are actually accessible, or else
a grub installation may later fail (and it typically does). The reason
is that in static Debian /dev there are only nodes created by debotstrap,
extracted from its /usr/lib/debootstrap/devices.tar.gz file.
# export TERM=xterm-color #### suggested
Additionally, it's wise to change the terminal definition, to the one
compatible with the system being installed - and not using a copy of the
host OS setting (in my case it was TERM=gnome and nano refused to work).
D.3.4.1. Mount Partitions
# editor /etc/fstab
It's worth to note that the default d-i instalation contains a link to
the cdrom mountpoint (/media/cdrom -> /media/cdrom0). The guide never
points that out:
# cd /media #### suggested
# mkdir cdrom0 #### suggested
# ln -s cdrom0 cdrom #### suggested
# cd #### suggested
While the guide lists most commands the user should write in the boxes
with the silver background, sometimes commands are listed in plain text
with the boldface only. For consistency:
# mount -a #### suggested
As a side note, I've found that:
# mount -t proc proc /proc
was always necessary (both in Debian and Ubuntu).
D.3.4.2. Configure Keyboard #### suggested removal
The mentioned command:
# dpkg-reconfigure console-data #### PROBLEM HERE!
results in an error, as console-data is not installed at this point
by the bootstrap (package could not be found). It could be installed
manually, but on the other hand this step is not necessary - see D.3.4.5.
D.3.4.2. Setting Timezone #### suggested new section
Even though d-i in expert mode asks explicitely whether the system should
use UTC or not and guesses the timezone by the country/region selected,
the guide is completely missing this. So choose between UTC=yes / UTC=no
and select the timezone by executing:
# editor /etc/default/rcS #### suggested
# tzconfig #### suggested
D.3.4.3. Configure Networking
# editor /etc/network/interfaces
Excellent step here, especially examples. Even d-i doesn't do that :-)
# editor /etc/resolv.conf
# echo DebianHostName > /etc/hostname
However, I've found that while d-i puts some lines in /etc/hosts, the
guide doesn't have any pointers. The simplest and the most needed
(depicting localhost and host node as 127.0.0.1) is the following:
# echo "127.0.0.1 localhost DebianHostName" > /etc/hosts #### suggested
D.3.4.4. Configure apt Sources #### suggested
While the guide enigmatically mentions that "apt must be configured
beforehand by creating a sources.list and running aptitude update",
the person installing Debian from another Unix/Linux system is currently
required to have a proper understanding of /etc/sources.list syntax.
In short: a prior Debian experience is required. Additionally, the guide
doesn't promote good practices and doesn't even mention the security
update sites. If a user leaves only the default single line with the
mirror used for installation, he/she cuts itself out of security updates.
This can be avoided by providing a simple, yet effective example of apt's
sources.list configuration. I did it this way:
# cat >> /etc/apt/sources.list <<EOF #### suggested
deb-src http://ftp.us.debian.org/debian etch main #### suggested
deb http://security.debian.org/ etch/updates main #### suggested
deb-src http://security.debian.org/ etch/updates main #### suggested
EOF #### suggested
Of course, a small discussion of sources.list or a complete copy'n'paste
example is always welcome. Additionally, consider providing a link to the
apt's documentation regarding the sources.list file.
Since in the next sections some packages are going to be installed, it's
wise to execute two additional commands at this moment:
# editor /etc/apt/sources.list #### suggested
# apt-get update #### suggested
D.3.4.5. Configure Locales and Keyboard #### suggested new section
System-wide locale settings are placed in /etc/environment file. The d-i
does put a LANG= line there, but the guide completely leaves this file
alone. Consider adding LANGUAGE= and LANG= settings here:
# cat >> /etc/environment <<EOF #### suggested (ver.A)
LANGUAGE="de_DE:de:en_US:en" #### suggested (ver.A)
LANG="de_DE.UTF-8" #### suggested (ver.A)
EOF #### suggested (ver.A)
(de_DE locale has been chosen arbitrarily, personally I've used pl_PL).
Another alternative (and shorter) approach is following:
echo LANGUAGE=\"de_DE:de:en_US:en\" >> /etc/environment #### suggested
echo LANG=\"de_DE.UTF-8" >> /etc/environment #### (ver.B)
After that locales package should be installed and reconfigured:
# apt-get install locales
# dpkg-reconfigure locales
Then the new, console-setup package (the same the Ubuntu uses) should be
installed and reconfigured:
# apt-get install console-setup #### suggested
# dpkg-reconfigure console-setup #### suggested
(console-setup is much more than the old console-data package)
D.3.5. Install a Kernel
# apt-cache search linux-image
Prior to the installation of kernel, it would be wise to set some options
in /etc/kernel-img.conf for better integration with automatic kernel
update procedure:
# cat > /etc/kernel-img.conf <<EOF #### suggested
# Kernel Image management overrides #### suggested
# See kernel-img.conf(5) for details #### suggested
do_symlinks = yes #### suggested
relative_links = yes #### suggested
do_bootloader = no #### suggested
do_bootfloppy = no #### suggested
do_initrd = yes #### suggested
link_in_boot = no #### suggested
EOF #### suggested
If the above aren't set, kernel installation mercilesly warns about
missing "do_symlinks = yes" entry in /etc/kernel-img.conf file.
With the correct setting in place the kernel installation goes smoothly:
# apt-get install linux-image-2.6.17-arch-etc #### correction!
Note the "apt-get" invocation above, instead of "aptitude". Is aptitude
necessary for this at all?
It can be beneficial for some users to (optionally) install kernel
headers at this point (with gcc and some other packages as dependencies).
This is completely optional and in specific cases (e.g. a secure server)
not desirable at all. I've found that this package is suggested by the
linux-image-* packages, so I bring it to the table as well:
# apt-get install linux-kernel-headers-2.6.17-arch-etc #### optional
D.3.6. Set up the Boot Loader
By default, new Debian Etch installer proposes GRUB installation.
This is fine, however three simple lines can be a time savior:
# apt-get install grub #### suggested
# grub-install /dev/XXX #### suggested
The most important is the third line, as the update-grub command creates
a working, sane content of /boot/grub/menu.ls file:
# update-grub #### suggested
D.3.7. Create a User #### suggested new section
Even though d-i in expert mode asks whether system should use shadow
passwords, the guide doesn't mention it. This step is optional:
# shadowconfig on #### optional
Debian installer in expert mode asks whether a user wants to set the
root's password or use the sudo package. Ubuntu's guide [3] has a very
nice section here (D.4.7. Create a User), concerning the usage of normal
root account vs. sudo package. Maybe a similar section can be considered
for inclusion here?
Alternatively, one can easily go with a regular root account. In that
case, without setting a root's password one cannot do much after reboot:
# passwd root #### suggested
It's worth to add that all mounted filesystems can be unmounted at this
point and the system should be rebooted in order to login into newly
installed environment.
D.3.8. Installing Tasks #### suggested new section
While not very necessary, it would also be beneficial (and complementary
to the normal system installation procedure) to introduce a tasksel
program here. A list of available tasks can be obtained via:
# tasksel --list-tasks #### suggested
And default desktop installation can be performed by:
# tasksel install standard
# tasksel install desktop
I hope this documentation effort will be useful and I wholeheartedly
welcome all constructive criticism upon it.
With best regards,
Wiktor Wandachowicz
[1] https://launchpad.net/bugs/64765
[2] http://lists.debian.org/debian-boot/2006/10/msg00697.html
[3] http://archive.ubuntu.com/ubuntu/pool/main/i/installation-guide/installation-guide-i386_20060726ubuntu5_all.deb
--
Registered Linux user #390131 (http://counter.li.org)
Reply to: