/mkinitcpio-systemd-tool

Provisioning tool for systemd in initramfs (systemd-tool)

Primary LanguagePythonOtherNOASSERTION

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

mkinitcpio-systemd-tool

Summary

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

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 + plymouth support
  • cryptsetup + custom password agent

Issues

Useful issues resolved in the past

Example

Basic usage steps:

  1. study and practice system recovery

  2. install the package

pacman -S mkinitcpio-systemd-tool
  1. activate required hooks in /etc/mkinitcpio.conf:
HOOKS=(base ... systemd systemd-tool)
  1. configure, override and enable/disable provided units, for example:
    for remote unlocking of luks root with cryptsetup and tinysshd use:
edit /etc/mkinitcpio-systemd-tool/config/crypttab
edit /etc/mkinitcpio-systemd-tool/config/fstab
systemctl enable initrd-cryptsetup.path
systemctl enable initrd-tinysshd.service
systemctl enable initrd-debug-progs.service
systemctl enable initrd-sysroot-mount.service
  1. build image, review content and finally reboot:
mkinitcpio -v -p linux > /tmp/initrd.log
lsinitcpio -l /boot/initramfs-linux.img | grep initrd
systemctl reboot

Install Details

pacman install actions:

  • take a look in arch repo and make file
  • provision user config and vendor systemd units into:
  • /etc/mkinitcpio-systemd-tool (with backup)
  • /usr/lib/systemd/system (with silent overwrite)

mkinitcpio install hook actions:

  • look for enabled units 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 inside 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 customize installed service units?

  • follow regular approaches to editing provided units
  • create service unit override with systemctl edit $unit_name
  • enable/disable with systemctl enable $unit_name / systemctl disable $unit_name

how can I review generated /boot/initramfs-linux.img?

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
  • directives: InitrdPath InitrdLink InitrdBinary InitrdBuild InitrdCall InitrdUnit

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=/usr/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 target=/path-to-target/target-name
  • note that link target /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 /usr/lib/mkinitcpio-systemd-tool/initrd-shell.sh

which ssh user keys are used by initramfs sshd server(s)?

  • they come from host /root//etc/mkinitcpio-systemd-tool/config/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)