Appendix A. Kickstart script file format reference
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 9 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 9. 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. 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: 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 9 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: 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: 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: 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 9, 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 9 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: 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 Managing Software with the DNF Tool 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: --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. 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: Configure Kickstart file with the following lines: 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 . --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 DNF will attempt to download packages (retries). The default value is 10. This option only applies during the installation, and will not affect DNF configuration on the installed system. --timeout= Sets the DNF timeout in seconds. The default value is 30. This option only applies during the installation, and will not affect DNF 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: --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. 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.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 9, you can select the kernel-64k package to install RHEL with kernel supporting 64k page size. Procedure In the %packages section of the kickstart file, add the following list of packages: Verification To verify the page size, after installation is completed and the system is rebooted, open the terminal and run: The output 65536 indicates that the 64k kernel is in use. To verify that the swap partition is enabled, enter: 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, 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: --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 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 Installing and using dynamic programming languages . --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: 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 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: 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 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 Installing and using dynamic programming languages . --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: 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. 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: --interpreter= Allows you to specify a different scripting language, such as Python. For example: 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 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 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. --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 : and with --nochroot : 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. 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, VNC fails to start if specified in the configuration, 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: 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 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 Installing and using dynamic programming languages . --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: The %addon command does not include any options of its own - all options are dependent on the actual add-on.
%packages @^Infrastructure Server %end %packages @X Window System @Desktop @Sound and Video %end %packages sqlite curl aspell docbook* %end %packages @module:stream/profile %end %packages -@Graphical Administration Tools -autofs -ipa*compat %end %packages --multilib --ignoremissing %packages --multilib --default %end %packages @Graphical Administration Tools --optional %end %packages kernel-64k -kmod-kvdo -vdo -kernel %end getconf PAGESIZE 65536 free total used free shared buff/cache available Mem: 35756352 3677184 34774848 25792 237120 32079168 Swap: 6504384 0 6504384 %pre --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end %pre --log=/tmp/ks-pre.log %pre-install --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end %pre-install --log=/mnt/sysroot/root/ks-pre.log %post --interpreter=/usr/libexec/platform-python -- Python script omitted -- %end %post --interpreter=/usr/libexec/platform-python %post --nochroot cp /etc/resolv.conf /mnt/sysroot/etc/resolv.conf %end %post --log=/root/ks-post.log %post --nochroot --log=/mnt/sysroot/root/ks-post.log 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 %onerror --interpreter=/usr/libexec/platform-python %addon com_redhat_kdump --enable --reserve-mb=auto %end