core/manager: Deprecate StartAuxiliaryScope() method

The method was added with migration of resources in mind (e.g. process's
allocated memory will follow it to the new scope), however, such a
resource migration is not in cgroup semantics. The method may thus have
the intended users and others could be guided to StartTransientUnit().

Since this API was advertised in a regular release, start the removal
with a deprecation message to callers.
Eventually, the goal is to remove the method to clean up DBus API and
simplify code (removal of cgroup_context_copy()).

Part of DBus docs is retained to satisfy build checks.

NEWS

@@ -66,6 +66,9 @@ CHANGES WITH 257 in spe:
           filesystem. $SYSTEMD_NSPAWN_UNIFIED_HIERARCHY=0 can be used to override
           this behavior.
 
+        * D-Bus method org.freedesktop.systemd1.StartAuxiliaryScope() becomes
+          deprecated (reach out if you have use cases).
+
         libsystemd:
 
         * New sd-json component is now available as part of libsystemd. The

man/org.freedesktop.systemd1.xml

@@ -277,6 +277,7 @@ node /org/freedesktop/systemd1 {
       GetDynamicUsers(out a(us) users);
       DumpUnitFileDescriptorStore(in  s name,
                                   out a(suuutuusu) entries);
+      @org.freedesktop.DBus.Deprecated("true")
       StartAuxiliaryScope(in  s name,
                           in  ah pidfds,
                           in  t flags,
@@ -619,6 +620,8 @@ node /org/freedesktop/systemd1 {
 
     <!--method GetDynamicUsers is not documented!-->
 
+    <!--method StartAuxiliaryScope is not documented!-->
+
     <!--property SecurityStartTimestampMonotonic is not documented!-->
 
     <!--property SecurityFinishTimestamp is not documented!-->
@@ -1591,13 +1594,6 @@ node /org/freedesktop/systemd1 {
       to <function>DumpFileDescriptorStore()</function> on the
       <interfacename>org.freedesktop.systemd1.Service</interfacename>. For further details, see below.</para>
 
-      <para><function>StartAuxiliaryScope()</function> creates a new scope unit from a service where calling
-      process resides. Set of processes that will be migrated to newly created scope is passed in as an array
-      of pidfds. This is useful for creating auxiliary scopes that should contain worker processes and their lifecycle
-      shouldn't be bound to a lifecycle of the service, e.g. they should continue running after the restart
-      of the service. Note that the main PID of the service can not be migrated to an auxiliary scope.
-      Also, <varname>flags</varname> argument must be 0 and is reserved for future extensions.</para>
-
       <para><function>CleanUnit()</function> deletes the configuration, state, logs, cache and runtime data
       directories and clear out the file descriptors store for the unit, as specified in the mask
       parameters. The possible values are <literal>configuration</literal>, <literal>state</literal>,

src/core/dbus-manager.c

@@ -2914,6 +2914,7 @@ static int aux_scope_from_message(Manager *m, sd_bus_message *message, Unit **re
                 return sd_bus_error_setf(error, SD_BUS_ERROR_INVALID_ARGS,
                                          "Name \"%s\" of auxiliary scope doesn't have .scope suffix.", name);
 
+        log_unit_warning(from, "D-Bus call StartAuxiliaryScope() has been invoked which is deprecated.");
         main_pid = unit_main_pid(from);
 
         r = sd_bus_message_enter_container(message, 'a', "h");
@@ -3035,6 +3036,10 @@ static int method_start_aux_scope(sd_bus_message *message, void *userdata, sd_bu
         if (r == 0)
                 return 1; /* No authorization for now, but the async polkit stuff will call us again when it has it */
 
+        log_once(LOG_WARNING, "StartAuxiliaryScope() is deprecated because state of resources cannot be "
+                              "migrated between cgroups. Please report this to "
+                              "systemd-devel@lists.freedesktop.org or https://github.com/systemd/systemd/issues/ "
+                              "if you see this message and know the software making use of this functionality.");
         r = aux_scope_from_message(m, message, &u, error);
         if (r < 0)
                 return r;
@@ -3606,7 +3611,7 @@ const sd_bus_vtable bus_manager_vtable[] = {
                                 SD_BUS_ARGS("s", name, "ah", pidfds, "t", flags, "a(sv)", properties),
                                 SD_BUS_RESULT("o", job),
                                 method_start_aux_scope,
-                                SD_BUS_VTABLE_UNPRIVILEGED),
+                                SD_BUS_VTABLE_DEPRECATED|SD_BUS_VTABLE_UNPRIVILEGED),
 
         SD_BUS_SIGNAL_WITH_ARGS("UnitNew",
                                 SD_BUS_ARGS("s", id, "o", unit),