rpm-sysusers - Man Page

%{_sysusersdir}/*.​conf
%{add_sysuser [-b] ENTRY}

ENTRY
# COMMENT

u USERNAME UID GECOS HOMEDIR SHELL
u USERNAME UID:GID GECOS HOMEDIR SHELL
u USERNAME FILE GECOS HOMEDIR SHELL
g GROUPNAME GID
g GROUPNAME FILE
m USERNAME GROUPNAME

• Suffix u with an exclamation mark (!​) to create a fully locked account (recommended)
• Use a dash (-) as UID/GID for automatic number allocation (recommended)
• FILE is an absolute path to a file whose UID/GID should be used

%__systemd_sysusers PATH

%_sysusersdir PATH

%add_sysusers [-b] ENTRY

By default, the generated virtual requires are hard dependencies.​ This can be problematic when upgrading an existing distribution to RPM 4.​19, however, so it is possible to weaken these requires into recommends, by setting %_use_weak_usergroup_deps to 1 in the rpmbuild-config(5).​

RPM will generate any combination of the following virtual provides based on, and attached to, the packaged sysusers.​d(5) file(s):

user(username) = base64
group(groupname) [= base64]
groupmember(username/groupname) = base64

base64 is a base64 encoded representation of the given sysusers.​d entry, with the input \0-padded as needed, in order to avoid the base64 native = padding in the output, which is illegal in an EVR string.​

For example, the following sysusers.​d entry:

  u dnsmasq - "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq

would emit the following provides attached to the originating file:

  user(dnsmasq) = dSBkbnNtYXNxIC0gIkRuc21hc3EgREhDUCBhbmQgRE5TIHNlcnZlciIgL3Zhci9saWIvZG5zbWFzcQAA
  group(dnsmasq)

As systemd-sysusers(8) implicitly creates a matching group for any created users, the group provides does not have an EVR here.​ Only explicitly created groups will have the encoded sysusers.​d entry as an EVR.​

Entries adding users to groups, such as:

  m klangd klong

will create a provides:

  groupmember(klangd/klong) = bSBrbGFuZ2Qga2xvbmcA

They will also create two requires (or recommends if %_use_weak_usergroup_deps is set to 1):

  group(klong)
  user(klangd)

to make sure the packages creating the user and group are installed first.​

When RPM installs a package with virtual provides as described in Encoding, it decodes their EVR strings back from base64 to the original sysusers.​d entries, and groups them by their source file.​ Then, it runs the systemd-sysusers(8) program once for each source file, with --replace pointing to the path of the source file when installed, and passes the decoded entries pertaining to that file on standard input.​ The program then creates new, or modifies existing, users and groups on the system, according to those entries.​

Since the above process happens before the payload is unpacked to disk, packages can ship files owned by their own users and groups.​

Virtual provides generated with the %add_sysuser macro in rpm-spec(5) files are package-level, with no source files to group them by.​ Thus, RPM does not use --replace when calling systemd-sysusers(8) for such entries.​ That may cause unintended behavior since the program then gives the entries on standard input higher priority than any sysusers.​d(5) overrides that the administrator may have configured on the system.​

Note that the packaged sysusers.​d(5) files, if any, are installed as normal, but do not participate in the user/group creation itself.​ They simply serve as static definition files for reconstructing /etc/passwd and /etc/group later, as per sysusers.​d(5).​

Consider a dnsmasq.​spec file with the following contents (irrelevant parts ellipsized or omitted):

  %install
  mkdir -p ${RPM_BUILD_ROOT}/%{_var}/lib/dnsmasq
  mkdir -p ${RPM_BUILD_ROOT}/%{_sysusersdir}
  cat << EOF > ${RPM_BUILD_ROOT}/%{_sysusersdir}/dnsmasq​.conf
  u dnsmasq - "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq
  EOF
  [​.​.​.]

%files
%dir %attr(0755,root,dnsmasq) %{_var}/lib/dnsmasq
%{_sysusersdir}/dnsmasq​.conf
[​.​.​.]

When the package is built, it will contain the following requires and provides:

  $ rpm -qp --requires /path/to/dnsmasq​.rpm
  group(dnsmasq)
  [​.​.​.]
  $ rpm -qp --provides /path/to/dnsmasq​.rpm
  group(dnsmasq)
  user(dnsmasq) = dSBkbnNtYXNxIC0gIkRuc21hc3EgREhDUCBhbmQgRE5TIHNlcnZlciIgL3Zhci9saWIvZG5zbWFzcQAA
  [​.​.​.]

Finally, when the package is installed, RPM will create the dnsmasq user and group automatically, and the /var/lib/dnsmasq directory installed by the package itself will be owned by that group as per the spec file:

  $ getent passwd dnsmasq
  dnsmasq:x:999:999:Dnsmasq DHCP and DNS server:/var/lib/dnsmasq:/usr/sbin/nologin
  $ getent group dnsmasq
  dnsmasq:x:999:
  $ stat -c ​'%G:%g​' /var/lib/dnsmasq
  dnsmasq:999

The original sysusers.​d(5) file will be installed as normal:

  $ rpm -ql dnsmasq | grep sysusers
  /usr/lib/sysusers​.d/dnsmasq​.conf
  $ cat /usr/lib/sysusers​.d/dnsmasq​.conf
  u dnsmasq - "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq

Consider a dnsmasq.​spec file with the following contents starting just below the preamble block (irrelevant parts ellipsized or omitted):

  %{add_sysuser u dnsmasq - "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq}
  [​.​.​.]

%files
%dir %attr(0755,root,dnsmasq) %{_var}/lib/dnsmasq
[​.​.​.]

Building and installing this package will have the same effect as described in Example 1.​ The only difference is that, in this example, no sysusers.​d(5) file is packaged or installed.​