General questions

What is the Ubuntu installer called?

OK, not many people actually ask this, but it will save time later if I pretend that they do. Ubuntu supports three installers:

• d-i

  • .. or the Debian installer (bugs go on the debian-installer package). This is Ubuntu's oldest and best-tried installation method. It's enormously flexible, automatable to the hilt, and gives you quite a lot of control. It also asks quite a lot of questions and isn't particularly pretty. People who like to do complicated things with the installer will probably like this. d-i is the only supported method for installing the Ubuntu server edition, the only reliable way to netboot Ubuntu installs, and is available on the "alternate install CD" and the DVD for those with special requirements.

• Ubiquity
  • d-i proved to be a bit complicated for straight-up-and-down desktop installations, where you can get away with less flexibility in exchange for a simpler installer. We didn't want to lose out on all the bug-fixes that had gone into d-i over the years, so we built a graphical front-end to it called Ubiquity. It's intentionally less flexible than d-i in a number of places, and intentionally gives you less control, although it isn't entirely dumbed-down either and still offers things like manual partitioning as an option. Its user interface was designed by hand, and, as a side effect of the way it works from a live CD, it typically installs Ubuntu much more quickly than d-i does. It is available on the "desktop CD" and the DVD. In either case, you may start it from the desktop, or (as of Ubuntu 7.10) use the CD boot loader option to start up the live CD straight into Ubiquity.
• Wubi
  • Many Windows users want to try out Ubuntu without having to repartition their hard disk. Wubi lets them do this, by installing Ubuntu into a large file on their Windows partition, and adding some boot-time magic to make this work almost transparently. Although I refer to it here as a separate installer, it consists of a Windows shell that asks a small number of questions on a single screen, and then uses Ubiquity to do the real installation.

How do I find more documentation about the Ubuntu installer?

d-i is well-documented in the Installation Guide, which is based heavily on Debian's similar document:

• Ubuntu 7.10: https://help.ubuntu.com/7.10/installation-guide/

• Ubuntu 8.04 LTS: https://help.ubuntu.com/8.04/installation-guide/

• Ubuntu 8.10: https://help.ubuntu.com/8.10/installation-guide/

Ubiquity is less well-documented. Its wiki page has some skeletal information.

What installation methods do you support?

Ubuntu has quite a wide variety of possible installation methods, although some are better-supported than others, and there are some things that simply aren't available at the moment. The following methods work well on most systems:

• CD
  • simple graphical installer from the desktop CD
  • flexible text installer from alternate and server CDs
• DVD (either graphical or text)
• Netboot (a.k.a. PXE boot)
  • defaults to using a full Ubuntu mirror on the Internet appropriate for your country
  • may use a local mirror provided that at least the "main" and "main/debian-installer" components are present, and perhaps also "restricted" and "restricted/debian-installer"

  • may work with a mounted CD or DVD image but is likely to break in certain circumstances, so this method is not currently recommended; however the contents of such an image might be useful to get a local mirror started

  • PXE-booting the graphical installer is believed to be possible with some versions of Ubuntu, but is lightly-tested; this method needs a regular maintainer
• USB drive
  • prior to Ubuntu 8.10, was supported using the hd-media installation method, requiring some downloads and manual setup (see the installation guide)
  • as of Ubuntu 8.10, we recommend using usb-creator (shipped with Ubuntu 8.10 desktop and above) to create the USB image

  • pre-loaded drives also available from the Canonical Store

It's also possible to combine these installation methods in various ways. For example, the characteristics of a netboot installation are firstly that you boot it over the network, and secondly that it acquires packages from the network. It's occasionally useful to boot from a (small!) CD and acquire packages from the network, and you can do this with the netboot mini.iso image. On systems with a very narrow range of boot possibilities, booting the installer is of course usually the hardest bit, and once you get that going the rest is usually not very difficult.

The following methods are not supported:

• Floppy disks

Do you support automatic installations?

Do we ever.

d-i was designed from the ground up around the Debian Configuration Management System (debconf), one of whose goals was to support automatic configuration of a variety of systems up to and including the installer. Every time d-i asks a question, it does so through a debconf frontend, and the answer goes into the debconf database. You can set up the debconf database in advance, using a technique known as "preseeding", so that the installer finds a preset answer in it every time it needs to know the answer to a question, and automatic installation magically Just Works.

Well, almost. As with any real-world system there are some quirks. The best general advice I can give here is to read Appendix B of the Installation Guide corresponding to the release of Ubuntu you're installing, which has lots of information on preseeding. It is very important that you read the correct version of the Installation Guide; don't use Debian's guide, and don't use one for a different release of Ubuntu. The preseeding documentation needs to be matched up with corresponding installer code, and there are differences between Debian and Ubuntu as well as between different versions of Ubuntu. Using the wrong guide is a recipe for frustration.

We also support a version of Red Hat's Kickstart automatic installation system, implemented by translating it on the fly into preseeding. The "Automatic Installation" section of the guide has details, with specific notes on Ubuntu-specific additions to Kickstart as well as features of Kickstart not yet supported in Ubuntu.

Ubiquity can be automated in a similar way to d-i, with some minor differences.

How do I debug the installer?

Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. - Brian W. Kernighan

There are a few Swiss Army Knives that can help with installer debugging. The most prominent is getting a full debconf trace. First, see the debconf-devel(7) manual page to learn about the protocol. You can boot d-i with DEBCONF_DEBUG=developer on the kernel command line, in which case you'll get a trace in /var/log/syslog. If you're using Ubiquity, then either you're starting it directly from the boot loader ("Install Ubuntu") in which case you can put debug-ubiquity on the kernel command line, or you're running it from a live CD ("Try Ubuntu without any change to your computer") in which case you can run ubiquity --debug. Debconf traces are an excellent way to track down all kinds of problems.

Sometimes you may need something a bit more detailed:

• If the problem lies in a shell script, putting the set -x command near the top of it will give a full execution trace.

• If you can't figure out why Ubiquity is crashing, you can run it with the --pdb option to have it drop into the Python debugger in the event of a crash.

• In d-i, you can run udpkg -i /cdrom/pool/main/s/strace/strace-udeb_* (or otherwise acquire an appropriate strace-udeb package and install it into the installation environment) and then use strace to get system call traces.

How do I test proposed installer changes?

Sometimes you may be asked to test a netboot installer image from intrepid-proposed (or hardy-proposed, etc.). The images may be found here (replace "i386" with your architecture as necessary):

http://archive.ubuntu.com/ubuntu/dists/intrepid-proposed/main/installer-i386/

In order to install successfully from these images, you will normally need to tell the installer to fetch its own components from intrepid-proposed as well, which is not the default. To do this, add the following boot parameter:

apt-setup/proposed=true

You must make sure that the mirror you are installing from contains packages from intrepid-proposed. All official mirrors will do so; if you operate your own mirror or use a site-local mirror, it may need to be modified to pull from intrepid-proposed. Make sure that you do not simply use a loopback mount of a CD or DVD image as an installation source; this is one of the cases where such mirrors will not work, since they do not contain the updated kernel packages required by the new installer.

Why does the installer not offer an option to create a separate home partition?

Preserving the contents of /home during installation has been implemented in the installer since Ubuntu 8.04. This is achieved by deleting the system files and directories that are about to be replaced and then continuing with a normal installation, leaving /home, /opt and others untouched. We decided against creating a separate /home partition as there is no correct answer for a /home partition, / partition size split for all users, and we felt the likelihood that whatever guess we came up with would be a major regression for a large subset of our users was quite high.

In addition to this, partitioning is a complex subject, one that is quite difficult for many non-technical users to understand. This difficulty is further complicated by a lack of safe, online partition resizing in Linux.

Specific installation problems

Why does the installer fail to detect my CD? It booted off it!

To start the installer successfully from a CD, two entirely different sets of software have to be able to cope with your CD drive. Firstly, the BIOS and the boot loader (usually isolinux) need to cooperate to read the Linux kernel and initial RAM disk (initramfs) from the CD. Those are loaded into memory and Linux starts, after which the installer is started from the initramfs. Only the bare bones of the installer are in the initramfs, though, and at some point the installer will need to read some more files from the CD. At that point, Linux has to have a driver for your CD, and that driver has to be present in either the kernel or the initramfs. It's entirely possible for this to fail even when the BIOS and the boot loader managed to read from the CD just fine.

There are two principal ways this can go wrong:

• Linux doesn't have a driver for your CD at all, it isn't enabled in Ubuntu, or it's broken in some way
• Ubuntu does have an enabled and working driver for your CD, but it isn't in the installer's initramfs

These two cases may be distinguished by trying the desktop CD. If it fails, then you have the first problem; if it succeeds, then you have the second problem.

In either case, file a bug on the 'linux' package in Ubuntu, quoting the output of 'lspci -vvnn' run as root (the desktop CD is often the easiest way to get hold of this). We don't usually need to know the make of your motherboard, the brand name of your CD drive, or that kind of thing - lspci output is usually enough to track down the relevant driver.

(There are some cases where this may in fact be due to some other installer bug, but they are comparatively rare.)

Why does the installer think there are no partitions on my disk?

This is usually because libparted failed to understand your partition table. The first thing we need is usually a dump of your boot sector (which includes the partition table) so that we can analyse it; we may need further dumps of specific parts of the disks after this. You can produce this dump using the following command from a running live CD, replacing /dev/sda with the name of your disk device if it's something else:

sudo od -Ax -tx1 -N512 /dev/sda

I'm installing Ubuntu 8.04 LTS on LVM, but it keeps asking about existing LVM data

The 8.04 installation guide contained the following recommendation:

# If one of the disks that are going to be automatically partitioned
# contains an old LVM configuration, the user will normally receive a
# warning. This can be preseeded away...
d-i partman-auto/purge_lvm_from_device boolean true

Unfortunately, this was out of date with respect to the actual installer code in 8.04. The correct text should be as in the 8.10 guide, so use this instead:

# If one of the disks that are going to be automatically partitioned
# contains an old LVM configuration, the user will normally receive a
# warning. This can be preseeded away...
d-i partman-lvm/device_remove_lvm boolean true

I'm installing Ubuntu 8.10 and Kickstart doesn't work

See bug 293586. This is fixed with the images in intrepid-updates, or you can use these images built against the 8.10 kernel as released.