docs: hook up the new USER_NAMES document everywhere

(Also correct the set of names we accept in User=, which was forgotten
to be updated in ae480f0b09aec815b64579bb1828ea935d8ee236.

4 files changed, 18 insertions, 8 deletions

diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md
index 3bc0879a48..b9c21a1fea 100644
--- a/docs/USER_RECORD.md
+++ b/docs/USER_RECORD.md
@@ -205,7 +205,8 @@ object. The following fields are currently defined:
 UNIX user name. This field is the only mandatory field, all others are
 optional. Corresponds with the `pw_name` field of of `struct passwd` and the
 `sp_namp` field of `struct spwd` (i.e. the shadow user record stored in
-`/etc/shadow`).
+`/etc/shadow`). See [User/Group Name Syntax](https://systemd.io/USER_NAMES) for
+the (relaxed) rules the various systemd components enforce on user/group names.
 
 `realm` → The "realm" a user is defined in. This concept allows distinguishing
 users with the same name that originate in different organizations or
diff --git a/man/homectl.xml b/man/homectl.xml
index ae502c8ebb..2d99af93b1 100644
--- a/man/homectl.xml
+++ b/man/homectl.xml
@@ -677,7 +677,10 @@
 
         <listitem><para>Create a new home directory/user account of the specified name. Use the various
         user record property options (as documented above) to control various aspects of the home directory
-        and its user accounts.</para></listitem>
+        and its user accounts.</para>
+
+        <para>The specified user name should follow the strict syntax described on <ulink
+        url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 79a2c744c6..fd1755e422 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -217,12 +217,15 @@
         is set, the default group of the user is used. This setting does not affect commands whose command line is
         prefixed with <literal>+</literal>.</para>
 
-        <para>Note that restrictions on the user/group name syntax are enforced: the specified name must consist only
-        of the characters a-z, A-Z, 0-9, <literal>_</literal> and <literal>-</literal>, except for the first character
-        which must be one of a-z, A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted
-        as first character). The user/group name must have at least one character, and at most 31. These restrictions
-        are enforced in order to avoid ambiguities and to ensure user/group names and unit files remain portable among
-        Linux systems.</para>
+        <para>Note that this enforces only weak restrictions on the user/group name syntax, but will generate
+        warnings in many cases where user/group names do not adhere to the following rules: the specified
+        name should consist only of the characters a-z, A-Z, 0-9, <literal>_</literal> and
+        <literal>-</literal>, except for the first character which must be one of a-z, A-Z and
+        <literal>_</literal> (i.e. digits and <literal>-</literal> are not permitted as first character). The
+        user/group name must have at least one character, and at most 31. These restrictions are made in
+        order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux
+        systems. For further details on the names accepted and the names warned about see <ulink
+        url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para>
 
         <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
         dynamically allocated at the time the service is started, and released at the time the service is
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index c632e8713e..f0e0f2bedc 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -154,6 +154,9 @@ r     -        500-900
       A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted as first character). The
       user/group name must have at least one character, and at most 31.</para>
 
+      <para>For further details about the syntax of user/group names, see <ulink
+      url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para>
+
       <para>It is strongly recommended to pick user and group names that are unlikely to clash with normal users
       created by the administrator. A good scheme to guarantee this is by prefixing all system and group names with the
       underscore, and avoiding too generic names.</para>