OS-INITRD-MGR(8)

NAME
os-initrd-mgr - Manage the Slackware ARM / AArch64 Operating System Initial RAM Disk

SYNOPSIS
os-initrd-mgr [options]

DESCRIPTION
The Slackware Linux Operating System is initially booted into an 'Initial RAM Disk', which is a small environment containing software drivers that when loaded provide access to the hardware, enabling the full Slackware Operating System to be launched from where it resides (typically on some locally-attached storage).

The Slackware Kernel package contains a generic copy of the Initial RAM Disk that supports the hardware present on known Hardware Models.

Users may need to customise the OS InitRD so that it supports some additional hardware required during the initial bootup, or perhaps if they are helping develop support for Slackware ARM / AArch64 on new Hardware Models.

Within Slackware ARM / AArch64, there is support for local customisations by way of shell scripts and configuration files that are located within the Operating System directory /boot/local. There are sample reference Kernel Module Loader scripts within /boot/local, and the Operating System configuration files are described within /boot/local/README.txt

"os-initrd-mgr" is a tool to manage both the initial incorporation of local customisations, and enables the changes to persist through Slackware Kernel package upgrades by reincorporating the customisations as part of the package upgrade process.

By default os-initrd-mgr will scan /boot/local for the customisations (see the FILES sections below) and if any are found, will reincorporate them into the OS InitRD.

OPTIONS - GENERAL

-h, --help
    Show the available options and exit

-v, --version
    Show the version information and exit

OPTIONS - MAIN

-q,  --quiet
    Surpress output messages if there are no user customisations within /boot/local. This option is used by the kernel package's post installation script to surpress any messages attached to inaction on the part of this tool, with the intention of only supplying informative messages should any actions need to be taken.

-O,  --os-inventory
    Discover and create an inventory of the live firmware and loaded Kernel modules, then exit. This is a mutually exclusive option.

    The firmware inventory file created is /run/os-initrd-mgr.fw-inventory

    This option is used for Slackware 15.0 where the runtime Kernel packages were split between a/kernel_armvX and a/kernel-modules-armvX.

-M,  --manual-mods
    Immediately prior to re-packing the OS InitRD, output the name of the temporary working directory containing the new OS InitRD contents and await user confirmation before proceeding.

    This enables manual modifications to the OS InitRD and is aimed at developers.

-F,  --force-rebuild
    Force a rebuild of the OS InitRD. This will primarily be used to remove customisations from the OS InitRD, but can also be used to re-process the Kernel modules and firmware even if they're already synchronized.

    Note: This option only removes from the OS InitRD the Kernel Module Loader scripts held within /boot/local. It does not presently remove any of the other configuration files (detailed in section 'FILES - OPERATING SYSTEM AND MISCELLANEOUS CONFIGURATION'); users need to create empty versions of those files within /boot/local, which has the same effect as being deleted.

-f,  --force-fw-repack
    If there is a valid firmware inventory for the OS InitRD but no firmware is detected during the scan, by default the firmware within the OS InitRD will remain unmodified. Such a situation would typically occur when there's a fault on the running system, and would result in re-creating the OS InitRD without (what is most likely) required firmware.

    This option forces the firmware to be re-evaluated and re-packaged, but may result in all firmware being removed from the OS InitRD.

    This is an advanced option and isn't expected to be used by most users.

-S,  --sync-loaded-kmods
    Slackware ARM ships with a generic OS InitRD that includes the gamut of Kernel modules required for all Hardware Models and peripherals. The purpose of this is to easily enable support for new Hardware Models. However, it results in a large (hundreds of MBs) OS InitRD which can take several seconds to load, thereby increasing the time taken to boot the Operating System.

    This option synchronizes the OS InitRD's Kernel modules with those presently loaded within the Operating System.

    Note: By default, the Kernel module loader will load all modules for the major sub systems. This is incompatible with the development feature 'kmod_load_subsyst'.

--force-kmod-sync-mismatch
    Kernel modules can only be synchronized when the running Kernel is within the same major version and patch level as the Kernel contained within the Slackware Kernel package. A mismatch occurs when upgrading from a major Kernel version. For example, you can upgrade from Linux 5.18.1 to 5.18.2 and synchronize the modules, but not from 5.17.1 to 5.18.1.

    This option bypasses this safety check, but is strongly discouraged as it may prevent your machine from booting.

    Note: The process may still fail if any of the loaded modules do not exist within the new Kernel's /lib/modules, in which case an error will be emitted and the existing modules within the OS InitRD will remain.

-m,  --modprobe-synced-kmods
    Note: this is experimental and shouldn't be used

    This option is used in conjunction with the above option (--sync-loaded-kmods), which enables loading all of the discovered modules in addition to those that are loaded as standard within the OS InitRD.

    This renders unnecessary the need to manually configure the module post load script (/boot/local/load_kernel_modules.post) because if the module is loaded when os-initrd-mgr is run, it'll be captured within the OS InitRD and loaded automatically during boot.

    This is not the default because some Kernel modules are best loaded within the Operating System Proper (outside of the OS InitRD environment), and can cause hangs/delays during the initialization of services such as BlueTooth.

FILES - KERNEL MODULE CONFIGURATION
/boot/local/load_kernel_modules.pre Customisation script, runs prior to any Kernel module lists are set.

/boot/local/load_kernel_modules.pre-modload Customisation script, runs after the standard Kernel module lists are set but prior to loading them into the Kernel. This enables manipulation of the lists which may be useful if the base set includes a particular module that causes problems during bootup. The script includes examples to manage the lists.

/boot/local/load_kernel_modules.post Customisation script, runs after the standard Kernel modules have been loaded into the Kernel. This is the most common customisation script users will need.

Note: The other scripts do not need be present within /boot/local if they are not required. Typically users will only need to customise /boot/local/load_kernel_modules.post.

FILES - KERNEL FIRMWARE
The OS InitRD contains firmware required at boot for the supported Hardware Models, and the os-initrd-mgr tool will also add any additional firmware detected at runtime.

/boot/.os-initrd-fw-inventory This is a cache of the firmware contained within the OS InitRD. This is created when os-initrd-mgr is run.

/boot/local/extra_firmware This is an advanced option for developers and should not be used nor be required by normal users.

There may be occasions when os-initrd-mgr doesn't detect required firmware, and this is a local customisation that enables the user to provide a static list of firmware to include.

This file isn't present by default, and generally its use should be unnecessary.

Caveats:

1. This file will be examined by os-initrd-mgr only when re-processing the firmware (when there's either no local inventory cache (see above) or the firmware is out of sync). If you have added some firmware to this file for the first time and would like to have it included, run os-initrd-mgr with the two force options: --force-rebuild --force-fw-repack to force a rebuild.

2. If the firmware listed in the extra_firmware file has no associated and loaded Kernel module, os-initrd-mgr will report that the firmware is out of sync until the Kernel module is loaded.

FILES - OPERATING SYSTEM AND MISCELLANEOUS CONFIGURATION
The following files may also be present within /boot/local and will be reincorported into the OS InitRD.

Important note:

By default, the Slackware ARM / AArch64 Kernel package ships these files as empty, as the principal configurations are stored within the Boot Loader configuration (/boot/extlinux/extlinux.conf on Slackware AArch64). These options are passed to the Kernel via its command line interface (/proc/cmdline).

Users are at liberty to set the configuration via either method, but must be aware that options supplied via the Kernel command line interface take precedence over the file-based configuration options.

/boot/local/rootdev Contains the name of the root device, such as: /dev/hda1

[ Default: Set within the Boot Loader configuration ]

/boot/local/rootfs Contains the root filesystem type, such as: xfs

[ Default: Set within the Boot Loader configuration ]

/boot/local/wait-for-root Contains a number - the init script will wait this amount of seconds before creating device nodes.

[ Default: Set within the Boot Loader configuration ]

/boot/local/resumedev Contains the name of the device to resume from hibernation.

/boot/local/luksdev Contains colon separated list of luks encrypted devices to be unlocked.

/boot/local/lukstrim Contains colon separated list of luks encrypted devices to pass '--allow-discards' when unlocking

/boot/local/lukskey Contains the path to a LUKS key-file for automatic unlock.

Format: LABEL=<partition_label>:/path/to/file
        UUID=<partition_uuid>:/path/to/file

/boot/local/keymap Contains the name for a custom keyboard map

/boot/local/initrd-name Contains the name of the initrd file.

/etc/os-initrd-mgr.conf Configuration file for os-initrd-mgr. This overrides all default settings and any command line operators. It can also be used to set up user-defined hooks to control parts of os-initrd-mgr's execution.

FILES - SOFTWARE RAID with mdadm
/etc/mdadm.conf configuration for management of Software RAID with mdadm

os-initrd manages the addition and removal of the mdadm tool's Software Raid configuration file, /etc/mdadm.conf

If a functioning (not purely comments) /etc/mdadm.conf is found within the OS' File System, it will be installed into the OS InitRD. If you no longer require the configuration file within the OS InitRD, you should delete it from the OS (rm /etc/mdadm.conf) and rebuild the OS InitRD as follows:

Example:
   root@bladswede:/# os-initrd-mgr --force-rebuild

USAGE EXAMPLES
By way of an example, we will configure the OS InitRD to load a UK keymap and we'd like to add an additional Kernel module to support a storage device supported by a module not present within the OS InitRD supplied by Slackware ARM:

   root@bladswede:/boot/local# ls -1
   README.txt
   load_kernel_modules.post.sample
   load_kernel_modules.pre-modload.sample
   load_kernel_modules.pre.sample

Set the keymap configuration:
   root@bladswede:/boot/local# echo uk > keymap

Create the Kernel helper shell script:

   root@bladswede:/boot/local# echo 'modprobe ums-datafab' > load_kernel_modules.post

Call the tool:

   root@bladswede:/boot/local# os-initrd-mgr
   Searching for local customisations ...
   Found: /boot/local/keymap
   Found: /boot/local/load_kernel_modules.post

   Unpacking /boot/initrd-armv8 ...
   Adding customisations ...
   Repacking /boot/initrd-armv8 ...
   Successfully added local customisations to the OS InitRD.
   root@bladswede:/boot/local#

Note: When the Slackware Kernel package is upgraded, it will run os-inigrd-mgr as part of the upgrade process, and will reincorporate the local customisations as long as they remain within /boot/local.

RETURN VALUES
These are the exit codes that os-initrd-mgr will produce when it encounters certain problems.

0 Clean exit
    os-initrd-mgr exited without encountering any errors. This is the default exit code.

    If there are no local customisations present within /boot/local, os-initrd-mgr will exit with status 0, and (unless the -q command line option is specified) will report an appropriate message.

1 An error occurred
    os-initrd-mgr failed to perform some critical part of the workflow.

AUTHOR
Stuart Winter <mozes@slackware.com>

SEE ALSO
    mkinitrd(8)