Custom Debian Distributions Toolkit (CDDT)

CDDT Source Packages

Author: Sergio Talens-Oliag
Contact: sto@debian.org
Date: 2006-01-30 01:01:56 +0100 (dl, 30 gen 2006)

Introduction

For the CDDT a CDD is a set of tasks that are declared on a description file that has a format similar to the debian control file; the CDDT Source Package contains this description and the files it references, when they are not provided by external packages.

This document describes:

Control file format

The control file consists of one or more paragraphs. The paragraphs are separated by blank lines.

Each paragraph consists of a series of data fields; each field consists of the field name, followed by a colon and then the data/value associated with that field. It ends at the end of the line. Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon.

Some fields' values may span several lines; in this case each continuation line must start with a space or a tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored.

Except when stated, only a single line of data is allowed and whitespace is not significant in a field body. Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships.

Field names are not case-sensitive, but it is usual to capitalize the field names using mixed case as shown on the fields description below.

Blank lines, or lines consisting only of spaces and tabs, are not allowed within field values or between fields - that would mean a new paragraph.

Description entities

The description file includes Tasks and uTasks definitions, the first ones are used on a standard Debian system, while the second ones are used for the debian-installer.

An uTask definition is used to give lists of .udeb and .deb packages to include or exclude from the installer (the list of .deb files is used to add or remove packages from the base system installation) and a set of presseeding files to include on the installer image (some of them are used unconditionally and some are simply copied to allow the customizer to have splitted preseedings and support conditional inclusions)

A task definition is used to provide the list of packages or tasks that have to be installed to provide the task's functionality and the information needed to configure those packages or, at least, give pointers to that information. Besides the needed dependencies, a task can also recommend and suggest other packages and tasks.

Currently the configuration data that can be included and distributed with a task includes preseeding (for the debian-installer and the system's debconf), references to configuration scripts (used to generate configuration files after package installation) and task control scripts to be executed before and after task installation, upgrade or removal.

Other configuration data like special user menus can also be included on the CDD metadata (using the data field), but for other things (like branding), proper debian packages are probably a better idea and can be included on the task dependencies.

Description fields

On the following sections we will define the fields that can be written on a description file; each field description will include the name of the field, if it is required or optional and the type of values it represents.

The CDD description fields support the following data types:

Global fields

  • Include (optional, file): the value given to this field is the path to a file that is parsed as if it were inline. It is used to allow the splitting of a CDD description into multiples files, as the tools that manipulate them usually only take one file as the description source.

    Note that while the parser reads an included file it changes the working directory to the one the file is in to handle the fields of type filepath as expected (relative paths are calculated from the included file location, not from the location of the file that includes it).

    This field can be used anywhere on a description file.

  • X- (optional, string): the fields that start with the prefix X- are read as strings and all the occurrences of the same field name are saved within the context of the paragraph they appear on (task or utask).

    This field can be used anywhere on a description file and it is associated with the scope it appears in (global, task, utask, ...).

Task and uTask fields

  • Data (optional, filepath): Path of a file in dh_install format, used to install files with a Task or uTask (files can be scripts, configuration files, etc.). Note that the paths of the files to install must be relative to the CDD package base directory.
  • Description (optional): short description of the Task or uTask, it is useful in general and is needed to build metapackages based on our tasks (if the field is not present we generate a simple description using the task name).
  • Architecture (optional): defaults to all, but can be used to include a list of supported architectures.

uTask fields

  • uTask (optional, string): name of a debian installer task, used to customize the debian-installer; the field must be the first one of its paragraph and all fields of the paragraph are related to that installer task.

    This kind of task does not support inter task dependencies, usually a CDD will only have one uTask, if more than one is defined they are used to generate different installers.

  • Installer-uDeb-Include (optional, package dependency): list of .udeb to install on the debian-installer RAM disk. This field is used only on uTasks.

  • Installer-uDeb-Exclude (optional, package dependency): list of .udeb not to install on the debian-installer RAM disk. This field is used only on uTasks.

  • Installer-Deb-Include (optional, package dependency): list of .deb to install on the debian-installer target disk. This field is used only on uTasks.

  • Installer-Deb-Exclude (optional): list of .deb not to install on the debian-installer target disk. This field is used only on uTasks.

  • Initrd-Preseed (optional): name of a file that contains debconf answers for the debian-installer to be used before starting the debian installer menu. This field is used only on uTasks. The field can appear more than once, the file included on the initrd is built concatenating all the files listed on that field.

  • Initrd-Optional-Preseed (optional): name of a file that contains debconf answers for the debian-installer that can be included from the Initrd-Preseed file. This field is used only on uTasks. The field can appear more than once, each entry is appended to the list of files related to that field on the uTask.

Task fields

  • Task (required): name of a task; always is written on the first line of a paragraph and all the fields of its paragraph and the following ones apply to this task (until a new task declaration is found). Note that the the same task name can be present more than once, for the second and following occurrences the fields are overridden or appended to the original task definition.

  • Section (optional): section given to the task (misc by default).

  • Installer-Preseed (optional): name of a file that contains debconf answers for the debian-installer. This field is used on Tasks to load preseedings when installing a Task from the debian-installer (for example to provide a fixed ethernet address to an interface when installing a server task). The field can appear more than once, each entry is appended to the list of files related to that field on the Task.

  • Installer-Optional-Preseed (optional): name of a file that contains debconf answers for the debian-installer that can be included from an Installer-Preseed file. This field is used only on Tasks. The field can appear more than once, each entry is appended to the list of files related to that field on the Task.

  • Depends, Recommends, Suggests (optional): at least one of them is required, they list the packages we want to include and can be present multiple times.

    The name of the field will imply the same as on the control file, and will have different effects depending on the target system (i.e. for tasksel recommends and suggests can be put on different tasks to be able to install only the basic dependencies).

  • Conflicts (optional): this should not be needed, but maybe is interesting to be able to declare explicit conflicts for important and standard packages, mainly to avoid it's installation on the initial base-installer run.

  • Task-Depends, Task-Recommends, Task-Suggests and Task-Conflicts (optional): tasks are not packages, to handle the relationship between them we use those fields instead of the standard ones. Note that the contents of those fields are simple lists of tasks names, there are no virtual tasks, or'ed dependencies or versioned dependencies. The virtual tasks make no sense (tasks are already virtual), nor the or'ed dependencies (we can build a task with or'ed package dependencies) and the versioning is unnecesary (the tasks have no version number and the description contains all the tasks, if we need two versions of a task they need to have two different names).

  • Task-Relevance (optional): number that declares the relevance given to the task on the tasksel .desc files.

  • Task-Script (optional): list of files containing configuration scripts for the task. The files included on a directory are executed in order and the field can appear more than once.

    The scripts take parameters similar to those defined for postinstall and preinstall scripts; they must support the keywords post-install, pre-update, post-update, pre-remove and post-remove as first parameter (note that we don't use purge, as the remove stage has to leave the package without customizations).

  • Task-Script-Depends (optional): tools needed to execute the configuration scripts (i.e. cfengine, python, ... or whatever tools the developer uses on them).

    Note that the tools needed by the scripts of an installed CDD will not be removed by the cddtool (i.e. if a task that includes the tools is removed) and if the tools are removed by hand they will will be reinstalled by the cddtool when trying to use the scripts that need them.

  • Meta-Task (optional): boolean value that indicates if a task should be considered a metapackage or not. The flag is used when generating metapackages, to know if the task dependencies have to be expanded or not.

  • Install-Task (optional): boolean value that indicates if a task has to be installable from the debian-installer. Note that a task marked as Install-Task is also considered a Meta-Task.

  • Debconf-Preseed (optional): name of a file that contains debconf answers for an installed system. The field can appear more than once, each entry is appended to the list of files related to that field on the task.

  • Debconf-Optional-Preseed (optional): name of a file that contains debconf answers for an installed system that can be included from an Debconf-Preseed file. This field is used only on Tasks. The field can appear more than once, each entry is appended to the list of files related to that field on the task.

  • Base-Config (optional): name of a file to be installed under /usr/lib/base-config/. The field can appear more than once, each entry is appended to the list of files related to that field on the task.

  • Base-Config-Menu (optional): name of a file to be installed under /usr/lib/base-config/menu/. The field can appear more than once, each entry is appended to the list of files related to that field on the task.

  • Cfg-Script (optional): file that contains a configuration script for the task. The field can appear more than once, each entry is appended to the list of files related to that field on the task.

    The scripts are used to generate customized configuration files, they should be able to handle four different commands as their first argument:

    • gen-cfiles: this command will generate new configuration files; it has a mandatory argument, DESTDIR, that is used as the root directory for the generated configuration files (they have to be put into $DESTDIR/$CFILE_ABSPATH).
    • list-cfiles: this command lists all the files that could be modified by the script. The output is the absolute PATH of the files.
    • packages: this command lists the packages that can be afected by the script (usually the packages that own the generated files or can have some influence on the script that generates the configuration file).
    • services: this command lists the init.d services that can be affected by the configuration file changes, to know what do we have to restart after installing or removing the files generated by the cfg-script.
  • Cfg-Script-Depends (optional): tools needed to execute the configuration scripts (i.e. cfengine, python, ... or whatever tools the developer uses on them). Note that the tools needed by the scripts of an installed CDD will aot be removed by the cdd-tool (i.e. if a task that includes the tools is removed) and if the tools are removed by hand they will will be reinstalled by the cdd-tool when trying to use the scripts that need them.

For fields not defined here we will use the prefix X-; the fields will be ignored by the cdd-tool system, but the values are included on the tasks and can be used by external tools.

The control file can include comments using the # symbol at the beginning of a line (ONLY).

The CDD Binary Files

When building a CDD binary package all the information in the description is transformed and installed on a CDD directory (usually /etc/$CDD) with the following structure:

[TODO]

/etc/$CDD/
       |-> iTask/LINKS_TO_MTASK_SUBDIRS
       |-> mTask/$TASK/
       .   |-> control
       .   |-> base-config/*
       .   |-> base-config/menu/*
       .   |-> cfg-scripts/*
       .   |-> debconf.cfg
       .   |-> debconf/*
       .   |-> di-debconf.cfg
       .   |-> di-debconf/*
       .   |-> menu/*
       .   |-> tsk-scripts/*
       |-> version
       |-> uTask/$TASK/
       .   |-> initrd-debconf.cfg
       .   |-> initrd-preseed/*
       .   |-> udeb_include
       .   |-> udeb_exclude