=head1 NAME

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

=head1 SYNOPSIS

B<os-initrd-mgr> 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

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 B<FILES> 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<-F>,  B<--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.

=back

=head1 FILES - KERNEL MODULE CONFIGURATION

F</boot/local/load_kernel_modules.pre> Customisation script, runs prior to any Kernel module lists are set.

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

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

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

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

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

B<[ Default: Set within the Boot Loader configuration ]>

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

B<[ Default: Set within the Boot Loader configuration ]>

F</boot/local/wait-for-root> 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</boot/local/resumedev> Contains the name of the device to resume from hibernation.

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

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

F</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

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

F</boot/local/initrd-name> Contains the name of the initrd file.


=head1 FILES - SOFTWARE RAID with mdadm

F</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


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

=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 <mozes@slackware.com> 

=head1 SEE ALSO

=over 4

B<mkinitrd>(8)

=cut
=back