v255 batch

.github/workflows/unit_tests.sh

@@ -22,6 +22,7 @@ ADDITIONAL_DEPS=(
     python3-pefile
     python3-pyelftools
     python3-pyparsing
+    python3-pytest
     rpm
     zstd
 )

catalog/systemd.catalog.in

@@ -748,3 +748,23 @@ Compatibility support for System V services in systemd is deprecated. Please
 make sure to update the package in question to provide proper, native systemd
 unit files. Contact vendor if necessary. Compatibility support for System V
 services is deprecated and will be removed soon.
+
+-- 187c62eb1e7f463bb530394f52cb090f
+Subject: A Portable Service has been attached
+Defined-By: systemd
+Support: %SUPPORT_URL%
+Documentation: https://systemd.io/PORTABLE_SERVICES/
+
+A new Portable Service @PORTABLE_ROOT@ (with extensions: @PORTABLE_EXTENSION@) has
+been attached to the system and is now available for use. The list of attached
+Portable Services can be queried with 'portablectl list'.
+
+-- 76c5c754d628490d8ecba4c9d042112b
+Subject: A Portable Service has been detached
+Defined-By: systemd
+Support: %SUPPORT_URL%
+Documentation: https://systemd.io/PORTABLE_SERVICES/
+
+A Portable Service @PORTABLE_ROOT@ (with extensions: @PORTABLE_EXTENSION@) has been
+detached from the system and is no longer available for use. The list of attached
+Portable Services can be queried with 'portablectl list'.

docs/UIDS-GIDS.md

@@ -21,7 +21,7 @@ validity for GIDs too.
 In theory, the range of the C type `uid_t` is 32-bit wide on Linux,
 i.e. 0…4294967295. However, four UIDs are special on Linux:
 
-1. 0 → The `root` super-user
+1. 0 → The `root` super-user.
 
 2. 65534 → The `nobody` UID, also called the "overflow" UID or similar. It's
    where various subsystems map unmappable users to, for example file systems
@@ -57,20 +57,20 @@ Distributions generally split the available UID range in two:
 
 2. 1000…65533 and 65536…4294967294 → Everything else, i.e. regular (human) users.
 
-Note that most distributions allow changing the boundary between system and
-regular users, even during runtime as user configuration. Moreover, some older
-systems placed the boundary at 499/500, or even 99/100. In `systemd`, the
-boundary is configurable only during compilation time, as this should be a
-decision for distribution builders, not for users. Moreover, we strongly
-discourage downstreams to change the boundary from the upstream default of
-999/1000.
+Some older systems placed the boundary at 499/500, or even 99/100,
+and some distributions allow the boundary between system and regular users to be changed
+via local configuration.
+In `systemd`, the boundary is configurable during compilation time
+and is also queried from `/etc/login.defs` at runtime,
+if the `-Dcompat-mutable-uid-boundaries=true` compile-time setting is used.
+We strongly discourage downstreams from changing the boundary from the upstream default of 999/1000.
 
 Also note that programs such as `adduser` tend to allocate from a subset of the
-available regular user range only, usually 1000..60000. And it's also usually
-user-configurable, too.
+available regular user range only, usually 1000..60000.
+This range can also be configured using `/etc/login.defs`.
 
 Note that systemd requires that system users and groups are resolvable without
-networking available — a requirement that is not made for regular users. This
+network — a requirement that is not made for regular users. This
 means regular users may be stored in remote LDAP or NIS databases, but system
 users may not (except when there's a consistent local cache kept, that is
 available during earliest boot, including in the initrd).
@@ -155,15 +155,15 @@ The most important boundaries of the local system may be queried with
 `pkg-config`:
 
 ```
-$ pkg-config --variable=systemuidmax systemd
+$ pkg-config --variable=system_uid_max systemd
 999
-$ pkg-config --variable=dynamicuidmin systemd
+$ pkg-config --variable=dynamic_uid_min systemd
 61184
-$ pkg-config --variable=dynamicuidmax systemd
+$ pkg-config --variable=dynamic_uid_max systemd
 65519
-$ pkg-config --variable=containeruidbasemin systemd
+$ pkg-config --variable=container_uid_base_min systemd
 524288
-$ pkg-config --variable=containeruidbasemax systemd
+$ pkg-config --variable=container_uid_base_max systemd
 1878982656
 ```
 

man/meson.build

@@ -84,7 +84,7 @@ foreach tuple : manpages
                                         output : htmlalias,
                                         command : [ln, '-fs', html, '@OUTPUT@'])
                                 if want_html
-                                        meson.add_install_script(sh, '-c', ln_s.format(html, docdir / 'html' / htmlalias))
+                                        meson.add_install_script(sh, '-c', ln_s.format(docdir / 'html' / html, docdir / 'html' / htmlalias))
                                         p2 += link
                                 endif
                                 html_pages += link
@@ -155,7 +155,7 @@ foreach tuple : xsltproc.found() ? [['systemd.directives', '7', systemd_directiv
                         output : htmlalias,
                         command : [ln, '-fs', html, '@OUTPUT@'])
                 if want_html
-                        meson.add_install_script(sh, '-c', ln_s.format(html, docdir / 'html' / htmlalias))
+                        meson.add_install_script(sh, '-c', ln_s.format(docdir / 'html' / html, docdir / 'html' / htmlalias))
                         p2 += link
                 endif
                 html_pages += link

man/org.freedesktop.portable1.xml

@@ -249,7 +249,8 @@ node /org/freedesktop/portable1 {
         <listitem><para>mkdir</para></listitem>
       </itemizedlist>
       Note that an image cannot be attached if a unit that it contains is already present
-      on the system.</para>
+      on the system. Note that this method returns only after all the listed operations are completed,
+      and due to the I/O involved it might take some time.</para>
 
       <para><function>AttachImageWithExtensions()</function> attaches a portable image to the system.
       This method is a superset of <function>AttachImage()</function> with the addition of
@@ -271,7 +272,9 @@ node /org/freedesktop/portable1 {
       <itemizedlist>
         <listitem><para>unlink</para></listitem>
       </itemizedlist>
-      Note that an image cannot be detached if a unit that it contains is running.</para>
+      Note that an image cannot be detached if a unit that it contains is running. Note that this method
+      returns only after all the listed operations are completed, and due to the I/O involved it might take
+      some time.</para>
 
       <para><function>DetachImageWithExtensions()</function> detaches a portable image from the system.
       This method is a superset of <function>DetachImage()</function> with the addition of
@@ -307,11 +310,11 @@ node /org/freedesktop/portable1 {
       <para>The <function>AttachImageWithExtensions()</function>,
       <function>DetachImageWithExtensions()</function> and
       <function>ReattachImageWithExtensions()</function> methods take in options as flags instead of
-      booleans to allow for extendability. <varname>SD_SYSTEMD_PORTABLE_FORCE_ATTACH</varname> will cause
-      safety checks that ensure the units are not running while the new image is attached or detached
-      to be skipped. <varname>SD_SYSTEMD_PORTABLE_FORCE_EXTENSION</varname> will cause the check that the
+      booleans to allow for extendability. <varname>SD_SYSTEMD_PORTABLE_FORCE_ATTACH</varname> will bypass
+      the safety checks that ensure the units are not running while the image is attached or detached.
+      <varname>SD_SYSTEMD_PORTABLE_FORCE_EXTENSION</varname> will bypass the check that ensures the
       <filename>extension-release.<replaceable>NAME</replaceable></filename> file in the extension image
-      matches the image name to be skipped. They are defined as follows:</para>
+      matches the image name. They are defined as follows:</para>
 
       <programlisting>
 #define SD_SYSTEMD_PORTABLE_RUNTIME            (UINT64_C(1) &lt;&lt; 0)

man/org.freedesktop.systemd1.xml

@@ -1284,7 +1284,13 @@ node /org/freedesktop/systemd1 {
       and terminate all units that aren't dependencies of it. If <literal>ignore-dependencies</literal>, it
       will start a unit but ignore all its dependencies. If <literal>ignore-requirements</literal>, it will
       start a unit but only ignore the requirement dependencies. It is not recommended to make use of the
-      latter two options. On completion, this method returns the newly created job object.</para>
+      latter two options. On reply, if successful, this method returns the newly created job object
+      which has been enqueued for asynchronous activation. Callers that want to track the outcome of the
+      actual start operation need to monitor the result of this job. This can be achieved in a race-free
+      manner by first subscribing to the <function>JobRemoved()</function> signal, then calling
+      <function>StartUnit()</function> and using the returned job object to filter out unrelated
+      <function>JobRemoved()</function> signals, until the desired one is received, which will then carry
+      the result of the start operation.</para>
 
       <para><function>StartUnitReplace()</function> is similar to <function>StartUnit()</function> but
       replaces a job that is queued for one unit by a job for another unit.</para>

man/sd_bus_service_reconnect.c

@@ -0,0 +1,223 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* Implements a D-Bus service that automatically reconnects when the system bus is restarted.
+ *
+ * Compile with 'cc sd_bus_service_reconnect.c $(pkg-config --libs --cflags libsystemd)'
+ *
+ * To allow the program to take ownership of the name 'org.freedesktop.ReconnectExample',
+ * add the following as /etc/dbus-1/system.d/org.freedesktop.ReconnectExample.conf
+ * and then reload the broker with 'systemctl reload dbus':
+
+<?xml version="1.0"?> <!--*-nxml-*-->
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+        "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+        <policy user="root">
+                <allow own="org.freedesktop.ReconnectExample"/>
+                <allow send_destination="org.freedesktop.ReconnectExample"/>
+                <allow receive_sender="org.freedesktop.ReconnectExample"/>
+        </policy>
+
+        <policy context="default">
+                <allow send_destination="org.freedesktop.ReconnectExample"/>
+                <allow receive_sender="org.freedesktop.ReconnectExample"/>
+        </policy>
+</busconfig>
+
+ *
+ * To get the property via busctl:
+ *
+ * $ busctl --user get-property org.freedesktop.ReconnectExample \
+ *                              /org/freedesktop/ReconnectExample \
+ *                              org.freedesktop.ReconnectExample \
+ *                              Example
+ *   s "example"
+ */
+
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+#define check(x) ({                             \
+  int _r = (x);                                 \
+  errno = _r < 0 ? -_r : 0;                     \
+  printf(#x ": %m\n");                          \
+  if (_r < 0)                                   \
+    return EXIT_FAILURE;                        \
+  })
+
+typedef struct object {
+  const char *example;
+  sd_bus **bus;
+  sd_event **event;
+} object;
+
+static int property_get(
+                sd_bus *bus,
+                const char *path,
+                const char *interface,
+                const char *property,
+                sd_bus_message *reply,
+                void *userdata,
+                sd_bus_error *error) {
+
+  object *o = userdata;
+
+  if (strcmp(property, "Example") == 0)
+    return sd_bus_message_append(reply, "s", o->example);
+
+  return sd_bus_error_setf(error,
+                           SD_BUS_ERROR_UNKNOWN_PROPERTY,
+                           "Unknown property '%s'",
+                           property);
+}
+
+/* https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html */
+static const sd_bus_vtable vtable[] = {
+  SD_BUS_VTABLE_START(0),
+  SD_BUS_PROPERTY(
+    "Example", "s",
+    property_get,
+    0,
+    SD_BUS_VTABLE_PROPERTY_CONST),
+  SD_BUS_VTABLE_END
+};
+
+static int setup(object *o);
+
+static int on_disconnect(sd_bus_message *message, void *userdata, sd_bus_error *ret_error) {
+  check(setup((object *)userdata));
+  return 0;
+}
+
+/* Ensure the event loop exits with a clear error if acquiring the well-known service name fails */
+static int request_name_callback(sd_bus_message *m, void *userdata, sd_bus_error *ret_error) {
+  if (!sd_bus_message_is_method_error(m, NULL))
+    return 1;
+
+  const sd_bus_error *error = sd_bus_message_get_error(m);
+
+  if (sd_bus_error_has_names(error, SD_BUS_ERROR_TIMEOUT, SD_BUS_ERROR_NO_REPLY))
+    return 1; /* The bus is not available, try again later */
+
+  printf("Failed to request name: %s\n", error->message);
+  object *o = userdata;
+  check(sd_event_exit(*o->event, -sd_bus_error_get_errno(error)));
+
+  return 1;
+}
+
+static int setup(object *o) {
+  /* If we are reconnecting, then the bus object needs to be closed, detached from
+   * the event loop and recreated.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_detach_event.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_close_unref.html
+   */
+  if (*o->bus) {
+    check(sd_bus_detach_event(*o->bus));
+    *o->bus = sd_bus_close_unref(*o->bus);
+  }
+
+  /* Set up a new bus object for the system bus, configure it to wait for D-Bus to be available
+   * instead of failing if it is not, and start it. All the following operations are asyncronous
+   * and will not block waiting for D-Bus to be available.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_new.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_set_address.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_set_bus_client.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_negotiate_creds.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_set_watch_bind.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_set_connected_signal.html
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_start.html
+   */
+  check(sd_bus_new(o->bus));
+  check(sd_bus_set_address(*o->bus, "unix:path=/run/dbus/system_bus_socket"));
+  check(sd_bus_set_bus_client(*o->bus, 1));
+  check(sd_bus_negotiate_creds(*o->bus, 1, SD_BUS_CREDS_UID|SD_BUS_CREDS_EUID|SD_BUS_CREDS_EFFECTIVE_CAPS));
+  check(sd_bus_set_watch_bind(*o->bus, 1));
+  check(sd_bus_start(*o->bus));
+
+  /* Publish an interface on the bus, specifying our well-known object access
+   * path and public interface name.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html
+   * https://dbus.freedesktop.org/doc/dbus-tutorial.html
+   */
+  check(sd_bus_add_object_vtable(*o->bus,
+                                 NULL,
+                                 "/org/freedesktop/ReconnectExample",
+                                 "org.freedesktop.ReconnectExample",
+                                 vtable,
+                                 o));
+  /* By default the service is only assigned an ephemeral name. Also add a well-known
+   * one, so that clients know whom to call. This needs to be asynchronous, as
+   * D-Bus might not be yet available. The callback will check whether the error is
+   * expected or not, in case it fails.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html
+   */
+  check(sd_bus_request_name_async(*o->bus,
+                                  NULL,
+                                  "org.freedesktop.ReconnectExample",
+                                  0,
+                                  request_name_callback,
+                                  o));
+  /* When D-Bus is disconnected this callback will be invoked, which will
+   * set up the connection again. This needs to be asynchronous, as D-Bus might not
+   * yet be available.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_match_signal_async.html
+   */
+  check(sd_bus_match_signal_async(*o->bus,
+                                  NULL,
+                                  "org.freedesktop.DBus.Local",
+                                  NULL,
+                                  "org.freedesktop.DBus.Local",
+                                  "Disconnected",
+                                  on_disconnect,
+                                  NULL,
+                                  o));
+  /* Attach the bus object to the event loop so that calls and signals are processed.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_attach_event.html
+   */
+  check(sd_bus_attach_event(*o->bus, *o->event, 0));
+
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  /* The bus should be relinquished before the program terminates. The cleanup
+   * attribute allows us to do it nicely and cleanly whenever we exit the
+   * block.
+   */
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  _cleanup_(sd_event_unrefp) sd_event *event = NULL;
+  object o = {
+    .example = "example",
+    .bus = &bus,
+    .event = &event,
+  };
+
+  /* Create an event loop data structure, with default parameters.
+   * https://www.freedesktop.org/software/systemd/man/sd_event_default.html
+   */
+  check(sd_event_default(&event));
+
+  /* By default the event loop will terminate when all sources have disappeared, so
+   * we have to keep it 'occupied'. Register signal handling to do so.
+   * https://www.freedesktop.org/software/systemd/man/sd_event_add_signal.html
+   */
+  check(sd_event_add_signal(event, NULL, SIGINT|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL));
+  check(sd_event_add_signal(event, NULL, SIGTERM|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL));
+
+  check(setup(&o));
+
+  /* Enter the main loop, it will exit only on sigint/sigterm.
+   * https://www.freedesktop.org/software/systemd/man/sd_event_loop.html
+   */
+  check(sd_event_loop(event));
+
+  /* https://www.freedesktop.org/software/systemd/man/sd_bus_release_name.html */
+  check(sd_bus_release_name(bus, "org.freedesktop.ReconnectExample"));
+
+  return 0;
+}