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

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

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

<para>

This section explains how to install &debian-gnu; 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-gnu; from
Red Hat, Mandriva, 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-gnu;
install. It's also a clever way for dealing with hardware that
otherwise doesn't play friendly with various boot or installation
media.

</para>

<note><para>

As this is a mostly manual procedure, you should bear in mind that you
will need to do a lot of basic configuration of the system yourself,
which will also require more knowledge of &debian; and of &arch-kernel; in general
than performing a regular installation. You cannot expect this procedure
to result in a system that is identical to a system from a regular
installation. You should also keep in mind that this procedure only
gives the basic steps to set up a system. Additional installation and/or
configuration steps may be needed.

</para></note>

  <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 &base-system-size;MB of space available for a console only install,
or about &task-desktop-lxde-inst;MB if you plan to install X (more if you intend to
install desktop environments like GNOME or KDE Plasma).

</para><para>

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

<informalexample><screen>
# mke2fs -j /dev/<replaceable>sda6</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>sda5</replaceable>
# sync
# swapon /dev/<replaceable>sda5</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>sda6</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>&archive-mirror;/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/mirror/list"></ulink>.

</para><para>

If you have a &releasename; &debian-gnu; 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>amd64</userinput>,
<userinput>arm64</userinput>,
<userinput>armel</userinput>,
<userinput>armhf</userinput>,
<userinput>i386</userinput>,
<userinput>mips</userinput>,
<userinput>mips64el</userinput>,
<userinput>mipsel</userinput>,
<userinput>powerpc</userinput>,
<userinput>ppc64el</userinput>, or
<userinput>s390x</userinput>.

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

If the target architecture is different than the host, you should add the
<userinput>--foreign</userinput> option.

</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.UTF-8 chroot /mnt/debinst /bin/bash
</screen></informalexample>

If the target architecture is different from the host,
you will need to first copy qemu-user-static to the new host:

<informalexample><screen>
# cp /usr/bin/qemu-ARCH-static /mnt/debinst/usr/bin
# LANG=C.UTF-8 chroot /mnt/debinst qemu-ARCH-static /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>

Depending on the value of TERM, you may have to install the
<classname>ncurses-term</classname> package to get support for it.
</para>
<para>
If the target architecture is different from the host,
you need to finish the multi-stage boot strap:

<informalexample><screen>
/debootstrap/debootstrap --second-stage
</screen></informalexample>

</para>

   <sect3>
   <title>Create device files</title>
<para>

At this point <filename>/dev/</filename> only contains very basic device
files. For the next steps of the installation additional device files may
be needed. There are different ways to go about this and which method you
should use depends on the host system you are using for the installation,
on whether you intend to use a modular kernel or not, and on whether you
intend to use dynamic (e.g. using <classname>udev</classname>) or static
device files for the new system.

</para><para>

A few of the available options are:

<itemizedlist>
<listitem><para>

install the makedev package, and create a default set of static device files
using (after chrooting)
<informalexample><screen>
# apt install makedev
# mount none /proc -t proc
# cd /dev
# MAKEDEV generic
</screen></informalexample>

</para></listitem>
<listitem><para>

manually create only specific device files using <command>MAKEDEV</command>

</para></listitem>
<listitem><para>

bind mount /dev from your host system on top of /dev in the target system;
note that the postinst scripts of some packages may try to create device
files, so this option should only be used with care

</para></listitem>
</itemizedlist>

</para>
   </sect3>

   <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>

Setting the third line of the file <filename>/etc/adjtime</filename> to 
<quote>UTC</quote> or <quote>LOCAL</quote> determines
whether the system will interpret the hardware clock as being set to UTC
respective local time.  The following command allows you to set that.

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

Here is a sample:
<informalexample><screen>
0.0 0 0.0
0
UTC
</screen></informalexample>

The following command allows you to choose your timezone.

<informalexample><screen>
# dpkg-reconfigure tzdata
</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.
######################################################################

# The loopback interface isn't really required any longer, but can be used
# if needed.
#
# auto lo
# iface lo inet loopback

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

# An example static IP setup: (network, 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 example <filename>/etc/resolv.conf</filename>:

<informalexample><screen>
search example.com
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
127.0.1.1 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 &releasename; main

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

Make sure to run <userinput>apt 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>
# apt install locales
# dpkg-reconfigure locales
</screen></informalexample>

To configure your keyboard (if needed):

<informalexample><screen>
# apt install console-setup
# dpkg-reconfigure keyboard-configuration 
</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 &arch-kernel; kernel
and a boot loader. Identify available pre-packaged kernels with:

<informalexample><screen>
# apt search &kernelpackage;
</screen></informalexample>

</para><para>

Then install the kernel package of your choice using its package name.

<informalexample><screen>
# apt install &kernelpackage;-<replaceable>arch-etc</replaceable>
</screen></informalexample>

</para>
  </sect2>

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

To make your &debian-gnu; 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, but you
can use <command>apt</command> inside your &debian; chroot to do so.

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

Check <userinput>info grub</userinput> <phrase arch="x86">or <userinput>man
lilo.conf</userinput></phrase> 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 grub2
<filename>grub.cfg</filename><phrase arch="x86"> 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)</phrase>.

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

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

<informalexample><screen>
# apt install grub-pc
# grub-install /dev/<replaceable>sda</replaceable>
# update-grub
</screen></informalexample>

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

</para><para>

Note that this assumes that a <filename>/dev/sda</filename> device file has
been created. There are alternative methods to install <command>grub2</command>,
but those are outside the scope of this appendix.

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

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

<informalexample><screen>
boot=/dev/<replaceable>sda6</replaceable>
root=/dev/<replaceable>sda6</replaceable>
install=menu
delay=20
lba32
image=/vmlinuz
initrd=/initrd.img
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/sda2
device=hd:
partition=6
root=/dev/sda6
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>Remote access: Installing SSH and setting up access</title>
<para>

In case you can login to the system via console, you can skip this section. If
the system should be accessible via the network later on, you need to install
SSH and set up access.

<informalexample><screen>
# apt install ssh
</screen></informalexample>


Root login with password is disabled by default, so setting up access can be
done by setting a password and re-enable root login with password:

<informalexample><screen>
# passwd
# editor /etc/ssh/sshd_config
</screen></informalexample>

This is the option to be enabled:

<informalexample><screen>
PermitRootLogin yes
</screen></informalexample>

Access can also be set up by adding an ssh key to the root account:

<informalexample><screen>
# mkdir /root/.ssh
# cat &lt;&lt; EOF &gt; /root/.ssh/authorized_keys
ssh-rsa ....
EOF
</screen></informalexample>

Lastly, access can be set up by adding a non-root user and setting a password:

<informalexample><screen>
# adduser joe
# passwd joe
</screen></informalexample>
</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 install all packages with <quote>standard</quote> priority:

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

Of course, you can also just use <command>apt</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>
# apt clean
</screen></informalexample>

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