Differences between revisions 2 and 3
Revision 2 as of 2005-01-07 10:14:51
Size: 9559
Editor: anonymous
Comment:
Revision 3 as of 2005-01-08 09:37:48
Size: 10018
Editor: anonymous
Comment:
Deletions are marked like this. Additions are marked like this.
Line 73: Line 73:
'''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 not 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.

CDD Tool

There is a lot of people working on CustomDebian Distributions, but it seems that everyone is reinventing the wheel to do it.

This document proposes the design of a cdd-tool that tries to standardize the way developers define their CDD and provides tools to distribute, install, update and manage the customized system.

This tool will be developed on the current [http://alioth.debian.org/projects/cdd cdd project] on alioth and discussed on the debian-custom@lists.debian.org mailing list.

The CDD Meta-data Package

The basic idea is that each CDD could be distributed in source form using a single deb package. This package will contain all the meta-data needed to install the CDD (or generate a system to install it) using the tools described here.

For this tool a CDD is defined as a set of tasks that will be used to install the system; each task declares a list of packages that have to be installed and includes the information needed to configure them. All the information will be declared using a file that uses a format similar to the Debian Control Files.

Of course, if a task needs to add configuration data that will be declared on the CDD control file and will be distributed with it.

Currently the configuration data that can be included and distributed includes debconf answers for the debian-installer and for the system's debconf and scripts that have to be executed after the package installation (needed to do things that can not be done with debconf pre-seeding) or before package or task removal.

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

The CDD Control File

The task definition control file uses a syntax similar to the Debian [http://www.debian.org/doc/debian-policy/ch-controlfields.html Control files].

The control file consists of one or more paragraphs of fields. 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 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.

Control File Fields

Include: the value given to this field has to be a directory or a file name and it's occurrence is replaced by the contents of the included file (or the contents of all the files found inside the directory). This field has been introduced to allow developers to use different directory layouts.

Task (mandatory): Name of the 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.

Description (mandatory): short description of the task, it is useful in general and is needed to build metapackages based on our tasks.

Architecture (optional): defaults to all, but can be used to include a list of supported architectures.

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

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 to be able to add meta-information for each dependency.

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.

Pkg-Relevance (optional): A number that indicates the relevance of the packages the task depends on; not all packages of a task have the same relevance, if it's value is changed the packages declared afterwards have the given relevance. Note that this attribute is given to the packages and used mainly to choose how to put packages on CD if the CDD installation needs more than one.

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

Task-Menu (optional): Name of a file or directory containing menu definitions for the task.

Base-Config (optional): Name of a file or directory containing files to be installed under /usr/lib/base-config/; note that if the directory contains subdirectories those will also be copied to /usr/lib/base-config/ (i.e. a menu/ subdirectory will be copied to /usr/lib/base-config/menu/).

Base-Config-Menu (optional): Name of a file or directory containing files to be installed under /usr/lib/base-config/menu/. If the developer uses a directory for all the base-config stuff that won't be needed.

Installer-Pressed (optional): Name of a file or directory containing debconf answers for the debian-installer. It can appear more than once.

Debconf-Preseed (optional): Name of a file or directory containing debconf answers for an installed system. It can appear more that once.

Cfg-Scripts (optional): Name of a file or a directory containing configuration scripts for the task. If can appear more than once and inside a directory all scripts are included to be executed in order.

Note that the configuration scripts have to support parameters similar to those defined for postinstall and preinstall scripts, that is, they have to support the parameters: post-install, pre-update, post-update, pre-remove, post-remove (note that we don't use purge, as the remove stage has to leave the package without customizations).

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 not 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- and they will be ignored by the cdd-tool system.

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

The CDD Tool

The idea is to have a single tool that acts as a fronted to all the CDD utilities, the syntax would be something like the following:

 cdd-tool OPTIONS COMMAND CMND_ARGS

Where OPTIONS is a list of options common to all tools, like:

 --version
 --help
 --debug
 --verbose
 --conf=FILENAME 

COMMAND is one of:

  • build: builds metapackages, task lists, installation CD, etc.

  • get: downloads all packages needed for the CDD (similar to debpartial-mirror)

  • install: installs all packages related to a CDD task applying preseeding and executing configuration scripts

  • update: updates all packages related to the CDD keeping customizations (without making questions to the user)

  • reconfigure: reconfigures all the packages included on a CDD task remove: removes all packages related to a CDD task purge: purges all packages related to a CDD task

And the CMND_ARGS usually include optional SUBCOMMANDS, the name of the CDD and a TASK_LIST to work with:

 cdd-tool OPTIONS COMMAND CDDNAME TASK_LIST 

Note that the tool is work in progress and possibly there will be additional commands and a configuration file (not already defined).

What's not on this document

To build a really custom distribution almost all derived distributions apply a lot of changes to the debian packages; with some help of the Debian Developers that could be avoided changing the way the packages read configuration files (i.e. not installing conffiles if they are complicated or can't be generated by debconf for the general case), adding debconf support to them (possibly using very low priority questions) or simply adding some kind of support for branding (i.e. using a standard file that is in fact a link handled by update-alternatives or a similar system).

Once we have a common cdd toolkit there will probably be more custom distributions and we will have a better position to ask all debian developers to help us make debian more customizable.