Merge pull request #14968 from keszybz/docs

Assorted updates to documentation

docs/BOOT_LOADER_INTERFACE.md

@@ -142,3 +142,11 @@ names for them in UIs.
 6. If a boot menu entry encapsulates a reboot into EFI firmware setup feature,
    it should use the identifier `reboot-to-firmware-setup` (or
    `auto-reboot-to-firmware-setup` in case it is automatically discovered).
+
+## Links
+
+[Boot Loader Specification](https://systemd.io/BOOT_LOADER_INTERFACE)<br>
+[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br>
+[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
+[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
+[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

docs/BOOT_LOADER_SPECIFICATION.md

@@ -55,14 +55,14 @@ functionality. Here's why we think that it is not enough for our uses:
 
 Everything described below is located on a placeholder file system `$BOOT`. The installer program should pick `$BOOT` according to the following rules:
 
-* On disks with MBR disk labels
-  * If the OS is installed on a disk with MBR disk label, and a partition with the MBR type id of 0xEA already exists it should be used as `$BOOT`.
-  * Otherwise, if the OS is installed on a disk with MBR disk label, a new partition with MBR type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
-* On disks with GPT disk labels
-  * If the OS is installed on a disk with GPT disk label, and a partition with the GPT type GUID of `bc13c2ff-59e6-4262-a352-b275fd6f7172` already exists, it should be used as `$BOOT`.
-  * Otherwise, if the OS is installed on a disk with GPT disk label, and an ESP partition (i.e. with the GPT type UID of `c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
-  * Otherwise, if the OS is installed on a disk with GPT disk label, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) partition with GPT type GUID of `bc13c2ff-59e6-4262-a352-b275fd6f7172` shall be created and it should be used as `$BOOT`.
-  * Otherwise, if the OS is installed on a disk with GPT disk label, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and should be used as `$BOOT`.
+* On disks with an MBR partition table:
+  * If the OS is installed on a disk with an MBR partition table, and a partition with the type id of 0xEA already exists it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with an MBR partition table, a new partition with type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
+* On disks with GPT (GUID Partition Table)
+  * If the OS is installed on a disk with GPT, and an Extended Boot Loader Partition or XBOOTLDR partition for short, i.e. a partition with GPT type GUID of `bc13c2ff-59e6-4262-a352-b275fd6f7172`, already exists, it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT, and an EFI System Partition or ESP for short, i.e. a partition with GPT type UID of `c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) XBOOTLDR partition shall be created and used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and used as `$BOOT`.
 
 This placeholder file system shall be determined during _installation time_, and an fstab entry may be created. It should be mounted to either `/boot/` or `/efi/`. Additional locations like `/boot/efi/`, with `/boot/` being a separate file system, might be supported by implementations. This is not recommended because the mounting of `$BOOT` is then dependent on and requires the mounting of the intermediate file system.
 
@@ -234,5 +234,9 @@ There are a couple of items that are out of focus for this specification:
 
 ## Links
 
+[GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table)<br>
+[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)<br>
+[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br>
 [systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
-[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
+[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
+[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

man/environment.d.xml

@@ -36,11 +36,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para>The <filename>environment.d</filename> directories contain a list of "global" environment
-    variable assignments for the user environment.
+    <para>The <filename>environment.d</filename> directories contain a list of environment variable
+    assignments for services started by the systemd user instance.
     <citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    parses them and updates the environment exported by the systemd user instance to the services it
-    starts.</para>
+    parses them and updates the environment exported by the systemd user instance. See below for an
+    discussion of which processes inherit those variables.</para>
 
     <para>It is recommended to use numerical prefixes for file names to simplify ordering.</para>
 
@@ -89,6 +89,33 @@
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Applicability</title>
+
+    <para>Environment variables exported by the user manager (<command>systemd --user</command> instance
+    started in the <filename>user@<replaceable>uid</replaceable>.service</filename> system service) apply to
+    any services started by that manager. In particular, this may include services which run user shells. For
+    example in the Gnome environment, the graphical terminal emulator runs as the
+    <filename>gnome-terminal-server.service</filename> user unit, which in turn runs the user shell, so that
+    shell will inherit environment variables exported by the user manager. For other instances of the shell,
+    not launched by the user manager, the environment they inherit is defined by the program that starts
+    them. Hint: in general,
+    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    units contain programs launched by systemd, and
+    <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    units contain programs launched by something else.</para>
+
+    <para>Specifically, for ssh logins, the
+    <citerefentry project='die-net'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    service builds an environment that is a combination of variables forwarded from the remote system and
+    defined by <command>sshd</command>, see the discussion in
+    <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    A graphical display session will have an analogous mechanism to define the environment. Note that some
+    managers query the systemd user instance for the exported environment and inject this configuration into
+    programs they start, using <command>systemctl show-environment</command> or the underlying D-Bus call.
+    </para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>

man/rules/meson.build

@@ -670,8 +670,11 @@ manpages = [
  ['systemd-backlight@.service', '8', ['systemd-backlight'], 'ENABLE_BACKLIGHT'],
  ['systemd-binfmt.service', '8', ['systemd-binfmt'], 'ENABLE_BINFMT'],
  ['systemd-bless-boot-generator', '8', [], 'ENABLE_EFI'],
- ['systemd-bless-boot.service', '8', [], 'ENABLE_EFI'],
- ['systemd-boot-check-no-failures.service', '8', [], ''],
+ ['systemd-bless-boot.service', '8', ['systemd-bless-boot'], 'ENABLE_EFI'],
+ ['systemd-boot-check-no-failures.service',
+  '8',
+  ['systemd-boot-check-no-failures'],
+  ''],
  ['systemd-boot-system-token.service', '8', [], 'ENABLE_EFI'],
  ['systemd-boot', '7', ['sd-boot'], 'ENABLE_EFI'],
  ['systemd-cat', '1', [], ''],

man/systemd-bless-boot.service.xml

@@ -18,6 +18,7 @@
 
   <refnamediv>
     <refname>systemd-bless-boot.service</refname>
+    <refname>systemd-bless-boot</refname>
     <refpurpose>Mark current boot process as successful</refpurpose>
   </refnamediv>
 

man/systemd-boot-check-no-failures.service.xml

@@ -18,6 +18,7 @@
 
   <refnamediv>
     <refname>systemd-boot-check-no-failures.service</refname>
+    <refname>systemd-boot-check-no-failures</refname>
     <refpurpose>verify that the system booted up cleanly</refpurpose>
   </refnamediv>
 

man/user@.service.xml

@@ -49,7 +49,7 @@
     <para>User processes may be started by the <filename>user@.service</filename> instance, in which
     case they will be part of that unit in the system hierarchy. They may also be started elsewhere,
     for example by
-    <citerefentry><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry> or a
+    <citerefentry project='die-net'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry> or a
     display manager like <command>gdm</command>, in which case they form a .scope unit (see
     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
     Both <filename>user@<replaceable>UID</replaceable>.service</filename> and the scope units are
@@ -142,7 +142,7 @@ Control group /:
 …</programlisting>
       <para>User with UID 1000 is logged in using <command>gdm</command> (<filename
       index="false">session-4.scope</filename>) and
-      <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
       (<filename index="false">session-19.scope</filename>), and also has a user manager instance
       running (<filename index="false">user@1000.service</filename>).  User with UID 1001 is logged
       in using <command>ssh</command> (<filename index="false">session-20.scope</filename>) and

man/userdbctl.xml

@@ -228,7 +228,7 @@
     <para>The <command>userdbctl</command> tool may be used to make the list of SSH authorized keys possibly
     contained in a user record available to the SSH daemon for authentication. For that configure the
     following in <citerefentry
-    project='openssh'><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>:</para>
+    project='die-net'><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>:</para>
 
     <programlisting>…
 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u

meson.build

@@ -21,11 +21,13 @@ libudev_version = '1.6.17'
 # names, sometimes. Not all variables are included in every
 # set. Ugh, ugh, ugh!
 conf = configuration_data()
-conf.set('PROJECT_VERSION',        meson.project_version())
+conf.set('PROJECT_VERSION',        meson.project_version(),
+         description : 'Numerical project version (used where a simple number is expected)')
 
 substs = configuration_data()
 substs.set('PROJECT_URL',          'https://www.freedesktop.org/wiki/Software/systemd')
-substs.set('PROJECT_VERSION',      meson.project_version())
+substs.set('PROJECT_VERSION',      meson.project_version(),
+           description : 'Numerical project version (used where a simple number is expected)')
 
 # This is to be used instead of meson.source_root(), as the latter will return
 # the wrong result when systemd is being built as a meson subproject

src/version/version.h.in

@@ -1 +1,8 @@
+/* Detailed project version that includes git commit when not built from a release.
+ * Use this in preference to PROJECT_VERSION, with the following exceptions:
+ * - where a simplified form is expected for compatiblity, for example
+ *   'udevadm version',
+ * - where a simplified machine-parsable form is more useful, for example
+ *   pkgconfig files and version information written to binary files.
+ */
 #define GIT_VERSION "@VCS_TAG@"