User Defined Scripts

Note

Abstract

This chapter describes the purpose of the user defined scripts config.sh, image.sh and disk.sh, which can be used to further customize an image in ways that are not possible via the image description alone.

KIWI NG supports the following optional scripts that it runs in a root environment (chroot) containing your new appliance:

config.sh

runs at the end of the prepare step and after users have been set and the overlay tree directory has been applied. It is usually used to apply a permanent and final change of data in the root tree, such as modifying a package provided config file.

images.sh

is executed at the beginning of the image creation process. It runs in the same image root tree that has been created by the prepare step but is invoked any time an image should be created from that root tree. It is usually used to apply image type specific changes to the root tree such as a modification to a config file that should be done when building a live iso but not when building a virtual disk image.

disk.sh

is executed for the disk image types vmx and oem only and runs after the synchronisation of the root tree into the disk image loop file. At call time of the script the device name of the currently mapped root device is passed as a parameter. The chroot environment for this script call is the virtual disk itself and not the root tree as with config.sh and images.sh. disk.sh is usually used to apply changes at parts of the system that are not an element of the file based root tree such as the partition table, the bootloader or filesystem attributes.

KIWI NG executes scripts via the operating system if their executable bit is set (in that case a shebang is mandatory) otherwise they will be invoked via the BASH. If a script exits with a non-zero exit code then KIWI NG will report the failure and abort the image creation.

Script Template for config.sh / images.sh

KIWI NG provides a collection of methods and variables that supports users with custom operations. For details see Functions and Variables Provided by KIWI NG. The following template shows how to import this information in your script:

#======================================
# Include functions & variables
#--------------------------------------
test -f /.kconfig && . /.kconfig
test -f /.profile && . /.profile

...

Warning

Modifications of the unpacked root tree

Keep in mind that there is only one unpacked root tree the script operates in. This means that all changes are permanent and will not be automatically restored!

Functions and Variables Provided by KIWI NG

KIWI NG creates the .kconfig and .profile files to be sourced by the shell scripts config.sh and images.sh. .kconfig contains various helper functions which can be used to simplify the image configuration and .profile contains environment variables which get populated from the settings provided in the image description.

Functions

The .kconfig file provides a common set of functions. Functions specific to SUSE Linux begin with the name suse, functions applicable to all Linux distributions start with the name base.

The following list describes all functions provided by .kconfig:

baseCleanMount

Unmount the filesystems /proc, /dev/pts, /sys and /proc/sys/fs/binfmt_misc.

baseGetPackagesForDeletion

Return the name(s) of the packages marked for deletion in the image description.

baseGetProfilesUsed

Return the name(s) of profiles used to build this image.

baseSetRunlevel {value}

Set the default run level.

baseSetupUserPermissions

Set the ownership of all home directories and their content to the correct users and groups listed in /etc/passwd.

baseStripAndKeep {list of info-files to keep}

Helper function for the baseStrip* functions, reads the list of files to check from stdin for removing params: files which should be kept

baseStripDocs {list of docu names to keep}

Remove all documentation files, except for the ones given as the parameter.

baseStripInfos {list of info-files to keep}

Remove all info files, except for the one given as the parameter.

baseStripLocales {list of locales}

Remove all locales, except for the ones given as the parameter.

baseStripTranslations {list of translations}

Remove all translations, except for the ones given as the parameter.

baseStripMans {list of manpages to keep}

Remove all manual pages, except for the ones given as the parameter.

Example:

baseStripMans more less
suseImportBuildKey

Add the SUSE build keys to the RPM database.

baseStripUnusedLibs

Remove libraries which are not directly linked against applications in the bin directories.

baseUpdateSysConfig {filename} {variable} {value}

Update the contents of a sysconfig variable

suseConfig

This function is deprecated and is a NOP.

baseSystemdServiceInstalled {service}

Prints the path of the first found systemd unit or mount with name passed as the first parameter.

baseSysVServiceInstalled {service}

Prints the name ${service} if a SysV init service with that name is found, otherwise it prints nothing.

baseSystemdCall {service_name} {args}

Calls systemctl ${args} ${service_name} if a systemd unit, a systemd mount or a SysV init service with the ${service_name} exist.

baseInsertService {servicename}

Activate the given service via systemctl.

baseRemoveService {servicename}

Deactivate the given service via systemctl.

baseService {servicename} {on|off}

Activate or deactivate a service via systemctl. The function requires the service name and the value on or off as parameters.

Example to enable the sshd service on boot:

baseService sshd on
suseInsertService {servicename}

Calls baseInsertService and exists only for compatibility reasons.

suseRemoveService {servicename}

Calls baseRemoveService and exists only for compatibility reasons.

suseService {servicename} {on|off}

Calls baseService and exists only for compatibility reasons.

suseActivateDefaultServices

Activates the network and cron services to run at boot.

suseSetupProduct

Creates the /etc/products.d/baseproduct link pointing to the product referenced by either /etc/SuSE-brand or /etc/os-release or the latest prod file available in /etc/products.d

suseSetupProductInformation

Uses zypper to search for the installed product and installs all product specific packages. This function fails when zypper is not the appliances package manager.

Debug {message}

Helper function to print the supplied message if the variable DEBUG is set to 1.

Echo {echo commandline}

Helper function to print a message to the controlling terminal.

Rm {list of files}

Helper function to delete files and log the deletion.

Rpm {rpm commandline}

Helper function for calling rpm: forwards all commandline arguments to rpm and logs the call.

Profile Environment Variables

The .profile environment file is created by KIWI NG and contains a specific set of variables which are listed below.

$kiwi_compressed

The value of the compressed attribute set in the type element in config.xml.

$kiwi_delete

A list of all packages which are children of the packages element with type="delete" in config.xml.

$kiwi_drivers

A comma separated list of the driver entries as listed in the drivers section of the config.xml.

$kiwi_iname

The name of the image as listed in config.xml.

$kiwi_iversion

The image version as a string.

$kiwi_keytable

The contents of the keytable setup as done in config.xml.

$kiwi_language

The contents of the locale setup as done in config.xml.

$kiwi_profiles

A comma separated list of profiles used to build this image.

$kiwi_timezone

The contents of the timezone setup as done in config.xml.

$kiwi_type

The image type as extracted from the type element in config.xml.

Configuration Tips

  1. Locale configuration:

KIWI in order to set the locale relies on systemd-firstboot, which in turn writes the locale configuration file /etc/locale.conf. The values for the locale settings are taken from the description XML file in the <locale> element under <preferences>.

KIWI assumes systemd adoption to handle these locale settings, in case the build distribution does not honor /etc/locale.conf this is likely to not produce any effect on the locale settings. As an example, in SLE12 distribution the locale configuration is already possible by using the systemd toolchain, however this approach overlaps with SUSE specific managers such as YaST. In that case using systemd-firstboot is only effective if locales in /etc/sysconfig/language are not set or if the file does not exist at all. In SLE12 /etc/sysconfig/language has precendence over /etc/locale.conf for compatibility reasons and management tools could still relay on sysconfig files for locale settings.

In any case the configuration is still possible in KIWI by using any distribution specific way to configure the locale setting inside the config.sh script or by adding any additional configuration file as part of the overlay root-tree.

  1. Stateless systemd UUIDs:

Machine ID files are created and set (/etc/machine-id, /var/lib/dbus/machine-id) during the image package installation when systemd and/or dbus are installed. Those UUIDs are intended to be unique and set only once in each deployment. KIWI NG follows the systemd recommendations and wipes any /etc/machine-id content, leaving it as an empty file. Note, this only applies to images based on a dracut initrd, it does not apply for container images.

In case this setting is also required for a non dracut based image, the same result can achieved by removing /etc/machine-id in config.sh.

Note

Avoid interactive boot

It is important to remark that the file /etc/machine-id is set to an empty file instead of deleting it. systemd may trigger systemd-firstboot service if this file is not present, which leads to an interactive firstboot where the user is asked to provide some data.

Note

Avoid inconsistent /var/lib/dbus/machine-id

Note that /etc/machine-id and /var/lib/dbus/machine-id must contain the same unique ID. On modern systems /var/lib/dbus/machine-id is already a symlink to /etc/machine-id. However on older systems those might be two different files. This is the case for SLE-12 based images. If you are targeting these older operating systems, it is recommended to add the symlink creation into config.sh:

#======================================
# Make machine-id consistent with dbus
#--------------------------------------
if [ -e /var/lib/dbus/machine-id ]; then
    rm /var/lib/dbus/machine-id
fi
ln -s /etc/machine-id /var/lib/dbus/machine-id