man: briefly document permitted user/group name syntax for User=/Group= and syusers.d (#6321)

As discussed here:

https://lists.freedesktop.org/archives/systemd-devel/2017-July/039237.html

2 files changed, 33 insertions, 19 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index c31ab980fc..a4f92775ae 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -165,13 +165,28 @@
         <term><varname>Group=</varname></term>
 
         <listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single
-        user or group name, or numeric ID as argument. For system services (services run by the system service manager,
+        user or group name, or a numeric ID as argument. For system services (services run by the system service manager,
         i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of
         <command>systemd --user</command>), the default is <literal>root</literal>, but <varname>User=</varname> may be
         used to specify a different user. For user services of any other user, switching user identity is not
         permitted, hence the only valid setting is the same user the user's service manager is running as. If no group
         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></listitem>
+        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>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 stopped —
+        unless it is already allocated statically (see below). If <varname>DynamicUser=</varname> is not used the
+        specified user and group must have been created statically in the user database no later than the moment the
+        service is started, for example using the
+        <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> facility, which
+        is applied at boot or package install time.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index 18ee3800d6..f232d9906d 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -53,15 +53,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-sysusers</command> uses the files from
-    <filename>sysusers.d</filename> directory to create system users
-    and groups at package installation or boot time. This tool may be
-    used to allocate system users and groups only, it is not useful
-    for creating non-system users and groups, as it accesses
-    <filename>/etc/passwd</filename> and
-    <filename>/etc/group</filename> directly, bypassing any more
-    complex user databases, for example any database involving NIS or
-    LDAP.</para>
+    <para><command>systemd-sysusers</command> uses the files from <filename>sysusers.d</filename> directory to create
+    system users and groups at package installation or boot time. This tool may be used to allocate system users and
+    groups only, it is not useful for creating non-system (i.e. regular, "human") users and groups, as it accesses
+    <filename>/etc/passwd</filename> and <filename>/etc/group</filename> directly, bypassing any more complex user
+    databases, for example any database involving NIS or LDAP.</para>
   </refsect1>
 
   <refsect1>
@@ -83,6 +79,9 @@ g input - -
 m authd input
 u root 0 "Superuser" /root</programlisting>
 
+    <para>Empty lines and lines beginning with the <literal>#</literal> character are ignored, and may be used for
+    commenting.</para>
+
     <refsect2>
       <title>Type</title>
 
@@ -134,14 +133,14 @@ u root 0 "Superuser" /root</programlisting>
     <refsect2>
       <title>Name</title>
 
-      <para>The name field specifies the user or group name. It should
-      be shorter than 31 characters and avoid any non-ASCII
-      characters, and not begin with a numeric character. 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>
+      <para>The name field specifies the user or group name. 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.</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>
 
       <para>For <varname>m</varname> lines, this field should contain
       the user name to add to a group.</para>