From 60bcb45927f18de637c3c9d5d7cc13f0c974523c Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 14 Sep 2020 11:03:59 +0200
Subject: [PATCH] man: rework UMask= explanation

Mention the JSON user record stuff. Mention pam_umask explicitly.
Mention that UMask= of the per-user user@.service instance can be used
too.

Fixes: #16963
---
 man/systemd.exec.xml | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index d2279a9b9a..8be6a1aadd 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -863,12 +863,17 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
 
         <listitem><para>Controls the file mode creation mask. Takes an access mode in octal notation. See
         <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
-        details. Defaults to 0022 for system units. For units of the user service manager the default value
-        is inherited from the user instance (whose default is inherited from the system service manager, and
-        thus also is 0022). Hence changing the default value of a user instance, either via
-        <varname>UMask=</varname> or via a PAM module, will affect the user instance itself and all user
-        units started by the user instance unless a user unit has specified its own
-        <varname>UMask=</varname>.</para></listitem>
+        details. Defaults to 0022 for system units. For user units the default value is inherited from the
+        per-user service manager (whose default is in turn inherited from the system service manager, and
+        thus typically also is 0022 — unless overriden by a PAM module). In order to change the per-user mask
+        for all user services, consider setting the <varname>UMask=</varname> setting of the user's
+        <filename>user@.service</filename> system service instance. The per-user umask may also be set via
+        the <varname>umask</varname> field of a user's <ulink url="https://systemd.io/USER_RECORD">JSON User
+        Record</ulink> (for users managed by
+        <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        this field may be controlled via <command>homectl --umask=</command>). It may also be set via a PAM
+        module, such as <citerefentry
+        project='man-pages'><refentrytitle>pam_umask</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
       </varlistentry>
 
       <varlistentry>