DEBOPS.PRESEED(5)

NAME
debops.preseed - Manage Debian Preseeding configuration with Ansible

SYNOPSIS

debops run service/preseed [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Preseeding <https://wiki.debian.org/DebianInstaller/Preseed> is a way to configure the Debian Installer non-interactively. During installation, a special text file can be downloaded over HTTP, this file can provide answers to the installer questions.

After installation, a custom shell script will be downloaded and run in the target environment to prepare host for remote use (an admin account will be created, SSH keys will be configured, optionally a Salt Minion will be installed and will start on the next boot).

GETTING STARTED

  iPXE integration

The debops.preseed role integrates very well with the Debian-Installer configuration provided with the debops.ipxe role. You can use the menu system defined there to select different Preseed flavors and provide needed parameters like hostname and Debian mirror to use.

  How Debian Installer preseeding works

The Debian Installer can use automatic preseed.cfg lookup system when specific kernel parameters are defined during the boot process. These parameters are:

auto=true url=<seed>

If a simple string and not a full URL is specified as <seed>, Debian Installer will expand it to:

http://<seed>/d-i/<release>/preseed.cfg

To enable Preseeded installation, after starting the Debian Installer, navigate the menu to "Advanced options" -> "Automated Install". Next, press the <Tab> key, this will let you enter additional boot options. Now you can specify the URL of the Preseed file. The menu system implemented in the debops.ipxe role can do this automatically for you when you select preseed installation method.

  Default set of Preseed flavors

Debian Preseeding can be used to provision various types of hardware or virtual machines. Not all of them are the same however, and to facilitate that, the debops.preseed role implements a system of preseed "flavors" which can be selected to enable different configuration options. The current set of "flavors" available by default is:
 | root-only | administrative user
hardware, non-free APT repos, manual partitioning | debian | debian-user
virtual machine, guided single LVM partition | debian-vm | debian-vm-user

If we assume that the DNS domain of the cluster is example.org, the Preseed flavors are presented as DNS subdomains of the main server domain by default defined as seed.example.org. For this to work reliably, DNS database needs to contain CNAME records that point to the Preseed server, for example:

•   debian.seed.example.org

•   debian-vm.seed.example.org

•   debian-user.seed.example.org

•   debian-vm-user.seed.example.org

    For convenience, you might also want to create a short DNS records for the *.seed "domain" that can be used in the menu system implemented by the debops.ipxe role:

•   debian.seed

•   debian-vm.seed

•   debian-user.seed

•   debian-vm-user.seed

    You can create your own Preseed "flavors" in the same way, just remember to add the needed CNAME DNS records.

  Example inventory

To configure the Preseed server, you can add a host to the [debops_service_preseed] group:

[debops_all_hosts]
hostname
[debops_service_preseed]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.preseed role:

---
- name: Provide Debian Preseed configuration files over HTTP
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_preseed' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::nginx' ]
      keyring__dependent_apt_keys:
        - '{{ nginx__keyring__dependent_apt_keys }}'
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ nginx__apt_preferences__dependent_list }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python' ]
      python__dependent_packages3:
        - '{{ nginx__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ nginx__python__dependent_packages2 }}'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__servers:
        - '{{ preseed__nginx__dependent_servers }}'
    - role: preseed
      tags: [ 'role::preseed', 'skip::preseed' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::preseed
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.preseed Ansible role:

•   "Hands-Off" Debian Installation <https://hands.com/d-i/>

•   The Debian Installer Pressed page <https://wiki.debian.org/DebianInstaller/Preseed> on Debian Wiki

DEFAULT VARIABLE DETAILS

Some of debops.preseed default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  preseed__definitions

The preseed__*_definitions variables are used to define what Debian Preseed configuration files and postinst.sh scripts will be available on the Preseed server. Each combination consists of a preseed "flavor" which is used to provide different combination of configuration options at boot time, and a "release" which defines the Debian releases that will be able to use a given "flavor"[1].

  Examples

Create a new Preseed definition with modifications to the default configuration which will configure the host as being located in Germany with German UI by default. The debian-de.seed.example.org DNS record needs to point to the Preseed server for this to work as expected. Ensure that a few Debian releases can be used if needed.

NOTE: This is just an example; locale configuration is set by default based on the facts of the debops.locales role applied on the Preseed server host. You shouldn't have to set these preferences in most cases.

# Variable which holds Preseed modifications used in multiple definitions
preseed_options_german_locale:
  - name: 'debian-installer/locale'
    value: 'de_DE.UTF-8'
    state: 'present'
  - name: 'keyboard-configuration/xkb-keymap'
    value: 'de'
    state: 'present'
preseed__definitions:
  - name: 'debian-stretch-de'
    flavor: 'debian-de'
    release: 'stretch'
    options: '{{ preseed_options_german_locale }}'
  - name: 'debian-buster-de'
    flavor: 'debian-de'
    release: 'buster'
    options: '{{ preseed_options_german_locale }}'
  - name: 'debian-bullseye-de'
    flavor: 'debian-de'
    release: 'bullseye'
    options: '{{ preseed_options_german_locale }}'

You can find a list of the default Preseed definitions in the preseed__default_definitions variable.

  Syntax

The Preseed definitions use the Universal Configuration system to define configuration entries. The variables are combined using preseed__combined_definitions variable which defines the general order of merging the entries.

Each definition is created using a specific set of parameters:

name
    Required. An identifier of a given Preseed definition, not used otherwise. Must be unique across all definitions. Entries with the same name are merged in order of appearance and can affect each other.

flavor
    Required. Name of the "flavor" of a particular Debian Preseed. Multiple definitions can have the same flavor (this is mandatory if you want to support more than one Debian release at a time). Flavors need to be configured in the DNS so that hosts can reach the Preseed server while booting.

release
    Required. Name of a Debian release (bullseye, buster, etc.) which can use a particular Debian Preseed definition. Multiple definitions can have the same release as long as they use different flavors.

state
    Optional. If not defined or present, a given Preseed definition will be created on the host. If absent, a given definition will be removed from the host (the <release>/ directory itself will be removed).

options
    Optional. A list of preseed.cfg configuration options defined using the preseed__configuration format. Because there are usually multiple definitions for a given "flavor", it's easier to put options you want to change in a separate variable which can be referenced in the inventory using Jinja expansion.

    The role uses the "configuration template" defined by the main preseed__configuration variables as the base for each Preseed definition. The options specified here will override the ones defined elsewhere. Since many options are commented out by default, it's good practice to always specify the state present as needed to be sure that the option is in the correct state.

root_sshkeys
    Optional. YAML list of SSH public keys which should be added to the UNIX root account on the provisioned host using a postinst.sh script. The SSH keys specified here will be combined with the ones specified in the preseed__root_sshkeys list.

admin_username
    Optional. Name of the UNIX administrative account which should be configured for full sudo access and provisioned with administrator SSH public keys. The UNIX account will not be created by the postinst.sh script; you need to use the relevant Debian Preseed options to either create it automatically or allow the manual creation during provisioning.

admin_sshkeys
    Optional. YAML list of SSH public keys which should be added to the UNIX administrative account on the provisioned host using a postinst.sh script. The SSH keys specified here will be combined with the ones specified in the preseed__admin_sshkeys list.

postinst_commands
    Optional. YAML text block with bash(1) <https://manpages.debian.org/bash(1)> commands which will be executed at the end of the provisioning process by the postinst.sh script using eval. The commands are executed one by one so you should use simple expressions without loops or conditional statements. Commands specified here will be executed after the ones specified in the preseed__debian_postinst_commands variable.

  preseed__configuration

The preseed__*_configuration variables define the default contents of the preseed.cfg configuration files. They can be thought of as a "template" for Preseed configurations which can be further augmented in separate "flavors" or OS releases using the options parameters.

  Examples

Enable network console in Debian Installer on all Preseed flavors and releases. A file with SSH public keys should be published on a reachable host.

preseed__configuration:
  - name: 'anna/choose_modules'
    value: 'network-console'
    state: 'present'
  - name: 'network-console/authorized_keys_url'
    value: 'http://192.0.2.1/openssh-key'
    state: 'present'

The original Preseed configuration, based on the Example Debian Stable preseed file <https://www.debian.org/releases/stable/example-preseed.txt> can be found in the preseed__original_configuration variable. Customizations to the original options included by default in the role can be found in the preseed__default_configuration variable.

  Syntax

The Preseed configuration is based on the Universal Configuration system. The separate variables are merged in the preseed__combined_configuration variable which defines the merge order of configuration entries. Configuration is defined using a list of YAML dictionaries with specific parameters:

name
    Required. Name of the Preseed configuration option. Entries with the same name parameter are merged in order of appearance and can affect each other.

option
    Optional. If a configuration option has multiple "versions", each needs to be defined using an unique name parameter to avoid overwriting. In this case the option parameter can be used to specify the actual name of the Preseed configuration option stored in the config file.

comment
    Optional. A string or YAML text block with additional comments added to an option. The strings ${flavor} and ${release} inside comments will be replace with the current definition's "flavor" and "release" values.

state
    Optional. If not specified or present, the configuration option will be included in the generated configuration file. If absent, a given option will not be included in the generated file. If comment, the option will be included but commented out (inactive). If hidden, a configuration option will not be added but its comments will (this is useful to add separate comment sections). If ignore, a given entry will not be evaluated during role execution.

    It's suggested to use present explicitly if any options are defined in the inventory to ensure that the customized options are uncommented, since most of the existing options are commented out by default.

owner
    Optional. Each Preseed option has an "owner" package, usually d-i as in Debian-Installer which will be used as default if this parameter is not specified. Some options have different owners.

type
    Optional. Specify the type of a given Preseed option, either a string, boolean, select, multiselect or password. If not specified, the role will try to guess the correct type based on the defined value - strings and booleans are recognized automatically. The role will default to string if the correct type cannot be determined.

seen
    Optional, boolean. If present and False, the role will mark a given option as "not seen" by the Debian-Installer. This is supposed to allow manual confirmation of a given option, but this hasn't been observed in practice - further testing is needed.

value
    The value of a given option. This can be either a string, a YAML list which will be concatenated into a string separated by spaces, a boolean True/False or a YAML text block with multiline value. Empty strings are permitted.

    If a YAML list is used, multiple entries with the same name parameter will merge the lists together. To reset an existing list, use an empty string in a separate entry.

FOOTNOTES

[1] The "release" mechanism is explicitly required by Debian-Installer which will use the URL in the form https://<host>/d-i/<release>/./preseed.cfg to retrieve the configuration file automatically.

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others