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
- 1 Origins
- 2 Quickstart
- 3 In more detail
- 4 ISO composition
- 4.1 Basic settings
- 4.2 Build configuration
- 4.2.1 Syntax
- 4.2.2 Keys
- 4.2.2.1 urpmi_media (required)
- 4.2.2.2 media_cfg (required)
- 4.2.2.3 group_include_lists (required)
- 4.2.2.4 package_include_lists (optional)
- 4.2.2.5 package_exclude_lists (optional)
- 4.2.2.6 biarch_packages (optional)
- 4.2.2.7 system (optional)
- 4.2.2.8 media (required)
- 4.2.2.8.1 label (required)
- 4.2.2.8.2 bootloader_title (optional)
- 4.2.2.8.3 bootloader_theme (optional)
- 4.2.2.8.4 bootloader_font (optional)
- 4.2.2.8.5 bootloader_langs (optional)
- 4.2.2.8.6 bootloader_kbds (optional)
- 4.2.2.8.7 bootloader_messages (optional)
- 4.2.2.8.8 bootloader_default (optional)
- 4.2.2.8.9 bootloader_timeout (optional)
- 4.2.2.8.10 bootloader_entries (optional)
- 4.2.2.8.11 mbr_boot_img (optional)
- 4.2.2.8.12 eltorito_img (optional)
- 4.2.2.8.13 iso_part_start (optional)
- 4.2.2.8.14 iso_part_type (optional)
- 4.2.2.8.15 efi_type (optional)
- 4.2.2.8.16 boot32_efi (optional)
- 4.2.2.8.17 boot64_efi (optional)
- 4.2.2.8.18 copy_from_repo (optional)
- 4.2.2.8.19 checksums (optional)
- 4.2.2.9 iso_name_fields (optional)
- 4.2.3 Using settings
- 4.2.4 Useful Perl functions
- 4.2.5 Syntax checking
- 5 Package selection
- 6 Bootloader menus
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
- eitheri586
orx86_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 bydrakclassic
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 theproduct.id
andpackage.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
andx86_64
.
distro
- An arbitrary string. Used as the
distribution
name stored in theproduct.id
file on the ISO and for constructing the Installer ISO name.
release
- An arbitrary string. Used as the
release
identifier stored in theproduct.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 theproduct.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 theproduct.id
andmedia.cfg
files on the ISO.
- If not specified, the
branch
name stored in theproduct.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 theproduct.id
file on the ISO.
- If not specified, the
product
name stored in theproduct.id
file in the master software repository will be used.
type
- An arbitrary string. Used as the
type
value stored in theproduct.id
file on the ISO.
- If not specified, the
type
value stored in theproduct.id
file in the master software repository will be used.
version
- An arbitrary string. Used as the
version
number stored in theproduct.id
andmedia.cfg
files on the ISO.
- If not specified, the
version
number stored in theproduct.id
file in the master software repository will be used.
workdir
- The path to the base working directory for
drakclassic
. All files created bydrakclassic
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 themedia.cfg
file.
suppl
(required)
- A number specifying the value of the
suppl
flag in themedia.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, otherwisedrakclassic
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 usegrub2-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
or1
. 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 usegrub2-mkimage
to build the 32-bit EFI bootloader image if it is required (this requires the 32-bitgrub2-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 usegrub2-mkimage
to build the 64-bit EFI bootloader image if it is required (this requires the 64-bitgrub2-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. |
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.
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.
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.