Skip to content

Retarder

Jump to bottom
Markus Hansmair edited this page Mar 3, 2026 · 3 revisions

sd-retarder extends (retards) the initramfs phase of the Linux boot process until one of the following two conditions is met:

  • a SSH session has been terminated and no other SSH session is still active or

  • after a configurable amount of time (default 20sec) after system start no active SSH session is detected. (See below for details.)

This way sd-retarder allows to access the preliminary Linux system during iniramfs phase by SSH, while still being able to boot up to the final operating environment without user intervention. This can be used to perform all kinds of actions that require filesystems not being mounted yet, e.g. backup, restore, merging of snapshots, etc.

Use other install hooks like sd-tinyssh, sd-dropbear, sd-openssh and sd-network to be able to access the initramfs environment via SSH.

Note

sd-retarder is NOT required if the purpose of a SSH connection during initramfs phase is to unlock one or more LUKS encrypted volume(s) that are used by the final operating environment. In this case systemd waits anyway until those volumes become available (i.e. have been unlocked).

Configuration

Add sd-retarder to the array HOOKS in /etc/mkinitcpio.conf. The entry must be positioned somewhere after (right of) systemd. Apart from that the concrete position is irrelevant.

There are two additional configuration parameters that can be specified somewhere in /etc/mkinitcpio.conf:

  • SD_RETARD_SECONDS: Number of seconds (default 20) after system start when the retarder checks for active SSH sessions. In case no active SSH sessions are detected the boot process continues. The special value infinity disables this timeout condition, i.e. the boot process continues only when a SSH session has been terminated and no other SSH session is still active.

  • SD_RETARD_SSH_SERVICE: The name of the SSH service that should be checked for active SSH connections. Usually this variable is not required as sd-retarder inspects bash array HOOKS (defined in /etc/mkinitcpio.conf) to determine which SSH service to monitor. These can be tinyssh, dropbear, sshd and openssh - the latter being an alias for sshd. Other values are tolerated, but will produce a warning.

    Keep in mind that the retarder checks for SSH services spawned by means of a corresponding socket unit. I.e. each SSH session must be represented by a services of the form $SD_RETARD_SSH_SERVICE@*.service. If this sounds like gobbledegook for you, you better leave SD_RETARD_SSH_SERVICE unset.

Clone this wiki locally