f6f77b3162
There is the legacy kiwi version and there is this kiwi(next generation). From a documentation perspective there are several inconsistencies that could confuse users. This commit makes the name for KIWI-NG consistent across the entire documentation. At places where we point to older documentation we use the term Legacy KIWI and a link to the documentation that covers this part. All this is needed in preparation to cleanup the documentation situation for the SUSE documentation but with respect to the upstream doc sources, their layout and markup.
408 lines
14 KiB
ReStructuredText
408 lines
14 KiB
ReStructuredText
.. _working-with-kiwi-user-defined-scripts:
|
|
|
|
User Defined Scripts
|
|
====================
|
|
|
|
.. note:: **Abstract**
|
|
|
|
This chapter describes the usage of the user defined scripts
|
|
:file:`config.sh` and :file:`image.sh`, which can be used to further
|
|
customize an image in ways that are not possible via the image
|
|
description alone.
|
|
|
|
|
|
{kiwi} supports up to two user defined scripts that it runs in the change
|
|
root environment (chroot) containing your new appliance:
|
|
|
|
1. :file:`config.sh` runs the end of the :ref:`prepare step <prepare-step>`
|
|
if present. It can be used to fine tune the unpacked image.
|
|
|
|
2. :file:`images.sh` is executed at the beginning of the :ref:`image
|
|
creation process <create-step>`. It is run on the top level of the
|
|
target root tree. The script is usually used to remove files that are
|
|
not needed in the final image. For example, if an appliance is being
|
|
built for a specific hardware, unnecessary kernel drivers can be removed
|
|
using this script.
|
|
|
|
{kiwi} will execute both 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.
|
|
|
|
.. _image-customization-config-sh:
|
|
|
|
Image Customization via the ``config.sh`` Shell Script
|
|
------------------------------------------------------
|
|
|
|
The {kiwi} image description allows to have an :file:`config.sh` script in
|
|
place. It can be used for changes appropriate for all images to be created
|
|
from a given unpacked image (:file:`config.sh` runs prior to the *create
|
|
step*). The script should add operating system configuration files which
|
|
would be otherwise added by a user driven installer, like the activation of
|
|
services, creation of configuration files, preparation of an environment
|
|
for a firstboot workflow, etc.
|
|
|
|
The :file:`config.sh` script is called at the end of the :ref:`prepare step
|
|
<prepare-step>` (after users have been set and the *overlay tree directory*
|
|
has been applied). If :file:`config.sh` exits with a non-zero exit code
|
|
then {kiwi} will report the failure and abort the image creation.
|
|
|
|
Find a common template for `config.sh` script below:
|
|
|
|
.. code:: bash
|
|
|
|
#======================================
|
|
# Include functions & variables
|
|
#--------------------------------------
|
|
test -f /.kconfig && . /.kconfig
|
|
test -f /.profile && . /.profile
|
|
|
|
#======================================
|
|
# Greeting...
|
|
#--------------------------------------
|
|
echo "Configure image: [$kiwi_iname]..."
|
|
|
|
#======================================
|
|
# Call configuration code/functions
|
|
#--------------------------------------
|
|
...
|
|
|
|
Configuration Tips
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
#. **Stateless systemd UUIDs:**
|
|
|
|
Machine ID files are created and set (:file:`/etc/machine-id`,
|
|
:file:`/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} follows the `systemd
|
|
recommendations
|
|
<https://www.freedesktop.org/software/systemd/man/machine-id.html>`_ and
|
|
wipes any :file:`/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 :file:`/etc/machine-id` in
|
|
:file:`config.sh`.
|
|
|
|
.. note:: Avoid interactive boot
|
|
|
|
It is important to remark that the file :file:`/etc/machine-id` is set
|
|
to an empty file instead of deleting it. :command:`systemd` may
|
|
trigger :command:`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 :file:`/var/lib/dbus/machine-id`
|
|
|
|
Note that :file:`/etc/machine-id` and :file:`/var/lib/dbus/machine-id`
|
|
**must** contain the same unique ID. On modern systems
|
|
:file:`/var/lib/dbus/machine-id` is already a symlink to
|
|
:file:`/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 :file:`config.sh`:
|
|
|
|
.. code:: bash
|
|
|
|
#======================================
|
|
# 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
|
|
|
|
|
|
.. _image-customization-images-sh:
|
|
|
|
Image Customization via the ``images.sh`` Shell Script
|
|
------------------------------------------------------
|
|
|
|
The {kiwi} image description allows to have an optional :file:`images.sh`
|
|
bash script in place. It can be used for changes appropriate for certain
|
|
images/image types on a case-by-case basis (since it runs at beginning of
|
|
:ref:`create step <create-step>`).
|
|
|
|
.. 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!
|
|
|
|
The script should be designed to take over control of handling image type
|
|
specific tasks. For example, if building the OEM type requires some
|
|
additional packages or configurations then that can be handled in
|
|
:file:`images.sh`. Additionally, the script authors tasks is to check if
|
|
changes performed beforehand do not interfere in a negative way if another
|
|
image type is created from the same unpacked image root tree.
|
|
|
|
If :file:`images.sh` exits with a non-zero exit code, then {kiwi} will report
|
|
an error and abort the image creation.
|
|
|
|
See below a common template for :file:`images.sh` script:
|
|
|
|
.. code:: bash
|
|
|
|
#======================================
|
|
# Include functions & variables
|
|
#--------------------------------------
|
|
test -f /.kconfig && . /.kconfig
|
|
test -f /.profile && . /.profile
|
|
|
|
#======================================
|
|
# Greeting...
|
|
#--------------------------------------
|
|
echo "Configure image: [$kiwi_iname]..."
|
|
|
|
#======================================
|
|
# Call configuration code/functions
|
|
#--------------------------------------
|
|
...
|
|
|
|
#======================================
|
|
# Exit successfully
|
|
#--------------------------------------
|
|
exit 0
|
|
|
|
|
|
Functions and Variables Provided by {kiwi}
|
|
-------------------------------------------
|
|
|
|
{kiwi} creates the :file:`.kconfig` and :file:`.profile` files to be sourced
|
|
by the shell scripts :file:`config.sh` and :file:`images.sh`.
|
|
:file:`.kconfig` contains various helper functions which can be used to
|
|
simplify the image configuration and :file:`.profile` contains environment
|
|
variables which get populated from the settings provided in the image
|
|
description.
|
|
|
|
Provided Functions
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
The :file:`.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 :file:`.kconfig`:
|
|
|
|
``baseCleanMount``
|
|
Unmount the filesystems :file:`/proc`, :file:`/dev/pts`, :file:`/sys` and
|
|
:file:`/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 :file:`/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:
|
|
|
|
.. code:: bash
|
|
|
|
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 :command:`systemctl`.
|
|
|
|
``baseRemoveService {servicename}``
|
|
Deactivate the given service via :command:`systemctl`.
|
|
|
|
``baseService {servicename} {on|off}``
|
|
Activate or deactivate a service via :command:`systemctl`.
|
|
The function requires the service name and the value ``on`` or ``off`` as
|
|
parameters.
|
|
|
|
Example to enable the sshd service on boot:
|
|
|
|
.. code:: bash
|
|
|
|
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 :file:`/etc/products.d/baseproduct` link
|
|
pointing to the product referenced by either :file:`/etc/SuSE-brand` or
|
|
:file:`/etc/os-release` or the latest `.prod` file available in
|
|
:file:`/etc/products.d`
|
|
|
|
``suseSetupProductInformation``
|
|
Uses :command:`zypper` to search for the installed product
|
|
and installs all product specific packages. This function fails
|
|
when :command:`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.
|
|
|
|
Functions for Custom non-dracut Based Boot
|
|
''''''''''''''''''''''''''''''''''''''''''
|
|
|
|
{kiwi} also provides the following functions (mostly for compatibility
|
|
reasons) which can be used to customize the boot process when using the
|
|
custom boot option (see
|
|
:ref:`working-with-kiwi-customizing-the-boot-process`):
|
|
|
|
``baseStripInitrd``
|
|
Removes various tools binaries and libraries which
|
|
are not required to boot a SUSE system with {kiwi}. This function is not
|
|
required when using the dracut initrd system and is kept for
|
|
compatibility reasons.
|
|
|
|
``baseStripFirmware``
|
|
Check all kernel modules if they require a firmware and strip out all
|
|
firmware files which are not referenced by a kernel module
|
|
|
|
``baseStripModules``
|
|
Search for updated modules and remove the old version which might be
|
|
provided by the standard kernel
|
|
|
|
``baseStripKernel``
|
|
Strips the kernel:
|
|
|
|
1. create the :file:`vmlinux.gz` and :file:`vmlinuz` files which are used
|
|
as a fallback for the kernel extraction
|
|
|
|
2. handle `<strip type="delete">` requests. Because this information is
|
|
generic not only files of the kernel are affected but also other data
|
|
which are unwanted get deleted here
|
|
|
|
3. only keep kernel modules matching the `<drivers>` patterns from the
|
|
kiwi boot image description
|
|
|
|
4. lookup kernel module dependencies and bring back modules which were
|
|
removed but still required by other modules that were kept in the
|
|
system
|
|
|
|
5. search for duplicate kernel modules due to kernel module updates and
|
|
keep only the latest version
|
|
|
|
6. search for kernel firmware files and keep only those for which a
|
|
kernel driver is still present in the system
|
|
|
|
``suseStripKernel``
|
|
Removes all kernel drivers which are not listed in the
|
|
drivers sections of :file:`config.xml`.
|
|
|
|
``baseStripTools {list of toolpath} {list of tools}``
|
|
Helper function for suseStripInitrd
|
|
function parameters: toolpath, tools.
|
|
|
|
|
|
Profile Environment Variables
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The :file:`.profile` environment file is created by {kiwi} 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
|
|
:file:`config.xml`.
|
|
|
|
``$kiwi_delete``
|
|
A list of all packages which are children of the `packages` element
|
|
with `type="delete"` in :file:`config.xml`.
|
|
|
|
``$kiwi_drivers``
|
|
A comma separated list of the driver entries as listed in the
|
|
`drivers` section of the :file:`config.xml`.
|
|
|
|
``$kiwi_iname``
|
|
The name of the image as listed in :file:`config.xml`.
|
|
|
|
``$kiwi_iversion``
|
|
The image version as a string.
|
|
|
|
``$kiwi_keytable``
|
|
The contents of the keytable setup as done in :file:`config.xml`.
|
|
|
|
``$kiwi_language``
|
|
The contents of the locale setup as done in :file:`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 :file:`config.xml`.
|
|
|
|
``$kiwi_type``
|
|
The image type as extracted from the `type` element in
|
|
:file:`config.xml`.
|