From Mageia wiki
Jump to: navigation, search


Drakconf multiflag.png
Other languages
English ;
Synopsis:
drakclassic is a mastering tool that creates an ISO image containing the Mageia classical installer and its associated software repository (or 'Installer ISO' for short). The image includes a GRUB2 bootloader, which supports both legacy (MBR) and EFI boot. The image is a hybrid ISO, allowing it to be used with both optical media and USB flash drives.

Contents

Origins

drakclassic is a replacement for the bcd tool that was used to generate the Installer ISOs for previous Mageia releases. Much of its code is inherited from (and shared with) the draklive2 tool.

The main differences to the bcd tool are:

  • all necessary files are automatically extracted from the master software repository
  • the GRUB2 bootloader is used for both legacy and EFI boot
  • the GRUB2 boot menu supports language selection and is itself translated into the selected language
  • both 32-bit and 64-bit EFI boot are supported
  • significantly faster operation

Quickstart

To get started, first install the drakiso package. Then, if you haven't already done so, install and configure sudo to allow you to execute commands that require root privileges. Finally, clone the drakclassic-config git repository and then perform the following steps:

1. In your drakclassic-config clone, edit the file config/settings.cfg and adjust the following settings:

arch - either i586 or x86_64
repository - a path to a local mirror of the master software repository for a specific Mageia release (or Cauldron, when preparing for a new release)
workdir - a path to a directory where all files generated by drakclassic should be stored

2. Adjust any other parts of the configuration as desired.

3. In a terminal window, change directory to the top-level directory of your drakclassic-config clone and execute the commands:

./update_bootloader_files.sh
drakclassic --clean --all

or use the build_one.sh script which executes both these commands for you.

Note:
If drakclassic is run by the root user, sudo is not used and does not need to be installed.
Note:
You can create both 32-bit and 64-bit variants of the Installer ISO, regardless of whether the system you are using to create them is 32-bit or 64-bit.
Note:
You can use an HTTP or FTP URL instead of a path to a local mirror in the repository setting, but it will take much longer to create the ISO and use a lot more disk space if you do this.

In more detail

drakclassic is started from the command line. It can be run by any user, as it will then use the sudo command to execute any operations that require root privileges. If started without any command line options, it will just print a summary of the available options and exit.

drakclassic creates the Installer ISO in three major steps:

Media

This uses the rpmsrate file from the master software repository and the configuration files supplied by the user to determine which packages are to be included in the installer software repository on the ISO (as described in Package selection). It then generates the urpmi media and top-level media info that make up that repository and checks the repository for consistency. It then generates the product.id and package.idx files that will included in the ISO image.
This step is performed when either the --media or --all option is specified on the command line.

Boot

This prepares all the files needed for booting the installer.
This step is performed when either the --boot or --all option is specified on the command line. It does not need to be rerun if the Media step is rerun.

Master

This creates the final ISO image from the files created in the Media and Boot steps and from the installer stage 1 and stage 2 images and any other files the user has specified should be included, and generates any requested checksums.
This step is performed when either the --master or --all option is specified on the command line. It must be rerun if any of the previous steps are rerun.

If multiple steps are specified on the command line, drakclassic will execute them in the correct order, regardless of the order they appear.

The --clean option can be added on the command line to delete all files created by previous runs. Note that it uses the current settings to determine what to delete; there is no memory of what you last ran.

drakclassic normally outputs a relatively small amount of information as it progresses. The level of verbosity can be increased or decreased by adding the --verbose <level> option on the command line, where <level> ranges from 0 (minimum verbosity) to 4 (maximum verbosity).

ISO composition

The composition of the Installer ISO is controlled via two files, a basic settings file and a build configuration file. drakclassic looks for these files in the directory specified by the --config-dir command line option (subsequently referred to as <config-dir>). If not specified, <config-dir> will be set to the current working directory.

Basic settings

The basic settings file contains a list of parameters for controlling the Installer ISO creation. The name and location of this file can be specified by the --settings command line option. If not specified, the default is <config-dir>/config/settings.cfg.

Syntax

Each line of the basic settings file should contain a single parameter name and associated value, with the name and value separated by an '=' character, e.g.

arch=x86_64
version=6

Names should be simple alpha-numeric identifiers and must contain no white space. Values may be any sequence of characters. If a value is enclosed in either single or double quotes, the outermost pair of quote characters is discarded. No whitespace is allowed between the name and the '=' or, for quoted values, between the '=' and the first quote character or after the last quote character.

Lines starting with a '#' character are treated as comments and are ignored.

Note:
In the following sections, a setting name in angled brackets (e.g. <arch>) is used as shorthand for the setting value.

Required settings

drakclassic requires the following parameters to be defined:

arch
The architecture for the installer. Supported architectures are i586 and x86_64.
distro
An arbitrary string. Used as the distribution name stored in the product.id file on the ISO and for constructing the Installer ISO name.
release
An arbitrary string. Used as the release identifier stored in the product.id file on the ISO and for constructing the Installer ISO name.
repository
The URL or path to the master software repository that will be used to create the installer ISO. Only FTP or HTTP URLs are supported. The URL or path should end with a Mageia version number or cauldron; the architecture will be appended automatically.
vendor
An arbitrary string of up to 128 characters identifying the person or organization that is creating the Installer ISO. Used as the vendor name stored in the product.id file on the ISO and as the Publisher ID in the ISO meta-data.

Optional Settings

drakclassic recognises the following optional parameters:

branch
An arbitrary string. Used as the branch name stored in the product.id and media.cfg files on the ISO.
If not specified, the branch name stored in the product.id file in the master software repository will be used.
media
An arbitrary string. Only used for constructing the Installer ISO name.
product
An arbitrary string. Used as the product name stored in the product.id file on the ISO.
If not specified, the product name stored in the product.id file in the master software repository will be used.
type
An arbitrary string. Used as the type value stored in the product.id file on the ISO.
If not specified, the type value stored in the product.id file in the master software repository will be used.
version
An arbitrary string. Used as the version number stored in the product.id and media.cfg files on the ISO.
If not specified, the version number stored in the product.id file in the master software repository will be used.
workdir
The path to the base working directory for drakclassic. All files created by drakclassic will be stored in a subdirectory (named as the Installer ISO name) below this directory.
If not specified, the current working directory will be used.

User settings

The user can add additional parameters in the basic settings file for use within the build configuration file. drakclassic will ignore these parameters.

Overriding settings

A setting can be overridden (or added) by using the --define <name>=<value> command line option.

Build configuration

The build configuration file specifies all aspects of the Installer ISO composition. The name and location of this file can be specified by the --config command line option. If not specified, the default is <config-dir>/config/build.cfg.

Syntax

The build configuration is composed from the following basic data types:

number
any sequence of decimal digits
string
any sequence of characters enclosed in either single or double quotes. If enclosed in single quotes, the enclosed string is used exactly as written. If enclosed in double quotes, certain characters have special meaning, as described below.
array
any sequence of elements separated by commas and enclosed in square brackets, e.g. ['a','b','c']. Any amount of white space may be added between the elements and the punctuation. Elements may be of any data type. Occasionally arrays are used to hold pairs of values, in which case the '=>' digraph may be used to separate the two elements in each pair instead of a comma.
associative array
any sequence of key/value pairs separated by commas and enclosed in curly brackets, with the key and value separated by the '=>' digraph, e.g. {a=>1,b=>2} . Any amount of white space may be added between the keys and values and the punctuation. Keys should be simple alpha-numeric identifiers (i.e. contain no white space). Values may be of any data type.

A '#' character outside a string starts a comment. It and all subsequent characters on the same line are ignored.

Readers familiar with Perl will have already realized that the build configuration file uses Perl syntax. The file may, in fact, contain any Perl constructs; the only restriction being that the associative array describing the build configuration is the last item in the file.

Double-quoted strings are therefore interpreted according to Perl rules. As well as the usual escape sequences common to most programming languages (e.g. "\n" for a new line), any Perl variable will be expanded to the variable value. See the Perl language documentation for more details.

Note:
In the following sections, a configuration key in curly brackets (e.g. {system}{vga_mode}) is used as shorthand for the configuration value.

Keys

The complete build configuration is an associative array which may contain the following keys:

urpmi_media (required)
An associative array containing the configuration values used to select which urpmi media in the master software repository are enabled for use during the Media step. It may contain the following keys:
enabled_sections (required)
An array specifying the sections within the master software repository that are to be enabled when selecting packages to include in the installer software repository. Each element of the array should be a string specifying a media directory, e.g. 'core', 'nonfree'.
enabled_subsections (required)
An array specifying the subsections within the master software repository that are to be enabled when selecting packages to include in the installer software repository. Each element of the array should be a string specifying a media subdirectory, e.g. 'release', 'updates'.
media_cfg (required)
An associative array containing the configuration values used to set flags in the installer software repositiory media.cfg file generated during the Media step. It may contain the following keys:
askmedia (required)
A number specifying the value of the ask_media flag in the media.cfg file.
suppl (required)
A number specifying the value of the suppl flag in the media.cfg file.
group_include_lists (required)
An array specifying a list of files that specify groups of packages that should be included in the installer software repository. Each element of the array should be a string specifying the path to a file. A relative path will be taken as relative to <config-dir>. See Package selection for details about the contents of these files and how they are used.
package_include_lists (optional)
An array specifying a list of files that specify additional packages that should be included in the installer software repository. Each element of the array should be a string specifying the path to a file. A relative path will be taken as relative to <config-dir>. See Package selection for details about the contents of these files and how they are used.
package_exclude_lists (optional)
An array specifying a list of files that specify packages that should be excluded from the installer software repository. Each element of the array should be a string specifying the path to a file. A relative path will be taken as relative to <config-dir>. See Package selection for details about the contents of these files and how they are used.
biarch_packages (optional)
An array specifying a list of package names for which both the 32-bit and 64-bit version of the package should be included in the installer software repository.
system (optional)
An associative array containing the configuration values used to customize the installer system. It may contain the following keys:
vga_mode (optional)
A number specifying the vga mode that should be passed on the boot command line when the installer is booted. If specified, vga={system}{vga_mode} will be appended to the command line in every boot menu entry.
media (required)
An associative array containing the configuration values used when preparing the bootloader files during the Boot step and when creating the final ISO image during the Master step. It may contain the following keys:
label (required)
A string specifying the volume label for the ISO image.
bootloader_title (optional)
A string specifying the title line for the bootloader screen.
If not specified, {media}{label} will be used, with any '-' characters in the label replaced by spaces.
bootloader_theme (optional)
A string specifying the path to a directory containing the theme files to be used by the bootloader. A relative path will be taken as relative to <config-dir>.
If not specified, /boot/grub2/themes/maggy will be used if it is present on the build system, otherwise, no bootloader theme will be included in the Installer ISO.
bootloader_font (optional)
A string specifying the path to a file containing the default bootloader font. This should be a GRUB2 (.pf2) font file. A relative path will be taken as relative to <config-dir>.
If not specified, /usr/share/grub/unicode.pf2 will be used if it is present on the build system, otherwise, no default bootloader font will be included in the Installer ISO and the bootloader will fall back to text mode.
bootloader_langs (optional)
A string specifying the path to a file containing the list of languages to be included in the bootloader language selection menu. A relative path will be taken as relative to <config-dir>.
If not specified, the language selection menu will not be included in the bootloader.
bootloader_kbds (optional)
A string specifying the path to a file containing the list of keyboard types to be included in the bootloader keyboard selection menu . A relative path will be taken as relative to <config-dir>.
If not specified, the keyboard selection menu will not be included in the bootloader.
bootloader_messages (optional)
A string specifying the path to a directory containing message translations for the bootloader. Only compiled translation (.mo) files will be included in the Installer ISO.
bootloader_default (optional)
A number specifying the bootloader menu entry that will be selected by default. Entries are numbered starting from zero.
If not specified, the first bootloader menu entry will be the default.
bootloader_timeout (optional)
A number specifying the delay in seconds before the bootloader automatically boots from the default entry.
If not specified, the delay will be 4 seconds.
bootloader_entries (optional)
An array of paired values specifying the bootloader menu entries. The first element in each pair should be a string specifying the menu entry title. The second element in each pair should be an associative array containing the following keys:

command (optional)

A string specifying the GRUB2 command that will be executed when the menu entry is selected. This should either be 'linux' or 'linux16'.
If not specified, the linux command will be used.

image (optional)

A string specifying the path to the kernel image that will be used for this menu entry.
If not specified, /boot/vmlinuz will be used, which is the kernel copied from the dummy root filesystem during the Boot step.

initrd (optional)

A string specifying the path to the initial RAM disk image that will be used for this menu entry. If not specified, /boot/initrd.gz will be used, which is the initial RAM disk image created during the Boot step. The special value 'none' may be used to indicate that there is no initial RAM disk image for this menu entry.

append (optional)

A string specifying additional options to append to the boot command line for this menu entry. Any options that are automatically added by drakclassic will be added before this string.
mbr_boot_img (optional)
A string specifying the path to the GRUB2 MBR bootloader image for hybrid boot. A relative path will be taken as relative to <config-dir>.
If not specified, /usr/lib/grub/i386-pc/boot_hybrid.img will be used if it exists on the build system, otherwise drakclassic will terminate with an error.
eltorito_img (optional)
A string specifying the path to the GRUB2 El Torito bootloader image. A relative path will be taken as relative to <config-dir>.
If not specified, drakclassic will use grub2-mkimage to build the El Torito bootloader image.
iso_part_start (optional)
A number specifying the starting sector for the hybrid ISO protective partition that protects the iso9660 filesystem. This should either be 0 or 1. The option of starting at sector 1 is provided for compatibility with some old BIOSs.
If not specified, the protective partition will start at sector 0.
iso_part_type (optional)
A string specifying the partition type for the hybrid ISO protective partition that protects the iso9660 filesystem. This should be a two-digit hexadecimal number in 'C' format, e.g. '0x00'.
If not specified, the protective partition type will be set to '0x00'.
efi_type (optional)
A string specifying the EFI boot type(s) to be supported. This should be one of 'none', '32bit', '64bit', or 'all'.
If not specified, the default is 'none'.
boot32_efi (optional)
A string specifying the path to the GRUB2 32-bit EFI bootloader image. A relative path will be taken as relative to <config-dir>.
If not specified, drakclassic will use grub2-mkimage to build the 32-bit EFI bootloader image if it is required (this requires the 32-bit grub2-efi package to be installed on the build system).
This key is ignored if the EFI boot type is set to 'none' or '64bit'.
boot64_efi (optional)
A string specifying the path to the GRUB2 64-bit EFI bootloader image. A relative path will be taken as relative to <config-dir>.
If not specified, drakclassic will use grub2-mkimage to build the 64-bit EFI bootloader image if it is required (this requires the 64-bit grub2-efi package to be installed on the build system).
This key is ignored if the EFI boot type is set to 'none' or '32bit'.
copy_from_repo (optional)
An array of paired values specifying a list of files or directories to be copied from the repository to the ISO image filesystem. The first element in each pair should be a string specifying the path to the file or directory to be copied (relative to the <arch> directory in the repository). The second element in each pair should be a string specifying the path to the file or directory in the ISO image filesystem (relative to the root of the filesystem). Intermediate directories in the ISO image filesystem will be automatically created as required.
If <repository> is a FTP or HTTP URL, the list may only contain files, not directories.
checksums (optional)
An array specifying a list of checksum types that should be calculated from and stored alongside the ISO image file. Each element of the array should be a string specifying a checksum type. Recognised types are:
  • 'md5' - a 128-bit MD5 checksum, stored in a file with the extension .md5
  • 'sha1' - a 160-bit SHA-1 checksum, stored in a file with the extension .sha1
  • 'sha2' - a 512-bit SHA-2 checksum, stored in a file with the extension .sha512
  • 'sha3' - a 512-bit SHA-3 checksum, stored in a file with the extension .sha3
If not specified, no checksums will be generated.
iso_name_fields (optional)
An array specifying the settings values used to construct the Installer ISO name, which is used both to name the working subdirectory and as the base name for the ISO image file and associated checksum files. Each element of the array should be a string specifying the name of one setting. The settings values will be separated by '-' characters when constructing the Installer ISO name.
If not specified, the default name for the Installer ISO is <distro>-<release>-<arch>-<media>. Null settings are skipped.

Using settings

Before reading the build configuration file, drakclassic will read the basic settings file and store the settings in an associative array contained within an object that is stored in the global $build variable. This allows the settings to be used in the build configuration file. For example, the arch setting can be obtained by $build->{settings}{arch}. Shortcuts can be created by declaring local variables, e.g.

my $arch = $build->{settings}{arch};

which can then be used within double-quoted strings.

Useful Perl functions

A useful shortcut is the Perl built-in qw() function. This converts a sequence of plain words into a comma-separated list of quoted strings, e.g.

qw(a b c)

is equivalent to

'a', 'b', 'c'

Before reading the build configuration file, drakclassic imports the MDK::Common Perl library, so the build configuration file may use any function exported by this library. A useful function is if_(), which allows items to be conditionally included in a list. So for example, if the local variable $arch is set to x86_64

'a', 'b', if_($arch eq 'x86_64', 'c', 'd')

is equivalent to

'a', 'b', 'c', 'd'

otherwise, it is equivalent to

'a', 'b'

Syntax checking

Because the build configuration file uses Perl syntax, the Perl interpreter can be used to check that there are no syntax errors in the file before running drakclassic. Just run

perl -qw <file>

(where <file> is the path to the file). To avoid a spurious warning, you need to assign the top-level associative array to a variable, e.g.

my $config = { ... };

Package selection

Package group lists

The files specified by the user in {group_include_lists} should be plain text files. Each line of these files should either be:

1. A rpmsrate category name (e.g CAT_X) followed by a threshold value (from 1 to 5), separated by white space and optionally followed by a comment.

2. A 'task' meta-package name (e.g. task-x11), optionally followed by a comment.

3. A blank or comment line.

A comment starts with a '#' character and continues to the end of the line. Additional white space will be ignored.

Package lists

The files specified by the user in {package_include_lists} and {package_exclude_lists} should be plain text files. Each line of these files should either be:

1. A package name (e.g x11-server), optionally preceded by an architecture (e.g. i586), separated by a ':' character, and optionally followed by a comment. The package name may include simple wildcards ('?' and '*').

2. A blank or comment line.

A comment starts with a '#' character and continues to the end of the line. Additional white space will be ignored.

Selection process

The packages contained in the installer software repository are selected as follows:

1. The files specified by the user in {group_include_lists} are read in turn. For each category name, all packages tagged with that category in the rpmsrate file with a rating greater than or equal to the specified threshold value are added to the list of selected packages. For each meta-package name, that meta-package is added to the list of selected packages.

2. The files specified by the user in {package_exclude_lists} are read in turn. For each package name (after expanding wildcards), that package will be removed from the list of selected packages (if present).

3. All packages recursively required by the current list of selected packages will be added to the list (if not already present), and marked as implicitly selected,

4. The files specified by the user in {package_include_lists} are read in turn. For each package name (after expanding wildcards), that package will be added to the list of selected packages.

5. All implicitly selected packages will be removed from the list of selected packages.

6. All packages recursively required by the current list of selected packages will be added to the list (if not already present), and marked as implicitly selected,

7. The files specified by the user in {package_exclude_lists} are again read in turn. For each package name (after expanding wildcards), that package will be removed from the list of selected packages (if present).

8. All implicitly selected packages will be removed from the list of selected packages.

9. All packages recursively required by the current list of selected packages will be added to the list (if not already present).

Note:
When adding dependencies, all alternatives are included.

Bootloader menus

Main menu

This menu will present the items specified by the user in {media}{bootloader_entries}. If the user has specified a {media}{bootloader_langs} file, this will then be followed by a menu entry that selects the language selection menu. If the user has specified a {media}{bootloader_kbds} file, this will then be followed by a menu entry that selects the keyboard selection menu.

Language selection menu

This menu will present the list of languages specified by the {media}{bootloader_langs} file. The file should contain an array of paired values, using the same syntax as the build configuration file except that the array is enclosed in round brackets instead of square brackets. The first element in each pair should be a string specifying the language code (e.g. 'en_US'). The second element in each pair should be a string specifying the displayed name of the language. If the file is UTF-8 coded, precede the array with the line

use utf8;

See /usr/share/drakiso/bootloader/lang-names.txt for an example.

When an entry is selected in this menu, the bootloader lang environment variable will be set to the selected language code, enabling the bootloader menus to be translated if the necessary translations have been provided in the {media}{bootloader_messages} directory.

When an ordinary entry in the main menu is selected, the bootloader will add a lang=<language code> option to the boot command line to pass the most recently selected language code to the live system.

Keyboard selection menu

This menu will present the list of keyboards specified by the {media}{bootloader_kbds} file. The file should contain an array of paired values, using the same syntax as the build configuration file except that the array is enclosed in round brackets instead of square brackets. The first element in each pair should be a string specifying the keyboard code (e.g. 'en'). The second element in each pair should be a string specifying the displayed name of the keyboard. If the file is UTF-8 coded, precede the array with the line

use utf8;
;

See /usr/share/drakiso/bootloader/kbd-names.txt for an example.

When an ordinary entry in the main menu is selected, the bootloader will add a kbd=<keyboard code> option to the boot command line to pass the most recently selected keyboard code to the live system.

If a file named lang-kbds.txt exists in the same directory as the {media}{bootloader_langs} file, the lang-kbds.txt file will be used to determine the default entry in the keyboard selection menu, once a language has been selected. The file should contain an associative array where the keys are the language codes and the associated values are the default keyboard codes.

See /usr/share/drakiso/bootloader/lang-kbds.txt for an example.

Note:
It was intended that the keyboard selection menu would also be used to change the keyboard mapping in the bootloader, but GRUB2 does not provide a reliable way to do this.

Translations

All text in the main menu and keyboard selection menu is translatable. The language names in the language selection menu are not translatable - it is assumed each language name will be provided in its native form in the {media}{bootloader_langs} file.