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 usb-stick. If you want to include the file in an installation ISO image, you will have to remaster the 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 https://www.debian.org/releases/bookworm/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 installation image:
  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] 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] 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 Debian 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. See Section 5.1.5, “The Boot Screen” for information on how to add a boot parameter.

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/bookworm/./preseed.cfg.

The last part of that url (d-i/bookworm/./preseed.cfg) is taken from auto-install/defaultroot. By default this includes the directory bookworm 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/bookworm/./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 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] 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
auto auto-install/enable
classes auto-install/classes
file preseed/file
url preseed/url
theme debian-installer/theme
language debian-installer/language
country debian-installer/country
locale debian-installer/locale
keymap keyboard-configuration/xkb-keymap
modules anna/choose_modules
firmware hw-detect/firmware-lookup
interface netcfg/choose_interface
domain netcfg/get_domain
hostname    netcfg/get_hostname
protocol mirror/protocol
suite mirror/suite
recommends base-installer/install-recommends
tasks tasksel:tasksel/first
desktop tasksel:tasksel/desktop
preseed-md5 preseed/file/checksum

B.2.5. Examples of boot prompt preseeding

Here are some examples of how the boot prompt might look like (you will need to adapt this to your needs; also see Section 5.1.5, “The Boot Screen”).

# To set French as language and France as country:
/install.amd/vmlinuz vga=788 initrd=/install.amd/gtk/initrd.gz language=fr country=FR --- quiet
# To set English as language and Germany as country, and use a German keyboard layout:
/install.amd/vmlinuz vga=788 initrd=/install.amd/gtk/initrd.gz language=en country=DE locale=en_US.UTF-8 keymap=de --- quiet
# To install the MATE desktop:
/install.amd/vmlinuz vga=788 initrd=/install.amd/gtk/initrd.gz desktop=mate-desktop --- quiet
# To install the web-server task:
/install.amd/vmlinuz initrd=/install.amd/initrd.gz tasksel:tasksel/first=web-server ---

B.2.6. 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 Debian 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 Debian 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 Debian 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.