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

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.

Additional resources

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 (that is, 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, only packages for this architecture (marked as x86_64) and packages for all architectures (marked as noarch) would be installed. When you use this option, packages for 32-bit AMD and Intel systems (marked as i686) are automatically installed as well, if available.

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.

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

A.3. Pre-installation scripts in Kickstart

Pre-installation scripts are run immediately before installation begins.

A.3.1. Pre-installation script section

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.

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 scripts ignore missing files for the %include commands. This is useful for generating the included files in the %pre section, and having them loaded later.

Note

Unlike the post-installation script, the pre-installation script is not run in the chroot environment.

A.3.2. Pre-installation Kickstart 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 8, see Introduction to Python in Configuring basic system settings.

--erroronfail
Display an error and halt the installation if the script fails. The error message will direct you to where the cause of the failure is logged.
--log=

Logs the script’s output into the specified log file. For example:

%pre --log=/mnt/sysimage/root/ks-pre.log

A.4. Post-installation scripts in Kickstart

Post-installation scripts are 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.

A.4.1. Post-installation script section

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. For more information, see the Behavior of systemctl in a chroot Environment section of the Configuring and managing system administration document.

Note that during execution of the %post section, the installation media must be still inserted.

Important

If you configured the network with static IP information, including a name server, you can access the network and resolve IP addresses in the %post section. If you configured the network for DHCP, the /etc/resolv.conf file has not been completed when the installation executes the %post section. You can access the network, but you cannot resolve IP addresses. Thus, if you are using DHCP, you must specify IP addresses in the %post section.

A.4.2. Post-installation Kickstart 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 8, 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/sysimage/etc/resolv.conf
%end
--erroronfail
Display an error and halt the installation if the script fails. The error message will direct you to where the cause of the failure is logged.
--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/sysimage/root/ks-post.log

A.4.3. 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.4.4. 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.5. 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.6. 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
Display an error and halt the installation if the script fails. The error message will direct you to where the cause of the failure is logged.
--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 8, see Introduction to Python in Configuring basic system settings.

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

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