<chapter id="running">
<title>Running Debian Installer</title>
<para>

The examples in this chapter are based on the CD-ROM and netboot installation
methods for x86 (the amd64 and i386 architectures). The choice for x86 was
made as this is most familiar to most users, but installations for other
architectures are not structurally different<footnote>

<para>
Some architectures may use specific additional components as part of their
default installation. However, this does not make them structurally different.
</para>

</footnote>.

</para><para>

The <quote>CD-ROM</quote> installation method also covers DVD, BD and the
popular netinst images. Please note, that images for amd64 and i386 are
built using isohybrid, so they can be used on optical media as well as on
USB sticks.

</para><para>

So what are the basic steps when the installer is run? In any installation
five stages can be distinguished:

<orderedlist>
  <listitem>
boot and initialization &mdash; setting up the installer so that it can load
any additional components;
  </listitem><listitem>
loading additional components &mdash; expanding the installer to its full
functionality;
  </listitem><listitem>
network configuration (unless already done in stage 1);
  </listitem><listitem>
partitioning;
  </listitem><listitem>
installing the target system.
  </listitem>
</orderedlist>

</para><para>

The first three stages are where the fundamental difference between
installation methods can be seen. All components (udebs) used there need
to be included in the initrd with which the installer is booted.

</para><para>

The table below shows what components are involved in the first and second
stage for the CD-ROM and netboot installation methods and also shows where
these differ.

</para>

<informaltable>
<tgroup cols='4' colsep='1' rowsep='1'>
  <colspec colname='c1' align='center'/>
  <colspec colname='c2' align='center'/>
  <colspec colname='c3' align='center'/>
  <colspec colname='c4' align='left'/>
  <thead>
    <row>
      <entry>Stage</entry>
      <entry>CD-ROM</entry>
      <entry>NETBOOT</entry>
      <entry>Comments</entry>
    </row>
  </thead><tbody>
    <row>
      <entry>-</entry>
      <entry namest="c2" nameend="c3">initrd-preseed</entry>
      <entry>Only if <filename>/preseed.cfg</filename> is present</entry>
    </row><row>
      <entry>1</entry>
      <entry namest="c2" nameend="c3">localechooser</entry>
      <entry>Language/location/locale selection</entry>
    </row><row>
      <entry>1</entry>
      <entry namest="c2" nameend="c3">console-setup</entry>
      <entry>Keyboard/keymap selection</entry>
    </row><row>
      <entry>1</entry>
      <entry>cdrom-detect</entry>
      <entry>ethdetect</entry>
      <entry>Hardware detection and setup</entry>
    </row><row>
      <entry>1</entry>
      <entry></entry>
      <entry>netcfg</entry>
      <entry>Network configuration</entry>
    </row><row>
      <entry>-</entry>
      <entry>file-preseed</entry>
      <entry>network-preseed</entry>
      <entry>If selected at boot prompt</entry>
    </row><row>
      <entry>2</entry>
      <entry></entry>
      <entry>choose-mirror</entry>
      <entry>Mirror selection</entry>
    </row><row>
      <entry>2</entry>
      <entry>load-cdrom (anna)</entry>
      <entry>download-installer (anna)</entry>
      <entry>Retrieve and unpack additional components</entry>
    </row><row>
      <entry>3</entry>
      <entry>ethdetect</entry>
      <entry></entry>
      <entry>Hardware detection and setup</entry>
    </row><row>
      <entry>3</entry>
      <entry>netcfg</entry>
      <entry></entry>
      <entry>Network configuration</entry>
    </row><row>
      <entry>3</entry>
      <entry>choose-mirror</entry>
      <entry></entry>
      <entry>Mirror selection (only if the base system is not installable from CD)</entry>
    </row><row>
      <entry>3</entry>
      <entry namest="c2" nameend="c3">clock-setup</entry>
      <entry>Set up clock and time zone</entry>
    </row>
  </tbody>
</tgroup>
</informaltable>

<para>

The remainder of the installation is basically the same for all installation
methods.

</para>

<informaltable>
<tgroup cols='3' colsep='1' rowsep='1'>
  <colspec colname='c1' align='center'/>
  <colspec colname='c2' align='center'/>
  <colspec colname='c3' align='left'/>
  <thead>
    <row>
      <entry>Stage</entry>
      <entry></entry>
      <entry>Comments</entry>
    </row>
  </thead><tbody>
    <row>
      <entry>4</entry>
      <entry>hw-detect</entry>
      <entry>Additional hardware detection</entry>
    </row><row>
      <entry>4</entry>
      <entry>partman</entry>
      <entry>Partitioning, file system creation and mount point selection</entry>
    </row><row>
      <entry>5</entry>
      <entry>base-installer</entry>
      <entry>Base system (debootstrap) &amp; kernel installation</entry>
    </row><row>
      <entry>5</entry>
      <entry>user-setup</entry>
      <entry>Set up root and normal user accounts</entry>
    </row><row>
      <entry>5</entry>
      <entry>apt-setup</entry>
      <entry>APT configuration in the target system (sources.list)</entry>
    </row><row>
      <entry>5</entry>
      <entry>pkgsel</entry>
      <entry>Select and install additional packages (tasksel)</entry>
    </row><row>
      <entry>5</entry>
      <entry>grub-installer; nobootloader</entry>
      <entry>Boot loader installation</entry>
    </row><row>
      <entry>5</entry>
      <entry>finish-install</entry>
      <entry>Finish up the installation and reboot</entry>
    </row>
  </tbody>
</tgroup>
</informaltable>

   <sect1><title>Installation methods</title>
<para>

The installer supports a lot of different installation methods and in some
cases installation methods can be creatively combined. The definition of an
installation method is based on the following questions.

<itemizedlist>
 <listitem>
How is the installer booted?
 </listitem><listitem>
From where are additional udebs retrieved?
 </listitem><listitem>
From where are packages needed to install the base system retrieved?
 </listitem><listitem>
From where are packages needed to install tasks retrieved<footnote>

<para>

The last question can also be rephrased as <quote>what source lines are set
up in the <filename>/etc/apt/sources.list</filename> file for the target
system</quote>.

</para>

</footnote>?
 </listitem>
</itemizedlist>

</para><para>

The table below shows the answers to these questions for the most common
installation methods.

</para>

<informaltable>
<tgroup cols='5' align='left' colsep='1' rowsep='1'>
  <thead>
    <row>
      <entry>Method</entry>
      <entry>Boot</entry>
      <entry>Udebs</entry>
      <entry>Base system</entry>
      <entry>Tasks</entry>
    </row>
  </thead><tbody>
    <row>
      <entry>netboot</entry>
      <entry>network (TFTP server)</entry>
      <entry>network</entry>
      <entry>network</entry>
      <entry>network</entry>
    </row><row>
      <entry>mini.iso</entry>
      <entry>CD</entry>
      <entry>network</entry>
      <entry>network</entry>
      <entry>network</entry>
    </row><row>
      <entry>netinst CD</entry>
      <entry>CD</entry>
      <entry>CD</entry>
      <entry>CD</entry>
      <entry>network</entry>
    </row><row>
      <entry>full CD/DVD/BD</entry>
      <entry>CD</entry>
      <entry>CD</entry>
      <entry>CD</entry>
      <entry>CD (+ network)</entry>
    </row><row>
      <entry>hd-media<superscript>a)</superscript></entry>
      <entry>harddisk/USB stick</entry>
      <entry>CD image</entry>
      <entry>CD image/network</entry>
      <entry>CD image/network</entry>
    </row>
  </tbody>
</tgroup>
</informaltable>

<para>

<superscript>a)</superscript> Whether packages for the base system and
tasks are retrieved from CD (image) or the network depends on the type of
CD used in combination with these boot methods.

</para>
   </sect1>

   <sect1 id="di-boot">
   <title>The boot process</title>
<para>

The boot process for the installer is similar to the boot of a regular
system. A bootloader (in some cases the system's firmware) is responsible
for loading the kernel and loading the initrd after which init is started.
The boot process can be debugged by adding the
<userinput>BOOT_DEBUG</userinput> parameter.

</para><para>

It is possible to pass additional kernel and boot parameters.
Kernel parameters are sometimes needed to get non-conformant hardware
supported, or to install from serial console instead of an attached
keyboard/display.

</para><para>

Boot parameters can also be used to influence the installer itself. More
about this in the section on preseeding.

</para><para>

The boot process is quite complex as it has evolved needing to support
several generations of linux, with changes in e.g. the kernel and udev.

</para><para>

The following enumeration gives an overview of the main steps in the boot
process.

</para>

<variablelist>
  <varlistentry>
    <term>1) <command>/init</command> (initramfs) or <command>/sbin/init</command> (initrd)</term>
    <listitem><para>
Sets up initial environment (<filename>/proc</filename>, <filename>/dev</filename>; run <command>udev</command>)
    </para></listitem>
  </varlistentry>

  <varlistentry>
    <term>2) <command>busybox init</command></term>
    <listitem><para>
<filename>/etc/inittab</filename> is parsed; this contains:

<itemizedlist>
 <listitem>
<literal>::sysinit:/sbin/debian-installer-startup</literal>
 </listitem><listitem>
<literal>::respawn:/sbin/debian-installer</literal>
 </listitem><listitem>
init for VT2 and VT3 (busybox shell), and for
VT4 (<filename>/var/log/syslog</filename>)
 </listitem>
</itemizedlist>

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

  <varlistentry>
    <term>3) <command>/sbin/debian-installer-startup</command></term>
    <listitem><para>
This is a run-parts like script that executes or sources scripts in
<filename>/lib/debian-installer-startup.d</filename>. The main functions
that are performed are:

<itemizedlist>
 <listitem>
mount <filename>devfs</filename> and <filename>sysfs</filename>
 </listitem><listitem>
load acpi modules
 </listitem><listitem>
start syslog
 </listitem><listitem>
check available memory and, depending on preset limits, enable a lowmem
mode if needed
 </listitem><listitem>
load any debconf templates present in the initrd
 </listitem><listitem>
parse boot parameters to look for debconf patterns
(<userinput>&lt;<replaceable>component</replaceable>&gt;/&lt;<replaceable>template</replaceable>&gt;=&lt;<replaceable>value</replaceable>&gt;</userinput>)
and set these in the debconf database
 </listitem><listitem>
detect the type of console that is used
 </listitem><listitem>
load framebuffer modules
 </listitem><listitem>
detect if the installer should run in rescue mode
 </listitem>
</itemizedlist>

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

  <varlistentry>
    <term>4) <command>/sbin/debian-installer</command></term>
    <listitem><para>
This is a run-parts like script that sources scripts in
<filename>/lib/debian-installer.d</filename>.
These scripts will be run again if the main installer process dies for some
reason. The main functions that are performed are:

<itemizedlist>
 <listitem>
detect if a framebuffer device is available
 </listitem><listitem>
initialize the console (blanking, UTF-8)
 </listitem><listitem>
select which debconf frontend is to be used (text, newt, gtk)
 </listitem><listitem>
start <classname>main-menu</classname> (see next section)
 </listitem><listitem>
halt or reboot the system (after <classname>main-menu</classname> exits)
 </listitem>
</itemizedlist>

    </para></listitem>
  </varlistentry>
</variablelist>

<para>

See also <xref linkend="ap-hooks-boot">the overview of available hooks</xref>.

</para>
   </sect1>

   <sect1><title>The Debian Installer Menu</title>
<para>

The component <classname>main-menu</classname> drives the rest of the
installation. It is responsible both for dynamically assembling the menu
and for executing components when they are selected. Note that the menu
is only actually visible when installing at low or medium debconf priority.
At higher priorities it is still there, but it will automatically execute
the next component without showing the menu to the user.

</para><para>

In some situations the debconf priority is automatically changed. It is
reduced when the execution of a component fails, or when the user uses the
<userinput>&lt;Go Back&gt;</userinput> button to back out all the way to
the menu. In these cases it will also be increased back to the original
level when the next component executed finishes successfully.

</para><para>

An important characteristic of udebs is that execution of their postinst
scripts is delayed. On installation udebs are only unpacked; the execution
of the postinst is done by main-menu and is actually what happens when a
component is selected in the menu. In other words, main-menu can be said
to be responsible for <quote>configuring</quote> the udeb.

</para><para>

For a component to be included in the menu, it needs to have an
<literal>Installer-Menu-Item</literal> line in the <classname>dpkg</classname>
status file (<filename>/var/lib/dpkg/status</filename>). The order of
components in the menu is determined primarily by its dependencies; the
menu item number is used only where the order for two or more components
cannot be resolved by dependencies alone.

</para><para>

Provides can be used to define virtual states which other components can
depend on, as shown in the next example.

<informalexample><screen>
Package: netcfg
Status: install ok installed
Version: 1.52
Provides: configured-network
Depends: libc6-udeb (&gt;= 2.10), libdebconfclient0-udeb,
         libdebian-installer4-udeb (&gt;= 0.69), libiw30-udeb (&gt;= 30~pre1),
         ethernet-card-detection
Description: Configure the network
Installer-Menu-Item: 1800

Package: choose-mirror
Status: install ok unpacked
Version: 2.32
Depends: configured-network, choose-mirror-bin
Description: Choose mirror to install from
Installer-Menu-Item: 2300
</screen></informalexample>

</para><para>

This example also shows that netcfg has been run successfully
(<quote>installed</quote>) while mirror selection has not yet taken place
(<quote>unpacked</quote>).

</para><para>

Some components are included in the menu but are not run by default. These
components have a menu number higher than 90000 and are listed after
<classname>finish-install</classname> in the menu. Examples are
components that allow to change the debconf priority, to save debug logs,
to check the integrity of a CD-ROM or to abort the installation.

</para>
   </sect1>

   <sect1 id="hooks">
   <title>Hooks provide additional flexibility</title>
<para>

At certain points in the installation, components provide run-parts like
execution of scripts. This allows other components to just drop scripts
there so that commands can be run at that point in the installation, even
though the postinst for the component itself is run earlier or later (if
the component even has a postinst).

</para><para>

An overview of available hooks can be found in <xref linkend="ap-hooks"/>.
The most relevant are the <xref linkend="ap-hooks-general">general purpose
hooks</xref>.

</para><para>

Besides these general hooks, partman is basically structured as one big
collection of hooks where partman components all drop their own scriptlets
to extend partman's functionality. The most noteworthy of these hooks is
<filename>/lib/partman/finish.d</filename> as some bootloaders drop scripts
there to add checks that ensure the selected partitioning scheme conforms to
their requirements.

</para>
   </sect1>

   <sect1><title>Some special tools</title>
<para>

The installer has some special commands which can be used in postinst or
preseeding scripts:

<variablelist>
  <varlistentry>
    <term><command>anna-install</command></term>
    <listitem><para>
Used to install additional, non-standard d-i components (udebs). It will
check if <classname>anna</classname> has already been run. If it has, the
component is unpacked immediately; if it has not, it will be scheduled for
installation when <classname>anna</classname> is run.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><command>apt-install</command></term>
    <listitem><para>
Performs the same function for normal packages and installs them in the
target system. Packages will either be installed immediately (if called
after base-installer) or scheduled for installation as one of the
<quote>extra</quote> packages installed near the end of base-installer's
postinst script.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><command>log-output</command></term>
    <listitem><para>
Allows to run a command and redirect its output (either
<filename>stdout</filename> or <filename>stderr</filename> or both) to
<filename>/var/log/syslog</filename>.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><command>in-target</command></term>
    <listitem><para>
Allows to run a command in a chroot on <filename>/target</filename> with
the chroot being set up for more demanding operations. For example,
<filename>proc</filename> and <filename>sysfs</filename> are mounted and
a <filename>policy-rc.d</filename> is created. Can obviously only be used
after the base system has been set up.
    </para></listitem>
  </varlistentry>
</variablelist>

</para><para>

See the <filename>README</filename> in the source for debian-installer-utils
for more detailed information.

</para>
   </sect1>

   <sect1><title>Automating the install using preseeding</title>
<para>

There are three preconfiguration methods that are currently supported:
<variablelist>
  <varlistentry>
    <term><emphasis>initrd preseeding</emphasis></term>
    <listitem><para>
The preconfiguration file <filename>/preseed.cfg</filename> needs to be
present in the initrd. It is read as part of the
<command>debian-installer-startup</command> processing.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>file preseeding</emphasis></term>
    <listitem><para>
Triggered by the presence of the <userinput>preseed/file</userinput>
boot parameter.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>network preseeding</emphasis></term>
    <listitem><para>
Triggered by the presence of the <userinput>preseed/url</userinput>
boot parameter. It is also possible to trigger this from the DHCP server.
    </para></listitem>
  </varlistentry>
</variablelist>

Which of these methods is available depends on the installation method.

</para><para>

The main purpose of preseeding is to set default values for debconf
questions. Note that it makes no sense when using file or network
preseeding to preseed values for questions that are asked
<emphasis>before</emphasis> the preconfiguration file is parsed.

</para><para>

Besides offering the option to set default values for debconf questions,
preseeding also makes it possible to run scripts at two distinct moments
using <userinput>preseed/early_command</userinput> and
<userinput>preseed/late_command</userinput>.
The <userinput>early_command</userinput> is executed immediately after the
preconfiguration file is parsed (only for file and network preseeding);
the <userinput>late_command</userinput> is executed as part of the
<command>finish-install</command> component.

</para><para>

These scripts can be made as complex as you like. One option is to use them
to install additional packages on the target system (using
<command>apt-install</command>). The <userinput>early_command</userinput>
could be used to install additional d-i components (using
<command>anna-install</command>) or to install scripts in the various hook
script directories (if commands need to be executed at a specific point in
the installation).

</para><para>

Additional information about preseeding is available in an appendix of the
Installation Guide.

</para>
   </sect1>

   <sect1><title>Debugging the installer</title>
<para>

Because most of the installer is scripted, it is fairly easy to debug most
problems by adding a <userinput>set -x</userinput> in the correct place.
The obvious place to start is the postinst of the component you want to
debug. The output will appear in <filename>/var/log/syslog</filename>,
which can most easily be viewed by starting the internal webserver from the
<quote>Save debug logs</quote> menu option (after the network has been
configured).

</para><para>

For components written in C debugging is a bit harder. Options are to use
the strace udeb (add it to a custom image if needed) or to create a custom
version of a component with added debug statements in the source and use that.

</para><para>

For debugging, you will probably want to control when components are started.
Booting the installer with <userinput>install debconf/priority=medium</userinput>
is a good way to achieve that. It will make sure the menu is displayed before
a new component is started.

</para><para>

If you boot the installer at medium priority, you will also be able to load
the optional component <classname>openssh-client-udeb</classname><footnote>

<para>
If you want to load optional components when installing at the default
priority, you need to back out to the menu, change the debconf priority to
medium or low, and then select the component that installs additional installer
components. After you've installed the desired components, the debconf priority
can then be changed back to its original value.
</para>

</footnote>. Loading this component will allow you to use <command>scp</command>
to copy files from the system being installed to another computer and vice
versa. Also useful for testing new versions of scripts or commands without
rebuilding the udeb and image. The command <command>nc</command> from the
<classname>netcat</classname> package is available by default in the installer.

</para>
   </sect1>
</chapter>
