path: root/en/appendix/chroot-install.xml

<!-- retain these comments for translator revision tracking -->
<!-- $Id$ -->

 <sect1 id="linux-upgrade">
 <title>Installing &debian; from a Unix/Linux System</title>

<para>

This section explains how to install &debian; from an existing
Unix or Linux system, without using the menu-driven installer as
explained in the rest of the manual. This <quote>cross-install</quote>
HOWTO has been requested by users switching to &debian; from
Red Hat, Mandrake, and SUSE. In this section some familiarity with
entering *nix commands and navigating the file system is assumed. In
this section, <prompt>$</prompt> symbolizes a command to be entered in
the user's current system, while <prompt>#</prompt> refers to a
command entered in the Debian chroot.

</para><para>

Once you've got the new Debian system configured to your preference,
you can migrate your existing user data (if any) to it, and keep on
rolling. This is therefore a <quote>zero downtime</quote> &debian;
install. It's also a clever way for dealing with hardware that
otherwise doesn't play friendly with various boot or installation
media.

</para>

  <sect2>
  <title>Getting Started</title>
<para>

With your current *nix partitioning tools, repartition the hard
drive as needed, creating at least one filesystem plus swap. You
need around 350MB of space available for a console only install,
or about 1GB if you plan to install X (more if you intend to
install destop environments like GNOME or KDE).

</para><para>

Create file systems on your partitions. For example, to create an
ext3 file system on partition <filename>/dev/hda6</filename> (that's
our example root partition):

<informalexample><screen>
# mke2fs -j /dev/<replaceable>hda6</replaceable>
</screen></informalexample>

To create an ext2 file system instead, omit <userinput>-j</userinput>.

</para><para>

Initialize and activate swap (substitute the partition number for
your intended Debian swap partition):

<informalexample><screen>
# mkswap /dev/<replaceable>hda5</replaceable>
# sync; sync; sync
# swapon /dev/<replaceable>hda5</replaceable>
</screen></informalexample>

Mount one partition as <filename>/mnt/debinst</filename> (the
installation point, to be the root (<filename>/</filename>) filesystem
on your new system). The mount point name is strictly arbitrary, it is
referenced later below.

<informalexample><screen>
# mkdir /mnt/debinst
# mount /dev/<replaceable>hda6</replaceable> /mnt/debinst
</screen></informalexample>

</para>
<note><para>

If you want to have parts of the filesystem (e.g. /usr) mounted on
separate partitions, you will need to create and mount these directories
manually before proceding with the next stage.

</para></note>
  </sect2>

  <sect2>
  <title>Install <command>debootstrap</command></title>
<para>

The utility used by the Debian installer, and recognized as the
official way to install a Debian base system, is
<command>debootstrap</command>. It uses <command>wget</command> and
<command>ar</command>, but otherwise depends only on
<classname>/bin/sh</classname> and basic Unix/Linux tools<footnote>

<para>

These include the GNU core utilities and commands like <command>sed</command>, <command>grep</command>, <command>tar</command> and <command>gzip</command>.

</para>

</footnote>. Install <command>wget</command> and
<command>ar</command> if they aren't already on your current system,
then download and install <command>debootstrap</command>.

</para>

<!-- The files linked to here are from 2004 and thus currently not usable
<para>

If you have an rpm-based system, you can use alien to convert the
.deb into .rpm, or download an rpm-ized version at
<ulink url="http://people.debian.org/~blade/install/debootstrap"></ulink>

</para>
-->

<para>

Or, you can use the following procedure to install it
manually. Make a work folder for extracting the .deb into:

<informalexample><screen>
# mkdir work
# cd work
</screen></informalexample>

The <command>debootstrap</command> binary is located in the Debian
archive (be sure to select the proper file for your
architecture). Download the <command>debootstrap</command> .deb from
the <ulink url="http://ftp.debian.org/debian/pool/main/d/debootstrap/">
pool</ulink>, copy the package to the work folder, and extract the
files from it. You will need to have root privileges to install
the files.

<informalexample><screen>
# ar -x debootstrap_0.X.X_all.deb
# cd /
# zcat /full-path-to-work/work/data.tar.gz | tar xv
</screen></informalexample>

</para>
  </sect2>

  <sect2>
  <title>Run <command>debootstrap</command></title>
<para>

<command>debootstrap</command> can download the needed files directly
from the archive when you run it. You can substitute any Debian
archive mirror for <userinput>http.us.debian.org/debian</userinput> in
the command example below, preferably a mirror close to you
network-wise. Mirrors are listed at
<ulink url="http://www.debian.org/misc/README.mirrors"></ulink>.

</para><para>

If you have a &releasename; &debian; CD mounted at
<filename>/cdrom</filename>, you could substitute a file URL instead
of the http URL: <userinput>file:/cdrom/debian/</userinput>

</para><para>

Substitute one of the following for <replaceable>ARCH</replaceable>
in the <command>debootstrap</command> command:

<userinput>alpha</userinput>,
<userinput>amd64</userinput>,
<userinput>arm</userinput>,
<userinput>hppa</userinput>,
<userinput>i386</userinput>,
<userinput>ia64</userinput>,
<userinput>m68k</userinput>,
<userinput>mips</userinput>,
<userinput>mipsel</userinput>,
<userinput>powerpc</userinput>,
<userinput>s390</userinput>, or
<userinput>sparc</userinput>.

<informalexample><screen>
# /usr/sbin/debootstrap --arch ARCH &releasename; \
     /mnt/debinst http://ftp.us.debian.org/debian
</screen></informalexample>

</para>
  </sect2>

  <sect2>
  <title>Configure The Base System</title>
<para>

Now you've got a real Debian system, though rather lean, on disk.
<command>chroot</command> into it:

<informalexample><screen>
# LANG=C chroot /mnt/debinst /bin/bash
</screen></informalexample>

After chrooting you may need to set the terminal definition to be
compatible with the Debian base system, for example:

<informalexample><screen>
# export TERM=<replaceable>xterm-color</replaceable>
</screen></informalexample>

</para>

   <sect3>
   <title>Mount Partitions</title>
<para>

You need to create <filename>/etc/fstab</filename>.

<informalexample><screen>
# editor /etc/fstab
</screen></informalexample>

Here is a sample you can modify to suit:

<informalexample><screen>
# /etc/fstab: static file system information.
#
# file system    mount point   type    options                  dump pass
/dev/XXX         /             ext3    defaults                 0    1
/dev/XXX         /boot         ext3    ro,nosuid,nodev          0    2

/dev/XXX         none          swap    sw                       0    0
proc             /proc         proc    defaults                 0    0

/dev/fd0         /media/floppy auto    noauto,rw,sync,user,exec 0    0
/dev/cdrom       /media/cdrom  iso9660 noauto,ro,user,exec      0    0

/dev/XXX         /tmp          ext3    rw,nosuid,nodev          0    2
/dev/XXX         /var          ext3    rw,nosuid,nodev          0    2
/dev/XXX         /usr          ext3    rw,nodev                 0    2
/dev/XXX         /home         ext3    rw,nosuid,nodev          0    2
</screen></informalexample>

Use <userinput>mount -a</userinput> to mount all the file systems you
have specified in your <filename>/etc/fstab</filename>, or to mount
file systems individually use:

<informalexample><screen>
# mount /path   # e.g.: mount /usr
</screen></informalexample>

Current Debian systems have mountpoints for removable media under
<filename>/media</filename>, but keep compatibility symlinks in
<filename>/</filename>. Create these as as needed, for example:

<informalexample><screen>
# cd /media
# mkdir cdrom0
# ln -s cdrom0 cdrom
# cd /
# ln -s media/cdrom
</screen></informalexample>

You can mount the proc file system multiple times and to arbitrary
locations, though <filename>/proc</filename> is customary. If you didn't use
<userinput>mount -a</userinput>, be sure to mount proc before continuing:

<informalexample><screen>
# mount -t proc proc /proc
</screen></informalexample>

</para><para>

The command <userinput>ls /proc</userinput> should now show a non-empty
directory. Should this fail, you may be able to mount proc from outside
the chroot:

<informalexample><screen>
# mount -t proc proc /mnt/debinst/proc
</screen></informalexample>

</para>
   </sect3>

   <sect3>
   <title>Setting Timezone</title>
<para>

An option in the file <filename>/etc/default/rcS</filename> determines
whether the system will interpret the hardware clock as being set to UTC
or local time. The following command allow you to set that and choose
your timezone.

<informalexample><screen>
# editor /etc/default/rcS
# tzconfig
</screen></informalexample>

</para>
   </sect3>

   <sect3>
   <title>Configure Networking</title>
<para>

To configure networking, edit
<filename>/etc/network/interfaces</filename>,
<filename>/etc/resolv.conf</filename>,
<filename>/etc/hostname</filename> and
<filename>/etc/hosts</filename>.

<informalexample><screen>
# editor /etc/network/interfaces
</screen></informalexample>

Here are some simple examples from
<filename>/usr/share/doc/ifupdown/examples</filename>:

<informalexample><screen>
######################################################################
# /etc/network/interfaces -- configuration file for ifup(8), ifdown(8)
# See the interfaces(5) manpage for information on what options are
# available.
######################################################################

# We always want the loopback interface.
#
auto lo
iface lo inet loopback

# To use dhcp:
#
# auto eth0
# iface eth0 inet dhcp

# An example static IP setup: (broadcast and gateway are optional)
#
# auto eth0
# iface eth0 inet static
#     address 192.168.0.42
#     network 192.168.0.0
#     netmask 255.255.255.0
#     broadcast 192.168.0.255
#     gateway 192.168.0.1
</screen></informalexample>

Enter your nameserver(s) and search directives in
<filename>/etc/resolv.conf</filename>:

<informalexample><screen>
# editor /etc/resolv.conf
</screen></informalexample>

A simple <filename>/etc/resolv.conf</filename>:

<informalexample><screen>
search hqdom.local\000
nameserver 10.1.1.36
nameserver 192.168.9.100
</screen></informalexample>

Enter your system's host name (2 to 63 characters):

<informalexample><screen>
# echo DebianHostName &gt; /etc/hostname
</screen></informalexample>

And a basic <filename>/etc/hosts</filename> with IPv6 support:

<informalexample><screen>
127.0.0.1 localhost DebianHostName

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
ff02::3 ip6-allhosts
</screen></informalexample>

If you have multiple network cards, you should arrange the names of
driver modules in the <filename>/etc/modules</filename> file into the
desired order. Then during boot, each card will be associated with the
interface name (eth0, eth1, etc.) that you expect.

</para>
   </sect3>

   <sect3>
   <title>Configure Apt</title>
<para>

Debootstrap will have created a very basic
<filename>/etc/apt/sources.list</filename> that will allow installing
additional packages. However, you may want to add some additional sources,
for example for source packages and security updates:

<informalexample><screen>
deb-src http://ftp.us.debian.org/debian etch main

deb http://security.debian.org/ etch/updates main
deb-src http://security.debian.org/ etch/updates main
</screen></informalexample>

Make sure to run <userinput>aptitude update</userinput> after you have
made changes to the sources list.

</para>
   </sect3>

   <sect3>
   <title>Configure Locales and Keyboard</title>
<para>

To configure your locale settings to use a language other than
English, install the <classname>locales</classname> support package
and configure it. Currently the use of UTF-8 locales is recommended.

<informalexample><screen>
# aptitude install locales
# dpkg-reconfigure locales
</screen></informalexample>

To configure your keyboard (if needed):

<informalexample><screen>
# aptitude install console-data
# dpkg-reconfigure console-data
</screen></informalexample>

</para><para>

Note that the keyboard cannot be set while in the chroot, but will be
configured for the next reboot.

</para>
   </sect3>
  </sect2>

  <sect2>
  <title>Install a Kernel</title>
<para>

If you intend to boot this system, you probably want a Linux kernel
and a boot loader. Identify available pre-packaged kernels with:

<informalexample><screen>
# apt-cache search linux-image
</screen></informalexample>

Then install your choice using its package name.

<informalexample><screen>
# aptitude install linux-image-<replaceable>&kernelversion;-arch-etc</replaceable>
</screen></informalexample>

</para>
<note><para>

The configuration file <filename>/etc/kernel-img.conf</filename> influences
the installation and upgrade of pre-packaged Debian kernels. A default file
will be created when you first install a Debian kernel image. For additional
information about this file, consult its man page which will be available
after installing the <classname>kernel-package</classname> package.

</para></note>
  </sect2>

  <sect2>
<title>Set up the Boot Loader</title>
<para>

To make your &debian; system bootable, set up your boot loader to load
the installed kernel with your new root partition. Note that
<command>debootstrap</command> does not install a boot loader, though you
can use <command>aptitude</command> inside your Debian chroot to do so.

</para><para arch="x86">

Check <userinput>info grub</userinput> or <userinput>man
lilo.conf</userinput> for instructions on setting up the
bootloader.  If you are keeping the system you used to install Debian, just
add an entry for the Debian install to your existing grub
<filename>menu.lst</filename> or <filename>lilo.conf</filename>.  For
<filename>lilo.conf</filename>, you could also copy it to the new system and
edit it there. After you are done editing, call <command>lilo</command>
(remember it will use
<filename>lilo.conf</filename> relative to the system you call it from).

</para><para arch="x86">

Installing and setting up <classname>grub</classname> is as easy as:

<informalexample><screen>
# aptitude install grub
# grub-install /dev/<replaceable>hda</replaceable>
# update-grub
</screen></informalexample>

The second command will install <command>grub</command> (in this case in
the MBR of <literal>hda</literal>). The last command will create a sane
and working <filename>/boot/grub/menu.lst</filename>.

</para><para arch="x86">

Here is a basic <filename>/etc/lilo.conf</filename> as an example:

<informalexample><screen>
boot=/dev/<replaceable>hda6</replaceable>
root=/dev/<replaceable>hda6</replaceable>
install=menu
delay=20
lba32
image=/vmlinuz
label=Debian
</screen></informalexample>

</para><para arch="powerpc">

Check <userinput>man yaboot.conf</userinput> for instructions on
setting up the bootloader.  If you are keeping the system you used to
install Debian, just add an entry for the Debian install to your
existing <filename>yaboot.conf</filename>.  You could also copy it to
the new system and
edit it there. After you are done editing, call ybin (remember it will
use <filename>yaboot.conf</filename> relative to the system you call it from).

</para><para arch="powerpc">

Here is a basic <filename>/etc/yaboot.conf</filename> as an example:

<informalexample><screen>
boot=/dev/hda2
device=hd:
partition=6
root=/dev/hda6
magicboot=/usr/lib/yaboot/ofboot
timeout=50
image=/vmlinux
label=Debian
</screen></informalexample>

On some machines, you may need to use <userinput>ide0:</userinput>
instead of <userinput>hd:</userinput>.

</para>
  </sect2>

  <sect2>
<title>Finishing touches</title>
<para>

As mentioned earlier, the installed system will be very basic. If you would
like to make the system a bit more mature, there is an easy method to
packages of <quote>standard</quote> priority:

<informalexample><screen>
# tasksel install standard
</screen></informalexample>

Of course, you can also just use <command>aptitude</command> to install
packages individually.

</para><para>

After the installation there will be a lot of downloaded packages in
<filename>/var/cache/apt/archives/</filename>. You can free up some
diskspace by running:

<informalexample><screen>
# aptitude clean
</screen></informalexample>

</para>
  </sect2>
 </sect1>