systemd_service - Add the machine parameter (#82958)

systemctl's `--machine` option execute the operation in the context of a local
user session or a local container.

This provides a failsafe way to run systemd on behalf of another user than
setting the `XDG_RUNTIME_DIR` variable.

Signed-off-by: Jimmy Thrasibule <dev@jimmy.lt>

changelogs/fragments/82958-systemd_service-machine-parameter.yml

@@ -0,0 +1,5 @@
+---
+minor_changes:
+  - |-
+    systemd_service - Add the `machine` parameter to connect systemd to the
+    session bus of a specific user in a local container or on the local host.

lib/ansible/modules/systemd_service.py

@@ -78,6 +78,14 @@ options:
         type: bool
         default: no
         version_added: "2.3"
+    machine:
+        description:
+            - Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating `@` character.
+            - If the special string `.host` is used in place of the container name, a connection to the local system is made.
+            - If the `@` syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case
+              the local user name and `.host` are implied.
+        type: str
+        version_added: "2.17"
 extends_documentation_fragment: action_common_attributes
 attributes:
     check_mode:
@@ -147,6 +155,13 @@ EXAMPLES = '''
     scope: user
   environment:
     XDG_RUNTIME_DIR: "/run/user/{{ myuid }}"
+
+- name: Run from within a specific user session
+  ansible.builtin.systemd_service:
+    name: myservice
+    state: started
+    scope: user
+    machine: myuser@.host
 '''
 
 RETURN = '''
@@ -350,6 +365,7 @@ def main():
             daemon_reexec=dict(type='bool', default=False, aliases=['daemon-reexec']),
             scope=dict(type='str', default='system', choices=['system', 'user', 'global']),
             no_block=dict(type='bool', default=False),
+            machine=dict(type='str'),
         ),
         supports_check_mode=True,
         required_one_of=[['state', 'enabled', 'masked', 'daemon_reload', 'daemon_reexec']],
@@ -377,6 +393,9 @@ def main():
     if module.params['scope'] != 'system':
         systemctl += " --%s" % module.params['scope']
 
+    if module.params['machine']:
+        systemctl += " --machine=%s" % module.params['machine']
+
     if module.params['no_block']:
         systemctl += " --no-block"