Awesome Open Source
Awesome Open Source
This file is part of


Master Status


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


Useful issues resolved in the past


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 > build.log
lsinitcpio -l /boot/initramfs-linux.img
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
  • units found in [Unit]/Requires|OnFailure are recursively installed

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

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/ command=function_name

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

  • check for available mkinitcpio functions in /usr/lib/initcpio/
  • 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/

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

  • they come from host /root/.ssh/authorized_keys

Shell Script Questions and Answers

there is a 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 actions during last boot?

  • use journalctl -b -t shell

what does CTRL-C do to in different modes?

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

is there a silent or no-echo mode during password entry in

  • 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)

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (49,933
ssh (311
archlinux (83
systemd (51
btrfs (21
zfs (19

Find Open Source By Browsing 7,000 Topics Across 59 Categories