path: root/upstream/debian-bookworm/man1/systemd-firstboot.1

'\" t
.TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 254" "systemd-firstboot"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-firstboot, systemd-firstboot.service \- Initialize basic system settings on or before the first boot\-up of a system
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-firstboot\fR\ 'u
\fBsystemd\-firstboot\fR [OPTIONS...]
.PP
systemd\-firstboot\&.service
.SH "DESCRIPTION"
.PP
\fBsystemd\-firstboot\fR
initializes basic system settings interactively during the first boot, or non\-interactively on an offline system image\&. The service is started during boot if
\fIConditionFirstBoot=yes\fR
is met, which essentially means that
/etc/
is empty, see
\fBsystemd.unit\fR(5)
for details\&.
.PP
The following settings may be configured:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The machine ID of the system
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The system locale, more specifically the two locale variables
\fILANG=\fR
and
\fILC_MESSAGES\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The system keyboard map
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The system time zone
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The system hostname
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The kernel command line used when installing kernel images
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The root user\*(Aqs password and shell
.RE
.PP
Each of the fields may either be queried interactively by users, set non\-interactively on the tool\*(Aqs command line, or be copied from a host system that is used to set up the system image\&.
.PP
If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting\&.
.PP
Note that this tool operates directly on the file system and does not involve any running system services, unlike
\fBlocalectl\fR(1),
\fBtimedatectl\fR(1)
or
\fBhostnamectl\fR(1)\&. This allows
\fBsystemd\-firstboot\fR
to operate on mounted but not booted disk images and in early boot\&. It is not recommended to use
\fBsystemd\-firstboot\fR
on the running system after it has been set up\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-root=\fR\fB\fIroot\fR\fR
.RS 4
Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
\fIroot\fR
path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
.RE
.PP
\fB\-\-image=\fR\fB\fIpath\fR\fR
.RS 4
Takes a path to a disk image file or block device node\&. If specified all operations are applied to file system in the indicated disk image\&. This is similar to
\fB\-\-root=\fR
but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
\fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
.RE
.PP
\fB\-\-locale=\fR\fB\fILOCALE\fR\fR, \fB\-\-locale\-messages=\fR\fB\fILOCALE\fR\fR
.RS 4
Sets the system locale, more specifically the
\fILANG=\fR
and
\fILC_MESSAGES\fR
settings\&. The argument should be a valid locale identifier, such as
"de_DE\&.UTF\-8"\&. This controls the
\fBlocale.conf\fR(5)
configuration file\&.
.RE
.PP
\fB\-\-keymap=\fR\fB\fIKEYMAP\fR\fR
.RS 4
Sets the system keyboard layout\&. The argument should be a valid keyboard map, such as
"de\-latin1"\&. This controls the
"KEYMAP"
entry in the
\fBvconsole.conf\fR(5)
configuration file\&.
.RE
.PP
\fB\-\-timezone=\fR\fB\fITIMEZONE\fR\fR
.RS 4
Sets the system time zone\&. The argument should be a valid time zone identifier, such as
"Europe/Berlin"\&. This controls the
\fBlocaltime\fR(5)
symlink\&.
.RE
.PP
\fB\-\-hostname=\fR\fB\fIHOSTNAME\fR\fR
.RS 4
Sets the system hostname\&. The argument should be a hostname, compatible with DNS\&. This controls the
\fBhostname\fR(5)
configuration file\&.
.RE
.PP
\fB\-\-setup\-machine\-id\fR
.RS 4
Initialize the system\*(Aqs machine ID to a random ID\&. This controls the
\fBmachine-id\fR(5)
file\&.
.sp
This option only works in combination with
\fB\-\-root=\fR
or
\fB\-\-image=\fR\&. On a running system,
machine\-id
is written by the manager with help from
\fBsystemd-machine-id-commit.service\fR(8)\&.
.RE
.PP
\fB\-\-machine\-id=\fR\fB\fIID\fR\fR
.RS 4
Set the system\*(Aqs machine ID to the specified value\&. The same restrictions apply as to
\fB\-\-setup\-machine\-id\fR\&.
.RE
.PP
\fB\-\-root\-password=\fR\fB\fIPASSWORD\fR\fR, \fB\-\-root\-password\-file=\fR\fB\fIPATH\fR\fR, \fB\-\-root\-password\-hashed=\fR\fB\fIHASHED_PASSWORD\fR\fR
.RS 4
Sets the password of the system\*(Aqs root user\&. This creates/modifies the
\fBpasswd\fR(5)
and
\fBshadow\fR(5)
files\&. This setting exists in three forms:
\fB\-\-root\-password=\fR
accepts the password to set directly on the command line,
\fB\-\-root\-password\-file=\fR
reads it from a file and
\fB\-\-root\-password\-hashed=\fR
accepts an already hashed password on the command line\&. See
\fBshadow\fR(5)
for more information on the format of the hashed password\&. Note that it is not recommended to specify plaintext passwords on the command line, as other users might be able to see them simply by invoking
\fBps\fR(1)\&.
.RE
.PP
\fB\-\-root\-shell=\fR\fB\fISHELL\fR\fR
.RS 4
Sets the shell of the system\*(Aqs root user\&. This creates/modifies the
\fBpasswd\fR(5)
file\&.
.RE
.PP
\fB\-\-kernel\-command\-line=\fR\fB\fICMDLINE\fR\fR
.RS 4
Sets the system\*(Aqs kernel command line\&. This controls the
/etc/kernel/cmdline
file which is used by
\fBkernel-install\fR(8)\&.
.RE
.PP
\fB\-\-prompt\-locale\fR, \fB\-\-prompt\-keymap\fR, \fB\-\-prompt\-timezone\fR, \fB\-\-prompt\-hostname\fR, \fB\-\-prompt\-root\-password\fR, \fB\-\-prompt\-root\-shell\fR
.RS 4
Prompt the user interactively for a specific basic setting\&. Note that any explicit configuration settings specified on the command line take precedence, and the user is not prompted for it\&.
.RE
.PP
\fB\-\-prompt\fR
.RS 4
Query the user for locale, keymap, timezone, hostname, root\*(Aqs password, and root\*(Aqs shell\&. This is equivalent to specifying
\fB\-\-prompt\-locale\fR,
\fB\-\-prompt\-keymap\fR,
\fB\-\-prompt\-timezone\fR,
\fB\-\-prompt\-hostname\fR,
\fB\-\-prompt\-root\-password\fR,
\fB\-\-prompt\-root\-shell\fR
in combination\&.
.RE
.PP
\fB\-\-copy\-locale\fR, \fB\-\-copy\-keymap\fR, \fB\-\-copy\-timezone\fR, \fB\-\-copy\-root\-password\fR, \fB\-\-copy\-root\-shell\fR
.RS 4
Copy a specific basic setting from the host\&. This only works in combination with
\fB\-\-root=\fR
or
\fB\-\-image=\fR\&.
.RE
.PP
\fB\-\-copy\fR
.RS 4
Copy locale, keymap, time zone, root password and shell from the host\&. This is equivalent to specifying
\fB\-\-copy\-locale\fR,
\fB\-\-copy\-keymap\fR,
\fB\-\-copy\-timezone\fR,
\fB\-\-copy\-root\-password\fR,
\fB\-\-copy\-root\-shell\fR
in combination\&.
.RE
.PP
\fB\-\-force\fR
.RS 4
Write configuration even if the relevant files already exist\&. Without this option,
systemd\-firstboot
doesn\*(Aqt modify or replace existing files\&. Note that when configuring the root account, even with this option,
systemd\-firstboot
only modifies the entry of the
"root"
user, leaving other entries in
/etc/passwd
and
/etc/shadow
intact\&.
.RE
.PP
\fB\-\-reset\fR
.RS 4
If specified, all existing files that are configured by
\fBsystemd\-firstboot\fR
are removed\&. Note that the files are removed regardless of whether they\*(Aqll be configured with a new value or not\&. This operation ensures that the next boot of the image will be considered a first boot, and
\fBsystemd\-firstboot\fR
will prompt again to configure each of the removed files\&.
.RE
.PP
\fB\-\-delete\-root\-password\fR
.RS 4
Removes the password of the system\*(Aqs root user, enabling login as root without a password unless the root account is locked\&. Note that this is extremely insecure and hence this option should not be used lightly\&.
.RE
.PP
\fB\-\-welcome=\fR
.RS 4
Takes a boolean argument\&. By default when prompting the user for configuration options a brief welcome text is shown before the first question is asked\&. Pass false to this option to turn off the welcome text\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SH "CREDENTIALS"
.PP
\fBsystemd\-firstboot\fR
supports the service credentials logic as implemented by
\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
(see
\fBsystemd.exec\fR(1)
for details)\&. The following credentials are used when passed in:
.PP
\fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
.RS 4
A hashed or plaintext version of the root password to use, in place of prompting the user\&. These credentials are equivalent to the same ones defined for the
\fBsystemd-sysusers.service\fR(8)
service\&.
.RE
.PP
\fIpasswd\&.shell\&.root\fR
.RS 4
Specifies the shell binary to use for the specified account\&. Equivalent to the credential of the same name defined for the
\fBsystemd-sysusers.service\fR(8)
service\&.
.RE
.PP
\fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
.RS 4
These credentials specify the locale settings to set during first boot, in place of prompting the user\&.
.RE
.PP
\fIfirstboot\&.keymap\fR
.RS 4
This credential specifies the keyboard setting to set during first boot, in place of prompting the user\&.
.sp
Note the relationship to the
\fIvconsole\&.keymap\fR
credential understood by
\fBsystemd-vconsole-setup.service\fR(8): both ultimately affect the same setting, but
\fIfirstboot\&.keymap\fR
is written into
/etc/vconsole\&.conf
on first boot (if not already configured), and then read from there by
\fBsystemd\-vconsole\-setup\fR, while
\fIvconsole\&.keymap\fR
is read on every boot, and is not persisted to disk (but any configuration in
vconsole\&.conf
will take precedence if present)\&.
.RE
.PP
\fIfirstboot\&.timezone\fR
.RS 4
This credential specifies the system timezone setting to set during first boot, in place of prompting the user\&.
.RE
.PP
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\*(Aqs password to be
"systemd"
like this:
.PP
.if n \{\
.RS 4
.\}
.nf
# systemd\-nspawn \-\-image=\&... \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \&...
.fi
.if n \{\
.RE
.\}
.PP
Note that these credentials are only read and applied during the first boot process\&. Once they are applied they remain applied for subsequent boots, and the credentials are not considered anymore\&.
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "KERNEL COMMAND LINE"
.PP
\fIsystemd\&.firstboot=\fR
.RS 4
Takes a boolean argument, defaults to on\&. If off,
systemd\-firstboot\&.service
won\*(Aqt interactively query the user for basic settings at first boot, even if those settings are not initialized yet\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBlocale.conf\fR(5),
\fBvconsole.conf\fR(5),
\fBlocaltime\fR(5),
\fBhostname\fR(5),
\fBmachine-id\fR(5),
\fBshadow\fR(5),
\fBsystemd-machine-id-setup\fR(1),
\fBlocalectl\fR(1),
\fBtimedatectl\fR(1),
\fBhostnamectl\fR(1)
.SH "NOTES"
.IP " 1." 4
Discoverable Partitions Specification
.RS 4
\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
.RE