systemd-firstboot.service(1)

NAME#

systemd-firstboot, systemd-firstboot.service - Initialize basic system settings on or before the first boot-up of a system

SYNOPSIS#

systemd-firstboot [OPTIONS...]

systemd-firstboot.service

DESCRIPTION#

The systemd-firstboot.service unit is one of the units which are used to initialize the machine configuration during "First Boot", i.e. when the system is freshly installed or after a factory reset. The systemd(1) manager itself will initialize machine-id(5) and preset all units, enabling or disabling them according to the systemd.preset(5) settings. systemd-firstboot.service is started later to interactively initialize basic system configuration. It is started only if ConditionFirstBoot=yes is met, which essentially means that /etc/ is unpopulated, see systemd.unit(5) for details. System credentials may be used to inject configuration; those settings are not queried interactively.

The systemd-firstboot command can also be used to non-interactively initialize an offline system image.

The following settings may be configured:

Each of the fields may either be queried interactively by users, set non-interactively on the tool's command line, or be copied from a host system that is used to set up the system image.

If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting.

Note that this tool operates directly on the file system and does not involve any running system services, unlike localectl(1), timedatectl(1) or hostnamectl(1). This allows systemd-firstboot to operate on mounted but not booted disk images and in early boot. It is not recommended to use systemd-firstboot on the running system after it has been set up.

OPTIONS#

The following options are understood:

--root=root

Added in version 216.

--image=path

Added in version 246.

--locale=LOCALE, --locale-messages=LOCALE

Added in version 216.

--keymap=KEYMAP

Added in version 236.

--timezone=TIMEZONE

Added in version 216.

--hostname=HOSTNAME

Added in version 216.

--setup-machine-id

This option only works in combination with --root= or --image=. On a running system, machine-id is written by the manager with help from systemd-machine-id-commit.service(8).

Added in version 216.

--machine-id=ID

Added in version 216.

--root-password=PASSWORD, --root-password-file=PATH, --root-password-hashed=HASHED_PASSWORD

Added in version 216.

--root-shell=SHELL

Added in version 246.

--kernel-command-line=CMDLINE

Added in version 246.

--prompt-locale, --prompt-keymap, --prompt-timezone, --prompt-hostname, --prompt-root-password, --prompt-root-shell

Added in version 216.

--prompt

Added in version 216.

--copy-locale, --copy-keymap, --copy-timezone, --copy-root-password, --copy-root-shell

Added in version 216.

--copy

Added in version 216.

--force

Added in version 246.

--reset

Added in version 254.

--delete-root-password

Added in version 246.

--welcome=

Added in version 246.

-h, --help

--version

CREDENTIALS#

systemd-firstboot supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(5) for details). The following credentials are used when passed in:

passwd.hashed-password.root, passwd.plaintext-password.root

Added in version 249.

passwd.shell.root

Added in version 249.

firstboot.locale, firstboot.locale-messages

Added in version 249.

firstboot.keymap

Note the relationship to the vconsole.keymap credential understood by systemd-vconsole-setup.service(8): both ultimately affect the same setting, but firstboot.keymap is written into /etc/vconsole.conf on first boot (if not already configured), and then read from there by systemd-vconsole-setup, while vconsole.keymap is read on every boot, and is not persisted to disk (but any configuration in vconsole.conf will take precedence if present).

Added in version 249.

firstboot.timezone

Added in version 249.

Note that by default the systemd-firstboot.service unit file is set up to inherit the listed credentials from the service manager. Thus, when invoking a container with an unpopulated /etc/ for the first time it is possible to configure the root user's password to be "systemd" like this:

# systemd-nspawn --image=... --set-credential=firstboot.locale:de_DE.UTF-8 ...

Note that these credentials are only read and applied during the first boot. Once they are applied they remain applied for subsequent boots, and the credentials are not considered anymore.

EXIT STATUS#

On success, 0 is returned, a non-zero failure code otherwise.

KERNEL COMMAND LINE#

systemd.firstboot=

Added in version 233.

SEE ALSO#

systemd(1), locale.conf(5), vconsole.conf(5), localtime(5), hostname(5), machine-id(5), shadow(5), systemd-machine-id-setup(1), localectl(1), timedatectl(1), hostnamectl(1)

NOTES#

1.

Discoverable Partitions Specification