diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/systemd-firstboot.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/systemd-firstboot.1 | 475 |
1 files changed, 475 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/systemd-firstboot.1 b/upstream/mageia-cauldron/man1/systemd-firstboot.1 new file mode 100644 index 00000000..2b65a8ad --- /dev/null +++ b/upstream/mageia-cauldron/man1/systemd-firstboot.1 @@ -0,0 +1,475 @@ +'\" t +.TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 255" "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 unpopulated, 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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 246\&. +.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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 236\&. +.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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 216\&. +.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)\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 216\&. +.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)\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 246\&. +.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)\&. +.sp +Added in version 246\&. +.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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 216\&. +.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\&. +.sp +Added in version 216\&. +.RE +.PP +\fB\-\-force\fR +.RS 4 +Write configuration even if the relevant files already exist\&. Without this option, +\fBsystemd\-firstboot\fR +doesn\*(Aqt modify or replace existing files\&. Note that when configuring the root account, even with this option, +\fBsystemd\-firstboot\fR +only modifies the entry of the +"root" +user, leaving other entries in +/etc/passwd +and +/etc/shadow +intact\&. +.sp +Added in version 246\&. +.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\&. +.sp +Added in version 254\&. +.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\&. +.sp +Added in version 246\&. +.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\&. +.sp +Added in version 246\&. +.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(5) +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\&. +.sp +Added in version 249\&. +.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\&. +.sp +Added in version 249\&. +.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\&. +.sp +Added in version 249\&. +.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)\&. +.sp +Added in version 249\&. +.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\&. +.sp +Added in version 249\&. +.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\&. +.sp +Added in version 233\&. +.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 |