B.2. Using preseeding
| Appendix B. Automating the installation using preseeding |

## B.2. Using preseeding

You will first need to create a preconfiguration file and place it in the location from where you want to use it. Creating the preconfiguration file is covered later in this appendix. Putting it in the correct location is fairly straightforward for network preseeding or if you want to read the file off a floppy or usb-stick. If you want to include the file on a CD or DVD, you will have to remaster the ISO image. How to get the preconfiguration file included in the initrd is outside the scope of this document; please consult the developers' documentation for `debian-installer`.

An example preconfiguration file that you can use as basis for your own preconfiguration file is available from ../example-preseed.txt. This file is based on the configuration fragments included in this appendix.

### B.2.1. Loading the preconfiguration file

If you are using initrd preseeding, you only have to make sure a file named `preseed.cfg` is included in the root directory of the initrd. The installer will automatically check if this file is present and load it.

For the other preseeding methods you need to tell the installer what file to use when you boot it. This is normally done by passing the kernel a boot parameter, either manually at boot time or by editing the bootloader configuration file (e.g. `syslinux.cfg`) and adding the parameter to the end of the append line(s) for the kernel.

If you do specify the preconfiguration file in the bootloader configuration, you might change the configuration so you don't need to hit enter to boot the installer. For syslinux this means setting the timeout to `1` in `syslinux.cfg`.

To make sure the installer gets the right preconfiguration file, you can optionally specify a checksum for the file. Currently this needs to be a md5sum, and if specified it must match the preconfiguration file or the installer will refuse to use it.

    Boot parameters to specify:
    - if you're netbooting:
      preseed/url=http://host/path/to/preseed.cfg
      preseed/url/checksum=5da499872becccfeda2c4872f9171c3d
    - or
      preseed/url=tftp://host/path/to/preseed.cfg
      preseed/url/checksum=5da499872becccfeda2c4872f9171c3d

    - if you're booting a remastered CD:
      preseed/file=/cdrom/preseed.cfg
      preseed/file/checksum=5da499872becccfeda2c4872f9171c3d

    - if you're installing from USB media (put the preconfiguration file in the
      toplevel directory of the USB stick):
      preseed/file=/hd-media/preseed.cfg
      preseed/file/checksum=5da499872becccfeda2c4872f9171c3d

Note that `preseed/url` can be shortened to just `url`, `preseed/file` to just `file` and `preseed/file/checksum` to just `preseed-md5` when they are passed as boot parameters.

### B.2.2. Using boot parameters to preseed questions

If a preconfiguration file cannot be used to preseed some steps, the install can still be fully automated, since you can pass preseed values on the command line when booting the installer.

Boot parameters can also be used if you do not really want to use preseeding, but just want to provide an answer for a specific question. Some examples where this can be useful are documented elsewhere in this manual.

To set a value to be used inside `debian-installer`, just pass ``path/to/variable`=`value`` for any of the preseed variables listed in the examples in this appendix. If a value is to be used to configure packages for the target system, you will need to prepend the owner[19] of the variable as in ``owner`:`path/to/variable`=`value``. If you don't specify the owner, the value for the variable will not be copied to the debconf database in the target system and thus remain unused during the configuration of the relevant package.

Normally, preseeding a question in this way will mean that the question will not be asked. To set a specific default value for a question, but still have the question asked, use “?=” instead of “=” as operator. See also Section B.5.2, “Using preseeding to change default values”.

Note that some variables that are frequently set at the boot prompt have a shorter alias. If an alias is available, it is used in the examples in this appendix instead of the full variable. The `preseed/url` variable for example has been aliased as `url`. Another example is the `tasks` alias, which translates to `tasksel:tasksel/first`.

A “---” in the boot options has special meaning. Kernel parameters that appear after the last “---” may be copied into the bootloader configuration for the installed system (if supported by the installer for the bootloader). The installer will automatically filter out any options (like preconfiguration options) that it recognizes.

| Note
Current linux kernels (2.6.9 and later) accept a maximum of 32 command line options and 32 environment options, including any options added by default for the installer. If these numbers are exceeded, the kernel will panic (crash). (For earlier kernels, these numbers were lower.)

For most installations some of the default options in your bootloader configuration file, like `vga=normal`, may be safely removed which may allow you to add more options for preseeding.

| Note
It may not always be possible to specify values with spaces for boot parameters, even if you delimit them with quotes.

### B.2.3. Auto mode

There are several features of Ubuntu Installer that combine to allow fairly simple command lines at the boot prompt to result in arbitrarily complex customized automatic installs.

This is enabled by using the `Automated install` boot choice, also called `auto` for some architectures or boot methods. In this section, `auto` is thus not a parameter, it means selecting that boot choice, and appending the following boot parameters on the boot prompt.

To illustrate this, here are some examples that can be used at the boot prompt:

    auto url=autoserver

This relies on there being a DHCP server that will get the machine to the point where `autoserver` can be resolved by DNS, perhaps after adding the local domain if that was provided by DHCP. If this was done at a site where the domain is `example.com`, and they have a reasonably sane DHCP setup, it would result in the preseed file being retrieved from `http://autoserver.example.com/d-i/bionic/./preseed.cfg`.

The last part of that url (`d-i/bionic/./preseed.cfg`) is taken from `auto-install/defaultroot`. By default this includes the directory `bionic` to allow future versions to specify their own codename and let people migrate forwards in a controlled manner. The `/./` bit is used to indicate a root, relative to which subsequent paths can be anchored (for use in preseed/include and preseed/run). This allows files to be specified either as full URLs, paths starting with / that are thus anchored, or even paths relative to the location where the last preseed file was found. This can be used to construct more portable scripts where an entire hierarchy of scripts can be moved to a new location without breaking it, for example copying the files onto a USB stick when they started out on a web server. In this example, if the preseed file sets `preseed/run` to `/scripts/late_command.sh` then the file will be fetched from `http://autoserver.example.com/d-i/bionic/./scripts/late_command.sh`.

If there is no local DHCP or DNS infrastructure, or if you do not want to use the default path to `preseed.cfg`, you can still use an explicit url, and if you don't use the `/./` element it will be anchored to the start of the path (i.e. the third `/` in the URL). Here is an example that requires minimal support from the local network infrastructure:

    auto url=http://192.168.1.2/path/to/mypreseed.file

The way this works is that:

- if the URL is missing a protocol, http is assumed,

- if the hostname section contains no periods, it has the domain derived from DHCP appended to it, and

- if there's no `/`'s after the hostname, then the default path is added.

In addition to specifying the url, you can also specify settings that do not directly affect the behavior of `debian-installer` itself, but can be passed through to scripts specified using `preseed/run` in the loaded preseed file. At present, the only example of this is `auto-install/classes`, which has an alias `classes`. This can be used thus:

    auto url=example.com classes=class_A;class_B

The classes could for example denote the type of system to be installed, or the localization to be used.

It is of course possible to extend this concept, and if you do, it is reasonable to use the auto-install namespace for this. So one might have something like `auto-install/style` which is then used in your scripts. If you feel the need to do this, please mention it on the `<debian-boot@lists.debian.org>` mailing list so that we can avoid namespace conflicts, and perhaps add an alias for the parameter for you.

The `auto` boot choice is not yet defined on all arches. The same effect may be achieved by simply adding the two parameters `auto=true priority=critical` to the kernel command line. The `auto` kernel parameter is an alias for `auto-install/enable` and setting it to `true` delays the locale and keyboard questions until after there has been a chance to preseed them, while `priority` is an alias for `debconf/priority` and setting it to `critical` stops any questions with a lower priority from being asked.

Additional options that may be of interest while attempting to automate an install while using DHCP are: `interface=auto netcfg/dhcp_timeout=60` which makes the machine choose the first viable NIC and be more patient about getting a reply to its DHCP query.

| Tip
An extensive example of how to use this framework, including example scripts and classes, can be found on the website of its developer. The examples available there also show many other nice effects that can be achieved by creative use of preconfiguration.

### B.2.4. Aliases useful with preseeding

The following aliases can be useful when using (auto mode) preseeding. Note that these are simply short aliases for question names, and you always need to specify a value as well: for example, `auto=true` or `interface=eth0`.

priority | debconf/priority
fb | debian-installer/framebuffer
language | debian-installer/language
country | debian-installer/country
locale | debian-installer/locale
theme | debian-installer/theme
auto | auto-install/enable
classes | auto-install/classes
file | preseed/file
url | preseed/url
domain | netcfg/get_domain
hostname | netcfg/get_hostname
interface | netcfg/choose_interface
protocol | mirror/protocol
suite | mirror/suite
modules | anna/choose_modules
recommends | base-installer/install-recommends
tasks | tasksel:tasksel/first
desktop | tasksel:tasksel/desktop
dmraid | disk-detect/dmraid/enable
keymap | keyboard-configuration/xkb-keymap
preseed-md5 | preseed/file/checksum

### B.2.5. Using a DHCP server to specify preconfiguration files

It's also possible to use DHCP to specify a preconfiguration file to download from the network. DHCP allows specifying a filename. Normally this is a file to netboot, but if it appears to be an URL then installation media that support network preseeding will download the file from the URL and use it as a preconfiguration file. Here is an example of how to set it up in the dhcpd.conf for version 3 of the ISC DHCP server (the isc-dhcp-server Ubuntu package).

    if substring (option vendor-class-identifier, 0, 3) = "d-i" {
        filename "http://host/preseed.cfg";
    }

Note that the above example limits this filename to DHCP clients that identify themselves as "d-i", so it will not affect regular DHCP clients, but only the installer. You can also put the text in a stanza for only one particular host to avoid preseeding all installs on your network.

A good way to use the DHCP preseeding is to only preseed values specific to your network, such as the Ubuntu mirror to use. This way installs on your network will automatically get a good mirror selected, but the rest of the installation can be performed interactively. Using DHCP preseeding to fully automate Ubuntu installs should only be done with care.

[19] The owner of a debconf variable (or template) is normally the name of the package that contains the corresponding debconf template. For variables used in the installer itself the owner is “d-i”. Templates and variables can have more than one owner which helps to determine whether they can be removed from the debconf database if the package is purged.

B.1. Introduction |  | B.3. Creating a preconfiguration file