From 30f10abf42f9e4d251a0b45b07812aafdef6be7c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 7 Jul 2014 18:45:53 +0200 Subject: [PATCH] man: document systemd-firstboot(1) --- Makefile-man.am | 7 + man/hostname.xml | 10 +- man/hostnamectl.xml | 10 +- man/locale.conf.xml | 11 +- man/localectl.xml | 8 +- man/localtime.xml | 8 +- man/machine-id.xml | 8 +- man/systemd-firstboot.xml | 286 +++++++++++++++++++++++++++++++ man/systemd-machine-id-setup.xml | 10 +- man/timedatectl.xml | 8 +- 10 files changed, 352 insertions(+), 14 deletions(-) create mode 100644 man/systemd-firstboot.xml diff --git a/Makefile-man.am b/Makefile-man.am index 5c289dda2..e6043f1ff 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -63,6 +63,7 @@ MANPAGES += \ man/systemd-delta.1 \ man/systemd-detect-virt.1 \ man/systemd-efi-boot-generator.8 \ + man/systemd-firstboot.8 \ man/systemd-fsck@.service.8 \ man/systemd-fstab-generator.8 \ man/systemd-getty-generator.8 \ @@ -193,6 +194,7 @@ MANPAGES_ALIAS += \ man/systemd-ask-password-console.path.8 \ man/systemd-ask-password-wall.path.8 \ man/systemd-ask-password-wall.service.8 \ + man/systemd-firstboot.service.8 \ man/systemd-fsck-root.service.8 \ man/systemd-fsck.8 \ man/systemd-hibernate.service.8 \ @@ -298,6 +300,7 @@ man/sd_notifyf.3: man/sd_notify.3 man/systemd-ask-password-console.path.8: man/systemd-ask-password-console.service.8 man/systemd-ask-password-wall.path.8: man/systemd-ask-password-console.service.8 man/systemd-ask-password-wall.service.8: man/systemd-ask-password-console.service.8 +man/systemd-firstboot.service.8: man/systemd-firstboot.8 man/systemd-fsck-root.service.8: man/systemd-fsck@.service.8 man/systemd-fsck.8: man/systemd-fsck@.service.8 man/systemd-hibernate.service.8: man/systemd-suspend.service.8 @@ -553,6 +556,9 @@ man/systemd-ask-password-wall.path.html: man/systemd-ask-password-console.servic man/systemd-ask-password-wall.service.html: man/systemd-ask-password-console.service.html $(html-alias) +man/systemd-firstboot.service.html: man/systemd-firstboot.html + $(html-alias) + man/systemd-fsck-root.service.html: man/systemd-fsck@.service.html $(html-alias) @@ -1600,6 +1606,7 @@ EXTRA_DIST += \ man/systemd-delta.xml \ man/systemd-detect-virt.xml \ man/systemd-efi-boot-generator.xml \ + man/systemd-firstboot.xml \ man/systemd-fsck@.service.xml \ man/systemd-fstab-generator.xml \ man/systemd-getty-generator.xml \ diff --git a/man/hostname.xml b/man/hostname.xml index a8648c529..2f949dedd 100644 --- a/man/hostname.xml +++ b/man/hostname.xml @@ -73,8 +73,11 @@ You may use hostnamectl1 - to change the value of this file from the command - line. + to change the value of this file during runtime from + the command line. Use + systemd-firstboot1 + to initialize it on mounted (but not booted) system + images. @@ -95,7 +98,8 @@ machine-id5, machine-info5, hostnamectl1, - systemd-hostnamed.service8 + systemd-hostnamed.service8, + systemd-firstboot1 diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index 4e456eb8f..7729ef692 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -84,7 +84,12 @@ for more information. The pretty hostname, chassis type, and icon name are stored in /etc/machine-info, see - machine-id5. + machine-info5. + + Use + systemd-firstboot1 + to initialize the system host name for mounted (but + not booted) system images. @@ -236,7 +241,8 @@ hostname5, machine-info5, systemctl1, - systemd-hostnamed.service8 + systemd-hostnamed.service8, + systemd-firstboot1 diff --git a/man/locale.conf.xml b/man/locale.conf.xml index e97092102..67bcc18e2 100644 --- a/man/locale.conf.xml +++ b/man/locale.conf.xml @@ -96,6 +96,13 @@ configuration files might be checked for locale configuration as well, however only as fallback. + + localectl1 + may be used to alter the settings in this file during + runtime from the command line. Use + systemd-firstboot1 + to initialize them on mounted (but not booted) system + images. @@ -142,7 +149,9 @@ LC_MESSAGES=en_US.UTF-8 systemd1, locale7, - systemd-localed.service8 + localectl1, + systemd-localed.service8, + systemd-firstboot1 diff --git a/man/localectl.xml b/man/localectl.xml index 9c32c794a..38e73c794 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -73,6 +73,11 @@ UI before the user logs in, such as the display manager, as well as the default for users after login. + + Use + systemd-firstboot1 + to initialize the system locale for mounted (but not + booted) system images. @@ -233,7 +238,8 @@ The XKB Configuration Guide , systemctl1, - systemd-localed.service8 + systemd-localed.service8, + systemd-firstboot1 diff --git a/man/localtime.xml b/man/localtime.xml index dbf2379e7..2d6372026 100644 --- a/man/localtime.xml +++ b/man/localtime.xml @@ -86,7 +86,10 @@ You may use timedatectl1 to change the settings of this file from the command - line. + line during runtime. Use + systemd-firstboot1 + to initialize the time zone on mounted (but not + booted) system images. @@ -96,7 +99,8 @@ tzset3, localtime3, timedatectl1, - systemd-timedated.service8 + systemd-timedated.service8, + systemd-firstboot1 diff --git a/man/machine-id.xml b/man/machine-id.xml index 4b4759e48..725370d32 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -85,7 +85,10 @@ The systemd-machine-id-setup1 tool may be used by installer tools to initialize the - machine ID at install time. + machine ID at install time. Use + systemd-firstboot1 + to initialize it on mounted (but not booted) system + images. @@ -138,7 +141,8 @@ id[8] = (id[8] & 0x3F) | 0x80; machine-info5, os-release5, sd-id1283, - sd_id128_get_machine3 + sd_id128_get_machine3, + systemd-firstboot1 diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml new file mode 100644 index 000000000..42fd753f5 --- /dev/null +++ b/man/systemd-firstboot.xml @@ -0,0 +1,286 @@ + + + + + + + + + systemd-firstboot + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-firstboot + 1 + + + + systemd-firstboot + systemd-firstboot.service + Initialize basic system settings on or before the first boot-up of a system + + + + + systemd-firstboot + OPTIONS + + + systemd-firstboot.service + + + + Description + + systemd-firstboot initializes + the most basic system settings interactively on the + first boot, or optionally non-interactively when a + system image is created. The following settings may be + set up: + + + The system locale, more + specifically the two locale variables + LANG= and + LC_MESSAGES + + The system time zone + + The system host name + + The machine ID of the system + + The root user's password + + + Each of the fields may either be queried + interactively from the 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 + localectl1, + timedatectl1 + or + hostnamectl1. This + allows systemd-firstboot to operate + on mounted but not booted disk images and in early + boot. It is not recommended to use + systemd-firsboot on the running + system while it is up. + + + + Options + + The following options are understood: + + + + + Takes a directory path + as an argument. All paths will be + prefixed with the given alternate + root 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. + + + + + + + + Sets the system + locale, more specifically the + LANG= and + LC_MESSAGES + settings. The argument should be a + valid locale identifier, such as + de_DE.UTF-8. This + controls the + locale.conf5 + configuration file. + + + + + + Sets the system time + zone. The argument should be a valid + time zone identifier, such as + Europe/Berlin. This + controls the + localtime5 + symlink. + + + + + + Sets the system + hostname. The argument should be a + host name, compatible with DNS. This + controls the + hostname5 + configuration file. + + + + + + Sets the system's machine ID. This + controls the + machine-id5 + file. + + + + + + + Sets the password of + the system's root user. This creates a + shadow5 + file. This setting exists in two + forms: + + accepts the password to set directly + on the command line, + + reads it from a file. Note that + it is not recommended specifying + passwords on the command line as other + users might be able to see them + simply by invoking + ps1. + + + + + + + + + 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. + + + + + + Query the user for locale, + timezone, hostname and root + password. This is equivalent to + specifiying + , + , + , + + in combination. + + + + + + + + Copy a specific basic setting + from the host. This only works in + combination with + (see + above). + + + + + + Copy locale, time zone and root + password from the host. This is + equivalent to specifiying + , + , + + in combination. + + + + + + Initialize the system's machine + ID to a random ID. This only works + combination with + . + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + See Also + + systemd1, + locale.conf5, + localtime5, + hostname5, + machine-id5, + shadow5, + systemd-machine-id-setup1, + localectl1, + timedatectl1, + hostnamectl1 + + + + diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 62630fbca..28352e357 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -81,13 +81,18 @@ UUID passed is sufficiently unique and is different for every booted instanced of the VM. - Similarly, if run inside a Linux container + Similar, if run inside a Linux container environment and a UUID is set for the container this is used to initialize the machine ID. For details see the documentation of the Container Interface. + Use + systemd-firstboot1 + to initialize the machine ID on mounted (but not + booted) system images. + @@ -123,7 +128,8 @@ systemd1, machine-id5, - dbus-uuidgen1 + dbus-uuidgen1, + systemd-firstboot1 diff --git a/man/timedatectl.xml b/man/timedatectl.xml index ee75d423d..fbd660080 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -60,6 +60,11 @@ timedatectl may be used to query and change the system clock and its settings. + + Use + systemd-firstboot1 + to initialize the system time zone for mounted (but not + booted) system images. @@ -240,7 +245,8 @@ chronyd.service - NTP client/server date1, localtime5, systemctl1, - systemd-timedated.service8 + systemd-timedated.service8, + systemd-firstboot1 -- 2.30.2