<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="sysusers.d" conditional='ENABLE_SYSUSERS'
xmlns:xi="http://www.w3.org/2001/XInclude">
<para><filename>/etc/sysusers.d/*.conf</filename></para>
<para><filename>/run/sysusers.d/*.conf</filename></para>
<para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
+
+ <programlisting>
+#Type Name ID GECOS Home directory Shell
+u user_name uid "User Description" /home/dir /path/to/shell
+u user_name uid:gid "User Description" /home/dir /path/to/shell
+u user_name /file/owned/by/user "User Description" /home/dir /path/to/shell
+g group_name gid
+g group_name /file/owned/by/group
+m user_name group_name
+r - lowest-highest</programlisting>
</refsynopsisdiv>
<refsect1>
<programlisting>#Type Name ID GECOS Home directory Shell
u httpd 404 "HTTP User"
-u authd /usr/bin/authd "Authorization user"
+u _authd /usr/bin/authd "Authorization user"
u postgres - "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb
g input - -
-m authd input
-u root 0 "Superuser" /root /bin/zsh</programlisting>
+m _authd input
+u root 0 "Superuser" /root /bin/zsh
+r - 500-900
+</programlisting>
<para>Empty lines and lines beginning with the <literal>#</literal> character are ignored, and may be used for
commenting.</para>
<term><varname>g</varname></term>
<listitem><para>Create a system group of the specified name
should it not exist yet. Note that <varname>u</varname>
- implicitly create a matching group. The group will be
+ implicitly creates a matching group. The group will be
created with no password set.</para></listitem>
</varlistentry>
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>
<para>Only applies to lines of type <varname>u</varname> and should otherwise
be left unset (or <literal>-</literal>). It is recommended to omit this, unless
software strictly requires a home directory to be set.</para>
+
+ <para><command>systemd-sysusers</command> only sets the home directory record in the
+ user database. To actually create the directory, consider adding a corresponding
+ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ fragment.</para>
</refsect2>
<refsect2>
<refsect1>
<title>Specifiers</title>
- <para>Specifiers can be used in the "Name", "ID", "GECOS", "Home directory", and "Shell" fields.
- An unknown or unresolvable specifier is treated as invalid configuration.
- The following expansions are understood:</para>
- <table>
- <title>Specifiers available</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname="spec" />
- <colspec colname="mean" />
- <colspec colname="detail" />
- <thead>
- <row>
- <entry>Specifier</entry>
- <entry>Meaning</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>%b</literal></entry>
- <entry>Boot ID</entry>
- <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
- </row>
- <row>
- <entry><literal>%H</literal></entry>
- <entry>Host name</entry>
- <entry>The hostname of the running system.</entry>
- </row>
- <row>
- <entry><literal>%m</literal></entry>
- <entry>Machine ID</entry>
- <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
- </row>
- <row>
- <entry><literal>%T</literal></entry>
- <entry>Directory for temporary files</entry>
- <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
- </row>
- <row>
- <entry><literal>%v</literal></entry>
- <entry>Kernel release</entry>
- <entry>Identical to <command>uname -r</command> output.</entry>
- </row>
- <row>
- <entry><literal>%V</literal></entry>
- <entry>Directory for larger and persistent temporary files</entry>
- <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
- </row>
- <row>
- <entry><literal>%%</literal></entry>
- <entry>Escaped <literal>%</literal></entry>
- <entry>Single percent sign.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <para>Specifiers can be used in the <literal>Name</literal>, <literal>ID</literal>,
+ <literal>GECOS</literal>, <literal>Home directory</literal>, and <literal>Shell</literal> fields. An
+ unknown or unresolvable specifier is treated as invalid configuration. The following expansions are
+ understood:</para>
+
+ <table class='specifiers'>
+ <title>Specifiers available</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname="spec" />
+ <colspec colname="mean" />
+ <colspec colname="detail" />
+ <thead>
+ <row>
+ <entry>Specifier</entry>
+ <entry>Meaning</entry>
+ <entry>Details</entry>
+ </row>
+ </thead>
+ <tbody>
+ <xi:include href="standard-specifiers.xml" xpointer="a"/>
+ <xi:include href="standard-specifiers.xml" xpointer="b"/>
+ <xi:include href="standard-specifiers.xml" xpointer="B"/>
+ <xi:include href="standard-specifiers.xml" xpointer="H"/>
+ <xi:include href="standard-specifiers.xml" xpointer="l"/>
+ <xi:include href="standard-specifiers.xml" xpointer="m"/>
+ <xi:include href="standard-specifiers.xml" xpointer="o"/>
+ <xi:include href="standard-specifiers.xml" xpointer="T"/>
+ <xi:include href="standard-specifiers.xml" xpointer="v"/>
+ <xi:include href="standard-specifiers.xml" xpointer="V"/>
+ <xi:include href="standard-specifiers.xml" xpointer="w"/>
+ <xi:include href="standard-specifiers.xml" xpointer="W"/>
+ <xi:include href="standard-specifiers.xml" xpointer="percent"/>
+ </tbody>
+ </tgroup>
+ </table>
</refsect1>
<refsect1>