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.

-F,  --force-rebuild
    Force a rebuild of the OS InitRD even if no local customisations are found. This will primarily be used to remove customisations from the OS InitRD.

    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.

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 - 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.

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)