Incompatible Filesystem Settings on Host vs. Image

Note

Abstract

This page provides further information on how to solve image boot problems if the filesystem toolchain on the image build host is incompatible with the image’s target distribution.

When KIWI NG builds an image that requests the creation of a filesystem, the required filesystem creation tool, for example, mkfs.xfs, is called from the host on which KIWI NG is running. It is expected that the generated filesystem is compatible with the image’s target distribution. This expectation is not always correct and depends on the compatibility of the filesystem default settings between build host and image target. We know about the following settings that cause an incompatible filesystem, which will not be able to be used on boot:

Ext[2,3,4]

Check /etc/mke2fs.conf on the build host and make sure the configured inode_size is the same as the setting used for the target image. To solve an issue of this type, use the following filesystem creation option in your KIWI NG image configuration:

<type fscreateoptions="-I inode-size"/>

XFS

Check the XFS metadata setup on the build host and make sure the settings are compatible with the target image. XFS has the default settings compiled-in, thus it might be needed to build the image first and use the xfs_info tool in a disk.sh script to fetch the settings at the build time of the image. We know from community reports that the setting sparse=1 will cause issues on older versions of grub’s xfs module, which does not know how to handle this setting properly. To solve an issue of this type, use the following filesystem creation option in your KIWI NG image configuration:

<type fscreateoptions="-i sparse=0"/>

btrfs

btrfs and default page sizes (4k vs 64k). By default, btrfs autodetects the sector size according to the used kernel page size. If the sector size differs from the page size, the created filesystem cannot be mounted by the image’s target kernel. If there is a different kernel page size between the kernel on the system the image is built on and the later kernel used for the image, it’s required to specify the filesystem sector size to match with the kernel page size of the kernel used for the image. This can be done as in the following example:

<type fscreateoptions="--sectorsize 4k"/>

Note

There can be more inconsistencies in the area of filesystems that we have not listed here. In general, it’s advisable to build the image in a compatible environment. At best, the build host distribution is of the same major Linux version as the image target. For this purpose, KIWI NG provides the so-called boxed-plugin. Further details can be found in Building in a Self-Contained Environment