=head1 NAME os-initrd-mgr - Manage the Slackware ARM / AArch64 Operating System Initial RAM Disk =head1 SYNOPSIS B B<[>optionsB<]> =head1 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 C 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 B sections below) and if any are found, will reincorporate them into the OS InitRD. =head1 OPTIONS - GENERAL =over 4 =item B<-h>, B<--help> Show the available options and exit =item B<-v>, B<--version> Show the version information and exit =back =head1 OPTIONS - MAIN =over 4 =item B<-q>, B<--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. =item B<-O>, B<--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 B and B. =item B<-M>, B<--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. =item B<-F>, B<--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. =item B<-f>, B<--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. =item B<-S>, B<--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. B By default, the Kernel module loader will load all modules for the major sub systems. This is incompatible with the development features 'kmod_load_subsyst' and its variants ('kmod_load_subsyst_soc', 'kmod_load_subsyst_pci', 'kmod_load_subsyst_usb'). =item B<--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. B 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. =item B<-m>, B<--modprobe-synced-kmods> F> 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. =back =head1 FILES - KERNEL MODULE CONFIGURATION F Customisation script, runs prior to any Kernel module lists are set. F 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. F Customisation script, runs after the standard Kernel modules have been loaded into the Kernel. This is the most common customisation script users will need. B The other scripts do not need be present within /boot/local if they are not required. Typically users will only need to customise B. =head1 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. F This is a cache of the firmware contained within the OS InitRD. This is created when os-initrd-mgr is run. F B 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. B 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: B<--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. =head1 FILES - OPERATING SYSTEM AND MISCELLANEOUS CONFIGURATION The following files may also be present within /boot/local and will be reincorported into the OS InitRD. B 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. F Contains the name of the root device, such as: /dev/hda1 B<[ Default: Set within the Boot Loader configuration ]> F Contains the root filesystem type, such as: xfs B<[ Default: Set within the Boot Loader configuration ]> F Contains a number - the init script will wait this amount of seconds before creating device nodes. B<[ Default: Set within the Boot Loader configuration ]> F Contains the name of the device to resume from hibernation. F Contains colon separated list of luks encrypted devices to be unlocked. F Contains colon separated list of luks encrypted devices to pass '--allow-discards' when unlocking F Contains the path to a LUKS key-file for automatic unlock. Format: LABEL=:/path/to/file UUID=:/path/to/file F Contains the name for a custom keyboard map F Contains the name of the initrd file. F 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. =head1 FILES - SOFTWARE RAID with mdadm F 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 =head1 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# B 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. =head1 RETURN VALUES These are the exit codes that os-initrd-mgr will produce when it encounters certain problems. =over 4 =item B<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. =item B<1> An error occurred os-initrd-mgr failed to perform some critical part of the workflow. =back =head1 AUTHOR Stuart Winter =head1 SEE ALSO =over 4 B(8) =cut =back