almalinux/kiwi-el8
14
0
Fork 0
Code Issues Pull Requests Releases Activity
aa4eaa8aee
kiwi-el8/doc/source/concept_and_workflow/shell_scripts.rst
Marcus Schäfer 2510bb3d6f
Fix vagrant documentation 
The previous pull request adding a baseVagrantSetup method
and documentation broke the build of the docs due to invalid
indentation. The test pipeline has failed but the PR was
merged so this followup commit is needed to fix the docs
2020-12-15 15:54:17 +01:00

343 lines
12 KiB
ReStructuredText
Raw Blame History

.. _working-with-kiwi-user-defined-scripts:
User Defined Scripts
====================
.. note:: **Abstract**
This chapter describes the purpose of the user defined scripts
:file:`config.sh`, :file:`image.sh` and :file:`disk.sh`, which can
be used to further customize an image in ways that are not possible
via the image description alone.
{kiwi} 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 :ref:`prepare step <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 :ref:`image
creation process <create-step>`. 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 type `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 :file:`config.sh` and :file:`images.sh`. The script :file:`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} 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} will report the failure and abort the image creation.
Script Template for config.sh / images.sh
-----------------------------------------
{kiwi} provides a collection of methods and variables that supports users
with custom operations. For details see :ref:`image-customization-methods`.
The following template shows how to import this information in your
script:
.. code:: bash
#======================================
# 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!
.. _image-customization-methods:
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.
Functions
^^^^^^^^^
The :file:`.kconfig` file provides a common set of functions. Functions
specific to SUSE Linux Enterprise and openSUSE 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.
baseVagrantSetup
Configures the image to work as a vagrant box by performing the following
changes:
- add the ``vagrant`` user to :file:`/etc/sudoers`
or :file:`/etc/sudoers.d/vagrant`
- insert the insecure vagrant ssh key, apply recommended
ssh settings and start the ssh daemon
- create the default shared folder :file:`/vagrant`
Debug {message}
Helper function to print the supplied message if the variable DEBUG is
set to 1 (it is off by default).
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 :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`.
Configuration Tips
------------------
#. **Locale configuration:**
KIWI in order to set the locale relies on :command:`systemd-firstboot`,
which in turn writes the locale configuration file :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 :command:`systemd-firstboot`
is only effective if locales in :file:`/etc/sysconfig/language` are
not set or if the file does not exist at all. In SLE12
:file:`/etc/sysconfig/language` has precendence over
:file:`/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
:file:`config.sh` script or by adding any additional configuration file
as part of the overlay root-tree.
#. **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
Reference in New Issue View Git Blame Copy Permalink