Appendix A. Kickstart script file format reference
This reference describes in detail the kickstart file format.
A.1. Kickstart file format
Kickstart scripts are plain text files that contain keywords recognized by the installation program, which serve as directions for the installation. Any text editor able to save files as ASCII text, such as Gedit
or vim
on Linux systems or Notepad
on Windows systems, can be used to create and edit Kickstart files. The file name of your Kickstart configuration does not matter; however, it is recommended to use a simple name as you will need to specify this name later in other configuration files or dialogs.
- Commands
- Commands are keywords that serve as directions for installation. Each command must be on a single line. Commands can take options. Specifying commands and options is similar to using Linux commands in a shell.
- Sections
-
Certain special commands that begin with the percent
%
character start a section. Interpretation of commands in sections is different from commands placed outside sections. Every section must be finished with the%end
command. - Section types
The available sections are:
-
Add-on sections. These sections use the
%addon addon_name
command. -
Package selection sections. Start with
%packages
. Use it to list packages for installation, including indirect means such as package groups or modules. -
Script sections. These start with
%pre
,%pre-install
,%post
, and%onerror
. These sections are not required.
-
Add-on sections. These sections use the
- Command section
-
The command section is a term used for the commands in the Kickstart file that are not part of any script section or
%packages
section. - Script section count and ordering
-
All sections except the command section are optional and can be present multiple times. When a particular type of script section is to be evaluated, all sections of that type present in the Kickstart are evaluated in order of appearance: two
%post
sections are evaluated one after another, in the order as they appear. However, you do not have to specify the various types of script sections in any order: it does not matter if there are%post
sections before%pre
sections. - Comments
-
Kickstart comments are lines starting with the hash
#
character. These lines are ignored by the installation program.
Items that are not required can be omitted. Omitting any required item results in the installation program changing to the interactive mode so that the user can provide an answer to the related item, just as during a regular interactive installation. It is also possible to declare the kickstart script as non-interactive with the cmdline
command. In non-interactive mode, any missing answer aborts the installation process.
If user interaction is needed during kickstart installation in text or graphical mode, enter only the windows where updates are mandatory to complete the installation. Entering spokes might lead to resetting the kickstart configuration. Resetting of the configuration applies specifically to the kickstart commands related to storage after entering the Installation Destination window.
A.2. Package selection in Kickstart
Kickstart uses sections started by the %packages
command for selecting packages to install. You can install packages, groups, environments, module streams, and module profiles this way.
A.2.1. Package selection section
Use the %packages
command to begin a Kickstart section which describes the software packages to be installed. The %packages
section must end with the %end
command.
You can specify packages by environment, group, module stream, module profile, or by their package names. Several environments and groups that contain related packages are defined. See the repository/repodata/*-comps-repository.architecture.xml
file on the Red Hat Enterprise Linux 10 Installation DVD for a list of environments and groups.
The *-comps-repository.architecture.xml
file contains a structure describing available environments (marked by the <environment>
tag) and groups (the <group>
tag). Each entry has an ID, user visibility value, name, description, and package list. If the group is selected for installation, the packages marked mandatory
in the package list are always installed, the packages marked default
are installed if they are not specifically excluded elsewhere, and the packages marked optional
must be specifically included elsewhere even when the group is selected.
You can specify a package group or environment by using either its ID (the <id>
tag) or name (the <name>
tag).
If you are not sure what package should be installed, Red Hat recommends you to select the Minimal Install environment. Minimal Install provides only the packages which are essential for running Red Hat Enterprise Linux 10. This will substantially reduce the chance of the system being affected by a vulnerability. If necessary, additional packages can be added later after the installation. For more details on Minimal Install, see the Installing the Minimum Amount of Packages Required section of the Security Hardening document. The Initial Setup can not run after a system is installed from a Kickstart file unless a desktop environment and the X Window System were included in the installation and graphical login was enabled.
To install a 32-bit package on a 64-bit system:
-
specify the
--multilib
option for the%packages
section -
append the package name with the 32-bit architecture for which the package was built; for example,
glibc.i686
A.2.2. Package selection commands
You can use the following commands within the %packages
section of a Kickstart file.
- Specifying an environment
Specify an entire environment to be installed as a line starting with the
@^
symbols:%packages @^Infrastructure Server %end
This installs all packages which are part of the
Infrastructure Server
environment. All available environments are described in therepository/repodata/*-comps-repository.architecture.xml
file on the Red Hat Enterprise Linux 10 Installation DVD.Only a single environment should be specified in the Kickstart file. If more environments are specified, only the last specified environment is used.
- Specifying groups
Specify groups, one entry to a line, starting with an
@
symbol, and then the full group name or group id as given in the*-comps-repository.architecture.xml
file. For example:%packages @X Window System @Desktop @Sound and Video %end
The
Core
group is always selected - it is not necessary to specify it in the%packages
section.- Specifying individual packages
Specify individual packages by name, one entry to a line. You can use the asterisk character (
*
) as a wildcard in package names. For example:%packages sqlite curl aspell docbook* %end
The
docbook*
entry includes the packagesdocbook-dtds
anddocbook-style
that match the pattern represented with the wildcard.- Specifying profiles of module streams
Specify profiles for module streams, one entry to a line, using the syntax for profiles:
%packages @module:stream/profile %end
This installs all packages listed in the specified profile of the module stream.
- When a module has a default stream specified, you can leave it out. When the default stream is not specified, you must specify it.
- When a module stream has a default profile specified, you can leave it out. When the default profile is not specified, you must specify it.
- Installing a module multiple times with different streams is not possible.
- Installing multiple profiles of the same module and stream is possible.
Modules and groups use the same syntax starting with the
@
symbol. When a module and a package group exist with the same name, the module takes precedence.In Red Hat Enterprise Linux 10, modules are present only in the AppStream repository. To list available modules, use the
dnf module list
command on an installed Red Hat Enterprise Linux 10 system.It is also possible to enable module streams using the
module
Kickstart command and then install packages contained in the module stream by naming them directly.- Excluding environments, groups, or packages
Use a leading dash (
-
) to specify packages or groups to exclude from the installation. For example:%packages -@Graphical Administration Tools -autofs -ipa*compat %end
Installing all available packages using only *
in a Kickstart file is not supported.
You can change the default behavior of the %packages
section by using several options. Some options work for the entire package selection, others are used with only specific groups.
Additional resources
A.2.3. Common package selection options
You can use the following options in the %packages
sections. To use an option, append it to the start of the package selection section. For example:
%packages --multilib --ignoremissing
--default
- Install the default set of packages. This corresponds to the package set which would be installed if no other selections were made in the Package Selection screen during an interactive installation.
--excludedocs
-
Do not install any documentation contained within packages. In most cases, this excludes any files normally installed in the
/usr/share/doc
directory, but the specific files to be excluded depend on individual packages. --ignoremissing
- Ignore any packages, groups, module streams, module profiles, and environments missing in the installation source, instead of halting the installation to ask if the installation should be aborted or continued.
--inst-langs
- Specify a list of languages to install. This is different from package group level selections. This option does not describe which package groups should be installed; instead, it sets RPM macros controlling which translation files from individual packages should be installed.
--multilib
Configure the installed system for multilib packages, to allow installing 32-bit packages on a 64-bit system, and install packages specified in this section as such.
Normally, on an AMD64 and Intel 64 system, you can install only the x86_64 and the noarch packages. However, with the --multilib option, you can automatically install the 32-bit AMD and the i686 Intel system packages available, if any.
This only applies to packages explicitly specified in the
%packages
section. Packages which are only being installed as dependencies without being specified in the Kickstart file are only installed in architecture versions in which they are needed, even if they are available for more architectures.You can configure Anaconda to install packages in
multilib
mode during the installation of the system. Use one of the following options to enablemultilib
mode:Configure Kickstart file with the following lines:
%packages --multilib --default %end
- Add the inst.multilib boot option during booting the installation image.
--nocore
Disables installation of the
@Core
package group which is otherwise always installed by default. Disabling the@Core
package group with--nocore
should be only used for creating lightweight containers; installing a desktop or server system with--nocore
will result in an unusable system.Notes-
Using
-@Core
to exclude packages in the@Core
package group does not work. The only way to exclude the@Core
package group is with the--nocore
option. -
The
@Core
package group is defined as a minimal set of packages needed for installing a working system. It is not related in any way to core packages as defined in the Package Manifest and Scope of Coverage Details.
-
Using
--exclude-weakdeps
- Disables installation of packages from weak dependencies. These are packages linked to the selected package set by Recommends and Supplements flags. By default weak dependencies will be installed.
--retries=
- Sets the number of times {PackageManagerName} will attempt to download packages (retries). The default value is 10. This option only applies during the installation, and will not affect {PackageManagerName} configuration on the installed system.
--timeout=
- Sets the {PackageManagerName} timeout in seconds. The default value is 30. This option only applies during the installation, and will not affect {PackageManagerName} configuration on the installed system.
A.2.4. Options for specific package groups
The options in this list only apply to a single package group. Instead of using them at the %packages
command in the Kickstart file, append them to the group name. For example:
%packages @Graphical Administration Tools --optional %end
--nodefaults
- Only install the group’s mandatory packages, not the default selections.
--optional
Install packages marked as optional in the group definition in the
*-comps-repository.architecture.xml
file, in addition to installing the default selections.Some package groups, such as
Scientific Support
, do not have any mandatory or default packages specified - only optional packages. In this case the--optional
option must always be used, otherwise no packages from this group will be installed.
The --nodefaults
and --optional
options cannot be used together. You can install only mandatory packages during the installation using --nodefaults
and install the optional packages on the installed system post installation.
A.2.5. Installing Kernel-64k on ARM using Kickstart
RHEL offers the ARM64 hardware architecture to support workloads that require large physical memory configuration for optimal performance. Such large memory configuration requires the use of a large MMU page size (64k).
While installing RHEL, you can select the kernel-64k
package to install with a kernel supporting 64k page size.
Procedure
In the
%packages
section of the kickstart file, add the following list of packages:%packages kernel-64k -kmod-kvdo -vdo -kernel %end
Verification
To verify the page size, after installation is completed and the system is rebooted, open the terminal and run:
$ getconf PAGESIZE 65536
The output
65536
indicates that the 64k kernel is in use.To verify that the swap partition is enabled, enter:
$ free total used free shared buff/cache available Mem: 35756352 3677184 34774848 25792 237120 32079168 Swap: 6504384 0 6504384
The total and free columns are non-zero, which indicates the swap is enabled successfully.
A.3. Scripts in Kickstart file
A kickstart file can include the following scripts:
-
%pre
-
%pre-install
-
%post
This section provides the following details about the scripts:
- Execution time
- Types of commands that can be included in the script
- Purpose of the script
- Script options
A.3.1. %pre script
The %pre
scripts are run on the system immediately after the Kickstart file has been loaded, but before it is completely parsed and installation begins. Each of these sections must start with %pre
and end with %end
.
The %pre
script can be used for activation and configuration of networking and storage devices. It is also possible to run scripts by using interpreters available in the installation environment. Adding a %pre
script can be useful if you have networking and storage that needs special configuration before proceeding with the installation, or have a script that, for example, sets up additional logging parameters or environment variables.
Debugging problems with %pre
scripts can be difficult, so it is recommended only to use a %pre
script when necessary.
The %pre
section of Kickstart is executed at the stage of installation which happens after the installer image (inst.stage2
) is fetched: it means after root switches to the installer environment (the installer image) and after the Anaconda
installer itself starts. Then the configuration in %pre
is applied and can be used to fetch packages from installation repositories configured, for example, by URL in Kickstart. However, it cannot be used to configure the network to fetch the image (inst.stage2
) from the network.
Commands related to networking, storage, and file systems are available to use in the %pre
script, in addition to most of the utilities in the installation environment /sbin
and /bin
directories.
You can access the network in the %pre
section. However, the name service has not been configured at this point, so only IP addresses work, not URLs.
The pre script does not run in the chroot environment.
A.3.1.1. %pre script section options
The following options can be used to change the behavior of pre-installation scripts. To use an option, append it to the %pre
line at the beginning of the script. For example:
%pre --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end
--interpreter=
Allows you to specify a different scripting language, such as Python. Any scripting language available on the system can be used; in most cases, these are
/usr/bin/sh
,/usr/bin/bash
, and/usr/libexec/platform-python
.Note that the
platform-python
interpreter uses Python version 3.6. You must change your Python scripts from previous RHEL versions for the new path and version. Additionally,platform-python
is meant for system tools: Use thepython36
package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python--erroronfail
-
Displays an error and halts the installation if the script fails. The error message will direct you to where the cause of the failure is logged. The installed system might get into an unstable and unbootable state. You can use the
inst.nokill
option to debug the script. --log=
Logs the script’s output into the specified log file. For example:
%pre --log=/tmp/ks-pre.log
A.3.2. %pre-install script
The commands in the pre-install
script are run after the following tasks are complete:
- System is partitioned
- Filesystems are created and mounted under /mnt/sysroot
- Network has been configured according to any boot options and kickstart commands
Each of the %pre-install
sections must start with %pre-install
and end with %end
.
The %pre-install
scripts can be used to modify the installation, and to add users and groups with guaranteed IDs before package installation.
It is recommended to use the %post
scripts for any modifications required in the installation. Use the %pre-install
script only if the %post
script falls short for the required modifications.
The pre-install
script does not run in the chroot environment.
A.3.2.1. %pre-install script section options
The following options can be used to change the behavior of pre-install
scripts. To use an option, append it to the %pre-install
line at the beginning of the script. For example:
%pre-install --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end
You can have multiple %pre-install
sections, with same or different interpreters. They are evaluated in their order of appearance in the Kickstart file.
--interpreter=
Allows you to specify a different scripting language, such as Python. Any scripting language available on the system can be used; in most cases, these are
/usr/bin/sh
,/usr/bin/bash
, and/usr/libexec/platform-python
.The
platform-python
interpreter uses Python version 3.6. You must change your Python scripts from previous RHEL versions for the new path and version. Additionally,platform-python
is meant for system tools: Use thepython36
package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python.--erroronfail
-
Displays an error and halts the installation if the script fails. The error message will direct you to where the cause of the failure is logged. The installed system might get into an unstable and unbootable state. You can use the
inst.nokill
option to debug the script. --log=
Logs the script’s output into the specified log file. For example:
%pre-install --log=/mnt/sysroot/root/ks-pre.log
A.3.3. %post script
The %post script is a post-installation script that is run after the installation is complete, but before the system is rebooted for the first time. You can use this section to run tasks such as system subscription.
You have the option of adding commands to run on the system once the installation is complete, but before the system is rebooted for the first time. This section must start with %post
and end with %end
.
The %post
section is useful for functions such as installing additional software or configuring an additional name server. The post-install script is run in a chroot
environment, therefore, performing tasks such as copying scripts or RPM packages from the installation media do not work by default. You can change this behavior by using the --nochroot
option as described below. Then the %post
script will run in the installation environment, not in chroot
on the installed target system.
Because the post-install script runs in a chroot
environment, most systemctl
commands will refuse to perform any action.
During execution of the %post
section, the installation media must be still inserted.
A.3.3.1. %post script section options
The following options can be used to change the behavior of post-installation scripts. To use an option, append it to the %post
line at the beginning of the script. For example:
%post --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end
--interpreter=
Allows you to specify a different scripting language, such as Python. For example:
%post --interpreter=/usr/libexec/platform-python
Any scripting language available on the system can be used; in most cases, these are
/usr/bin/sh
,/usr/bin/bash
, and/usr/libexec/platform-python
.The
platform-python
interpreter uses Python version 3.6. You must change your Python scripts from previous RHEL versions for the new path and version. Additionally,platform-python
is meant for system tools: Use thepython36
package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python in Installing and using dynamic programming languages.--nochroot
Allows you to specify commands that you would like to run outside of the chroot environment.
The following example copies the file /etc/resolv.conf to the file system that was just installed.
%post --nochroot cp /etc/resolv.conf /mnt/sysroot/etc/resolv.conf %end
--erroronfail
-
Displays an error and halts the installation if the script fails. The error message will direct you to where the cause of the failure is logged. The installed system might get into an unstable and unbootable state. You can use the
inst.nokill
option to debug the script. --log=
Logs the script’s output into the specified log file. The path of the log file must take into account whether or not you use the
--nochroot
option. For example, without--nochroot
:%post --log=/root/ks-post.log
and with
--nochroot
:%post --nochroot --log=/mnt/sysroot/root/ks-post.log
A.3.3.2. Example: Mounting NFS in a post-install script
This example of a %post
section mounts an NFS share and executes a script named runme
located at /usr/new-machines/
on the share. The NFS file locking is not supported while in Kickstart mode, therefore the -o nolock
option is required.
# Start of the %post section with logging into /root/ks-post.log %post --log=/root/ks-post.log # Mount an NFS share mkdir /mnt/temp mount -o nolock 10.10.0.2:/usr/new-machines /mnt/temp openvt -s -w -- /mnt/temp/runme umount /mnt/temp # End of the %post section %end
A.4. Kickstart error handling section
Starting with Red Hat Enterprise Linux 7, Kickstart installations run custom scripts when any fatal error encounters in the installation program. Example scenarios include an error in a package that has been requested for installation or an error while scanning storage devices. In case of such events, installation aborts. To analyze these events, the installation program runs all %onerror
scripts chronologically as provided in the Kickstart file. In the event of traceback, you can run the %onerror
scripts.
Each %onerror
script is required to end with %end
.
You can enforce the error handler for any error by using inst.cmdline
to make every error a fatal error.
Error handling sections accept the following options:
--erroronfail
-
Displays an error and halts the installation if the script fails. The error message will direct you to where the cause of the failure is logged. The installed system might get into an unstable and unbootable state. You can use the
inst.nokill
option to debug the script. --interpreter=
Allows you to specify a different scripting language, such as Python. For example:
%onerror --interpreter=/usr/libexec/platform-python
Any scripting language available on the system can be used; in most cases, these are
/usr/bin/sh
,/usr/bin/bash
, and/usr/libexec/platform-python
.The
platform-python
interpreter uses Python version 3.6. You must change your Python scripts from previous RHEL versions for the new path and version. Additionally,platform-python
is meant for system tools: Use thepython36
package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python.--log=
- Logs the script’s output into the specified log file.
A.5. Kickstart add-on sections
Starting with Red Hat Enterprise Linux 7, Kickstart installations support add-ons. These add-ons can expand the basic Kickstart (and Anaconda) functionality in many ways.
To use an add-on in your Kickstart file, use the %addon addon_name options
command, and finish the command with an %end
statement, similar to pre-installation and post-installation script sections. For example, if you want to use the Kdump add-on, which is distributed with Anaconda by default, use the following commands:
%addon com_redhat_kdump --enable --reserve-mb=auto %end
The %addon
command does not include any options of its own - all options are dependent on the actual add-on.