How to install sarge with the new debian-installer
--------------------------------------------------

This documents describes how to perform an installation with the new
debian-installer, which will be released together with the upcoming
Debian release, codename: sarge.

For the most current version of this document or more information on
the debian-installer project: http://www.debian.org/devel/debian-installer

Last change to this document: February 7th, 2004


1. Preliminaries

Debian-installer images are currently only available for the i386, powerpc,
alpha, and ia64 architectures. Ports to other architectures are of
course welcome. Please see section 6 if you want to help developing.

The debian-installer is still in a beta state. If you encounter
bugs during your install, please refer to section 5 on how to report
them. If you have questions which cannot be answered by this document,
please direct them to the debian-boot mailing list
(debian-boot@lists.debian.org) or ask on irc (#debian-boot on the
freenode network).

Recently the debian-installer has switched to ask only the important
questions and configure the rest automatically. This also means that you
won't get to see the main menu anymore, except when something goes wrong.
If you want to restore the old configuration with more questions asked,
type "expert" at the boot prompt. If you do so, refer to section
3.1. for installing rather than section 3.


2. Getting images

The debian-cd team provides builds of CD images for debian-installer here:
http://people.debian.org/cdimage/testing/

The other kinds of images, including floppy images are in the Debian
archive, in the main/installer-<arch> directories. For example:
ftp://ftp.debian.org/debian/dists/unstable/main/installer-i386/current/images/

Daily builds of all non-ISO debian-installer images, including floppy images 
and initrd's are available --
for i386:      http://people.debian.org/~joeyh/d-i/images/daily/
for powerpc:   http://people.debian.org/~tsauter/d-i/images-powerpc/daily/
               (cdrom and netboot only)
complete list: http://www.debian.org/devel/debian-installer/ports-status

The subsections below will give the details about which images you should
get for each possible means of installation.


2.1 CDROM

There are two different netinst images at the location above which can be
used to install sarge with the debian-installer. These images are intended
to boot from CD and install additional packages over a network, hence the
name 'netinst'. The difference between the two images is, that on the full
netinst image the base packages are included, whereas you have to download
these from the web if you are using the business card image.

Download whichever type you prefer and burn it to a CD.

2.1.1 SCSI CD drives

If you have a SCSI CD drive and a relatively uncommon SCSI controller (not
an aic7xxx, BusLogic, or sym53c8xx), then you may also need one driver
floppy to let the installer see your CD drive. See section 2.2 for
information about floppys, and download the cd-drivers floppy image and
write it to disk. You will be given an opportunity to load drivers from the
floppy if the installer fails to see your SCSI CD drive, and after
loading the floppy, the installer will see your CD ROM.

2.2 The dreaded floppies

If you can't boot from CD, you can download floppy images to install
Debian. You need the floppy/boot.img, the floppy/root.img and possibly
one of the driver disks.

- floppy/net-drivers.img
  To do an install over the network with a few common ethernet cards,
  you do not need this driver floppy. If you have a less common ethernet
  card, or pcmcia, you will need it.
- floppy/cd-drivers.img
  If you have a cdrom, but cannot boot from it, you can boot from floppies,
  and use this driver disk to complete the install using the cdrom.

Floppy disks are one of the least reliable media around, so be prepared for
lots of bad disks. Each .img file you downloaded goes on a single floppy;
you can use the dd command to write it to /dev/fd0 or some other means.
It's a good idea to them use cmp to compare what ended up on the unreliable
floppy disk with the image. If it fails throw that floppy away and try
again. Since you'll have more than one floppy, it's a good idea to label
them.

The boot floppy is the one with boot.img on it. This floppy, when
booted, will prompt you to insert a second floppy -- use the one with
root.img on it. 

2.3 USB memory stick

It's also possible to install from removable USB storage devices. For
example a USB keychain can make a handy Debian install media the you
can take with you anywhere.

The easiest way to prepare your USB memory stick is to download
hd-media/boot.img.gz, and use gunzip to extract the 128 MB image from that
file. Write this image directly to your memory stick, which must be at
least 128 mb in size. Of course this will destroy anything already on the
memory stick. Then mount the memory stick, which will now have a FAT
filesystem on it. Next, download a Debian netinst CD image, and copy that
file to the memory stick; any filename is ok as long as it ends in ".iso".

Alternatively, if you're using linux and familiar with loopback mounting,
it can be quicker to loop mount the disk image, copy the iso into it, and
only then write the complete image to the memory stick.

There are other, more flexible ways to set up a memory stick to use the
debian-installer, and it's possible to get it to work with smaller memory
sticks. This web page has more complete directions for using
debian-installer and a bootable USB stick: http://d-i.pascal.at/

2.3.1 Booting directly from USB storage

Some BIOSes can boot USB storage directly, and some cannot. You may need to
configure your BIOS to boot from a "removable drive" or even a "USB-ZIP" to
get it to boot from the USB device. The web site above has more information
and some helpful hints about booting.

2.3.2 Using USB storage and a boot floppy

The debian-installer can be booted off a single floppy, which will be able
to access your USB memory stick. To boot the installer this way, you will
need to put the floppy/boot.img on a floppy (see section 2.2).

Now boot from the floppy. It should detect your USB device and proceed
with booting from it.

2.4 Booting from network

It's also possible to boot debian-installer completely from the net. The 
various methods to netboot depend on your architecture and netboot setup. 
They are not explaind here. For an explanation of how to do PXE netbooting
(on i386), see this web page:
http://wiki.debian.net/index.cgi?DebianInstallerNetbootPXE

The files in netboot/ can be used to netboot debian-installer.
If you don't have a netboot setup, you can write the netboot/mini.iso
to a CD to produce a minimal netinst CD.

2.5 Booting from hard disk

It's possible to boot the installer using no removable media, but just an
existing hard disk, which can have a different OS on it. These instructions
are for i386 systems, such as those running windows. Download 
hd-media/initrd.gz, hd-media/vmlinuz, and a Debian CD image to the top-level
directory of the hard disk. Make sure that the CD image has a filename
ending in ".iso". Now it's just a matter of booting linux with the initrd.

If you have grub installed, boot grub, and do the following:

grub>kernel (hd0,0)/vmlinuz root=/dev/ram ramdisk_size=8192 devfs=mount,dall
grub>initrd (hd0,0)/initrd.gz
grub>boot

Or you can use loadlin to boot linux from inside DOS (or early versions of
Windows) with the same parameters. Ater the installer boots , it should
find the ISO you placed on the hard disk, and continue with the install.
You will not be able to reformat the partition the installer was booted
from if you use this technique.


3. Installation

From here on, I assume you have downloaded and burnt the 'netinst'
CD. Put it into your CD-drive and make your system boot from CD.

You will be greeted by a welcome screen. Hit ENTER to boot. After a
while you will be asked to select your language. This will affect
translation of debian-installer (if already available for your
language) as well as the choice of country and keyboard layout. Select
your language and press ENTER to continue.

Sit back while debian-installer detects some of your hardware, and
loads additional installer modules from the cd.

Next the installer will try to detect your network hardware and set up
networking by DHCP. If you are not on a network or do not have DHCP, you
will see an error message. You do not need a network to continue the
install so this can be easily worked around. Select continue and watch the
main menu which will appear everytime if something went wrong, so you have
more control over the situation. Proceed to "Partition a hard drive".

Now it is time to partition your harddisks. Select the disk you want
to partition and a partitioning program suitable for your architecture
will be started. Partition the harddisk to your needs and quit the
program. Select "Finish" to proceed.

On the next screen you have to configure and mount your partitions. Select
the partitions you want to use in the system you wish to install and select
a filesystem and a mount point for them. Remember to assign at least one
partition for swap space and to mount a partition on "/".

Please note the debian-installer will do no changes to your harddisks until
you select "Finish". Do this when you are sure that you have found a
suitable setup for your partitions and answer the next question with "Yes".

Now debian-installer starts to install the base system which can take a
while. That is followed by installing a kernel.

The last step is to install a boot loader. You will be prompted for
the device where GRUB should be installed. It defaults to the boot
record of the first harddrive which is generally a good choice,
but if you have another OS installer that you want to keep booting, be
careful not to overwrite your master boot record.

Debian-installer will now tell you that the installation has
finished. Remove the cdrom from your drive and hit ENTER to reboot
your machine. Make sure it boots from harddisk, cross your fingers and
wait until base-config is started.

Stepping through base-config is not within the scope of this document
as it is not part of debian-installer.


3.1. Expert mode installation

From here on, I assume you have downloaded and burnt the 'netinst'
CD. Put it into your CD-drive and make your system boot from CD.

You will be greeted by a welcome screen. Type "expert" and hit ENTER to
boot. After a while you will be presented with the main-menu of the
debian-installer.  Some general remarks:

The main-menu is not static. New entries are added when new installer
modules are loaded. However main-menu tries to resolve the next best
choice and presents that as default selection. If that selection does
not suit your needs just select another entry. If you select an entry
that requires the configuration of an entry you did not yet choose,
the main-menu will try to resolve these dependencies automatically.
This can be used to automate the install process, by selecting always
the last visible step. 

When main-menu first is shown, the default will be "Choose language". Hit
return and choose your language from the list that now is presented. You
will be taken back to main-menu and the next item will be the default,
which is "Choose country". Select that entry and observe that the installer
tries to set a reasonable default based upon your language selection.
Select your country and continue.

The next step is "Detect a keyboard and select layout". Again the installer
will attempt to pick a reasonable default. Select your preferred keymap and
continue.

The next step is "Detect CDROM devices and mount the CD". As part of this
step, the installer will probe the system for hardware, and load kernel
modules for detect hardware. You will be given a chance to veto the loading
of kernel modules (in case they cause problems), and to specify parameters
to pass to the kernel when the modules are loaded. After the hardware is
detected, the CD should be found automatically in most cases.

Now we are able to load the rest of the installer. Select the corresponding
entry "Load installer components". Since the modules we want to access are
on the CD, select "cdrom-retriever". The floppy-retriever can be used to
load additional modules from a floppy, e.g. if you have exotic hardware.
See section 2.1.1 if you have a SCSI CDROM.

You are presented a long list with optional components to install. We
only want to install the standard components, which are selected
automatically, so just hit "Continue". Wait and watch until all
components have been loaded.

Main-menu appears again, but with the additional modules there are new
entries. The next default step would be to configure a network. We are
breaking out of the default route, because we do not need networking
since the base debs are on the CD.

Select "Detect hardware". This will repeat the hardware detection process,
but now the installer has more kernel modules available to it.

Now it is time to partition your disk. There are basically two ways to
do that. The first one is to use cfdisk, which will be started upon
selecting the menu entry "Partition a harddrive". Be sure to create at
least two partitions, one for swap and one for the root filesystem.

The other possibility is to use the autopartitioner. Select
"Automatically partition harddrives" which tries to determine a sane
partitioning. WARNING: Use this option ONLY if you have no or
unimportant data on your harddrives.

After finishing partitioning, select the entry "Configure and mount
partitions". Since autopartkit creates filesystems and mounts them
automatically you can skip this step if you used autopartkit to partition
your harddrive.

Configuring the partitions is pretty straightforward. You are
presented with a list with all partitions, their sizes and a filesystem
if one was detected on that partition. Selecting a partition lets you
choose which filesystem to create on that partition. If you select a
non-swap filesystem, you are also asked for a mount point.

Configure the partitions to your need, and remember to specify a
partition with mount point "/". When you've made your choices, select
"Finish" and confirm that the filesystems should be created as
requested.

Now we are ready to install the base system. Select the corresponding entry
("Install the base system") and lean back. The packages are retrieved from
the CD and installed in the /target area. During this step, you will
presented a list of all available kernel images on the CD. Select the most
suitable for your system and wait until the installation has finished.

Now we are almost done. Select "Install LILO on a hard disk" or
"Install GRUB on a hard disk" to make your harddisk bootable. You will
be asked where LILO/GRUB shall install the bootblock. A good idea is
the first hard drive in your system which should be in fact the
default selection.

If that last step has completed successfully select "Finish the
installation and reboot", eject your CD and wait until your computer
restarts. Make sure it boots from harddisk, cross your fingers and
wait until base-config is started.

Stepping through base-config is not within the scope of this document
as it is not part of debian-installer.


4. Installation Report

If you successfully managed an installation with debian-installer,
please take time to provide us with a report. There is a template
named "install-report.template" in the /root directory of a freshly
installed system. Please fill it out and file it as a bug against the
package "installation-reports". See section 5 on how to file bugs.


5. Reporting bugs

If you did not reach base-config or ran into other trouble, you
probably found a bug in debian-installer. To improve the installer it
is necessary that we know about them, so please take your time and
report them.

First, look here to see if your bug has already been reported:
http://bugs.qa.debian.org/cgi-bin/debian-installer.cgi?full=yes

The page is sorted by packages which represent the individual
subsystems of debian-installer. File your bug against the respective
subsystem or, if you do not know which it is, against the package
"install". Look here for an explanation of how to file bugs:
http://www.debian.org/Bugs/Reporting


6. Get involved

The Debian-Installer Team always welcomes people who would like to
work on the installer. We have plenty of work to do: fixing bugs,
improve usability, create new modules and of course extensive
testing. If you are interested to help, check out this page:
http://www.debian.org/devel/debian-installer/