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 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 %end command.
Section types

The available sections are:

  • Add-on sections. These sections use the %addon addon_name command.
  • Package selection sections. Starts 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.
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.

Note

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 8 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 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 8. 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. Note that 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.

Important

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

These commands can be used 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 the repository/repodata/*-comps-repository.architecture.xml file on the Red Hat Enterprise Linux 8 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 packages docbook-dtds and docbook-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 8, modules are present only in the AppStream repository. To list available modules, use the yum module list command on an installed Red Hat Enterprise Linux 8 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
Important

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.

A.2.3. Common package selection options

The following options are available for 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.
--instLangs=
Specify a list of languages to install. Note that 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.

User can configure Anaconda to install packages in multilib mode during the installation of the system. Use one of the following options to enable multilib mode:

  1. Configure Kickstart file with the following lines:

    %packages --multilib --default
    %end
  2. 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.
--excludeWeakdeps
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 YUM will attempt to download packages (retries). The default value is 10. This option only applies during the installation, and will not affect YUM configuration on the installed system.
--timeout=
Sets the YUM timeout in seconds. The default value is 30. This option only applies during the installation, and will not affect YUM 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.

Note that 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.

Important

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.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, 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.

Important

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 network to fetch the image (inst.stage2) from 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.

Note

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 the python36 package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see\ Introduction to Python in Configuring basic system settings.

--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.

Note: The pre-install script does not run in 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

Note that 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.

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 the python36 package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python in Configuring basic system settings.

--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 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 post-install script runs in a chroot environment, most systemctl commands will refuse to perform any action.

Note that 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.

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 the python36 package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python in Configuring basic system settings.

--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. Note that 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. Note that 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.3.3.3. Example: Running subscription-manager as a post-install script

One of the most common uses of post-installation scripts in Kickstart installations is automatic registration of the installed system using Red Hat Subscription Manager. The following is an example of automatic subscription in a %post script:

%post --log=/root/ks-post.log
subscription-manager register --username=admin@example.com --password=secret --auto-attach
%end

The subscription-manager command-line script registers a system to a Red Hat Subscription Management server (Customer Portal Subscription Management, Satellite 6, or CloudForms System Engine). This script can also be used to assign or attach subscriptions automatically to the system that best-match that system. When registering to the Customer Portal, use the Red Hat Network login credentials. When registering to Satellite 6 or CloudForms System Engine, you may also need to specify more subscription-manager options like --serverurl, --org, --environment as well as credentials provided by your local administrator. Note that credentials in the form of an --org --activationkey combination is a good way to avoid exposing --username --password values in shared kickstart files.

Additional options can be used with the registration command to set a preferred service level for the system and to restrict updates and errata to a specific minor release version of RHEL for customers with Extended Update Support subscriptions that need to stay fixed on an older stream.

See also the How do I use subscription-manager in a kickstart file? article on the Red Hat Customer Portal for additional information about using subscription-manager in a Kickstart %post section.

A.4. Anaconda configuration section

Additional installation options can be configured in the %anaconda section of your Kickstart file. This section controls the behavior of the user interface of the installation system.

This section must be placed towards the end of the Kickstart file, after Kickstart commands, and must start with %anaconda and end with %end.

Currently, the only command that can be used in the %anaconda section is pwpolicy.

Example A.1. Sample %anaconda script

The following is an example %anaconda section:

%anaconda
pwpolicy root --minlen=10 --strict
%end

This example %anaconda section sets a password policy which requires that the root password be at least 10 characters long, and strictly forbids passwords which do not match this requirement.

A.5. Kickstart error handling section

Starting with Red Hat Enterprise Linux 7, Kickstart installations can contain custom scripts which are run when the installation program encounters a fatal error. For example, an error in a package that has been requested for installation, failure to start VNC when specified, or an error when scanning storage devices. Installation cannot continue after such an error has occured. The installation program will run all %onerror scripts in the order they are provided in the Kickstart file. In addition, %onerror scripts will be run in the event of a traceback.

Each %onerror script is required to end with %end.

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.

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 the python36 package outside the installation environment. For more details about Python in Red Hat Enterprise Linux, see Introduction to Python in Configuring basic system settings.

--log=
Logs the script’s output into the specified log file.

A.6. 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.