mkinitcpio-systemd-tool: A Shell repository from richiboi1977

This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool

mkinitcpio-systemd-tool

Never write another mkinitcpio hook again, use systemd-tool.

Summary

Provisioning tool for systemd in initramfs (systemd-tool)

mkinitcpio hook name: systemd-tool

Core features provided by the hook:

unified systemd + mkinitcpio configuration
automatic provisioning of binary and config resources
on-demand invocation of mkinitcpio scripts and in-line functions

Features provided by the included service units:

initrd debugging
early network setup
interactive user shell
remote ssh access in initrd
cryptsetup + custom password agent

Issues

Useful issues

Example

Basic usage steps:

activate required hooks in /etc/mkinitcpio.conf:

HOOKS="base systemd systemd-tool"

review, change and enable/disable provided default files:

/etc/systemd/network/initrd-*.network
/etc/systemd/system/initrd-*.service
/etc/systemd/system/initrd-*.sh

build/review initrd and reboot

mkinitcpio -v -p linux > build.log 
systemctl reboot

Details

makepkg/pacman install actions:

provision default files included in this package into the /etc
specific folders are /etc/mkinitcpio.d and /etc/systemd/{system,network}

mkinitcpio install hook actions:

look in the /etc/systemd/system
include in initrd units containing marker /etc/initrd-release
activate transitively in initrd any discovered systemd service units
auto provision into initramfs resources declared in the initrd service units

Provisioning Questions and Answers

what is the mkinitcpio hook entry provided by this package?

hook name: systemd-tool
required hooks are: base systemd systemd-tool
recommended hooks are: base autodetect modconf block filesystems keyboard fsck systemd systemd-tool

how can I include/exclude my custom service unit in initrd?

include: change [Unit] entry to ConditionPathExists=/etc/initrd-release
exclude: change [Unit] entry to ConditionPathExists=/etc/xxx/initrd-release

how can I enable/disable/mask/unmask my custom service unit in initrd?

enable: change [X-SystemdTool] entry InitrdService=enable

how systemd unit transitive dependency provisioning works?

see mkinitcpio-install.sh/add_systemd_unit_X()
units found in [Unit]/Requires|OnFailure are recursively installed

what is the purpose of [X-SystemdTool] section in service unit files?

see systemd/systemd#3340
this section provides configuration interface for mkinitcpio provisioning actions
entries: InitrdBuild, InitrdCall, InitrdService
entries: InitrdBinary, InitrdPath, InitrdLink

how can I auto-provision my custom service unit binaries into initramfs?

use InitrdBinary=/path/target-exec to provision service binary
also will be provisioned all Exec* entries such as ExecStart=/bin/program

how can I auto-provision my custom service unit resources into initramfs?

use InitrdPath=/path/to/host/folder-or-file

how can I relocate folder during provisioning?

not implemented, source and target folder must use the same location

how can I relocate file and/or change file mode during provisioning?

use InitrdPath=/target-file source=/source-file mode=NNN

how can I filter directory content during provisioning?

use InitrdPath=/target-folder glob=*.example

how can I provision optional folder or file?

use InitrdPath=/target-file source=/source-file optional=yes

is there a way to create empty folder or file?

for empty dir, use InitrdPath=/path/target-dir/ create=yes note trailing SLASH
for empty file, use InitrdPath=/path/target-file create=yes note NO trailing slash

how can I provision a symbolic link?

use InitrdLink=/path-to-link/link-name /path-to-target/target-name
note that /path-to-target/target-name must be provisioned separately

can I invoke a provisioning script related to my service during mkinitcpio build time?

use InitrdBuild=/path-to/script.sh command=function_name

can I call a little provisioning script snippet during mkinitcpio build time?

check for available mkinitcpio functions in /usr/lib/initcpio/functions.sh
use InitrdCall=inline-bash-code-here to call these functions

how can I provide custom interactive user shell for ssh client

change sample shell file located in /etc/systemd/system/initrd-shell.sh

which ssh user keys are used by initramfs sshd server?

they come from host /root/.ssh/authorized_keys

Shell Script Questions and Answers

there is a initrd-shell.sh script provided, what does it do?

it is used as both interactive login shell and as a systemd service
when crypto disks are present, it acts as password agent
when in ssh console, it offers simple interactive menu
when in systemd service mode, it acts as service

how can I review initrd-shell.sh actions during last boot?

use journalctl -b -t shell

what does CTRL-C do to initrd-shell.sh in different modes?

initrd-shell.sh provides appropriate reaction to interrupt, depending on the context
while in ssh terminal password agent prompt, it will start a menu form initrd-shell.sh
while in /dev/tty local debug console, it will exit from initrd-shell.sh
while in /dev/console password agent prompt, it will restart the initrd-shell.sh service

is there a silent or no-echo mode during password entry in initrd-shell.sh?

there are two ways to enter silent mode (see systemd-ask-password.c):
either by pressing BACKSPACE as first key or by pressing TAB at any time
then the prompt will show extra text: (no echo)

Package Build Questions and Answers

how can I install latest release or development version of this?

create a marker file .PKGDEV to build from latest branch=master ,
create a marker file .PKGREL to build from latest release tag=vNNN,
for example:

mkdir -p /tmp/aur
cd /tmp/aur
git clone https://aur.archlinux.org/mkinitcpio-systemd-tool.git
cd mkinitcpio-systemd-tool
touch .PKGDEV
makepkg --syncdeps --install   --noconfirm --needed

release versions look like 3-1, development like 3.25.d069dad-1

richiboi1977/mkinitcpio-systemd-tool

This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool