.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "RPM\-SYSUSERS" "7" "2026\-08\-31" "RPM 6.1.0"
.PP
.SH NAME
.PP
\fBrpm\-sysusers\fR \- RPM native allocation of users and groups through \fBsysusers.\&d\fR(5)
.PP
.SH SYNOPSIS
.PP
.SS Declaration
.PP
\fB%{_sysusersdir}\fR\fI/*.\&conf\fR
.br
\fB%{add_sysuser\fR [\fB\-b\fR] \fIENTRY\fR\fB}\fR
.PP
.SS File format
.PP
\fIENTRY\fR
.br
\fB#\fR \fICOMMENT\fR
.PP
.SS Entry format
.PP
\fBu\fR \fIUSERNAME\fR \fIUID\fR \fIGECOS\fR \fIHOMEDIR\fR \fISHELL\fR
.br
\fBu\fR \fIUSERNAME\fR \fIUID\fR\fB:\fR\fIGID\fR \fIGECOS\fR \fIHOMEDIR\fR \fISHELL\fR
.br
\fBu\fR \fIUSERNAME\fR \fIFILE\fR \fIGECOS\fR \fIHOMEDIR\fR \fISHELL\fR
.br
\fBg\fR \fIGROUPNAME\fR \fIGID\fR
.br
\fBg\fR \fIGROUPNAME\fR \fIFILE\fR
.br
\fBm\fR \fIUSERNAME\fR \fIGROUPNAME\fR
.PP
.SS Notes
.PP
.PD 0
.IP \(bu 4
Suffix \fBu\fR with an exclamation mark (\fB!\&\fR) to create a fully locked account
(recommended)
.IP \(bu 4
Use a dash (\fB\-\fR) as \fIUID\fR/\fIGID\fR for automatic number allocation (recommended)
.IP \(bu 4
\fIFILE\fR is an absolute path to a file whose UID/GID should be used
.PD
.PP
.SH DESCRIPTION
.PP
RPM has native support for declarative user and group creation by integrating
with the \fBsysusers.\&d\fR(5) format (introduced by systemd).\& Packagers only need to
drop one or more files to \fI/usr/lib/sysusers.\&d/\fR and RPM will handle the rest,
such as dependency generation and the invocation of \fBsystemd\-sysusers\fR(8) during
the build and installation, respectively.\&
.PP
Vendors on non\-systemd platforms can enable the feature by shipping any missing
tools and configuring RPM accordingly (see \fBPORTABILITY\fR for details).\&
.PP
Note that for certain types of systemd services (such as transient or socket
activated), it may be possible to avoid package level user/group allocation
altogether by using \fIDynamic Users\fR (see \fBDynamicUser=\fR in \fBsystemd.\&exec\fR(5) and
the URL in \fBSEE ALSO\fR for details).\&
.PP
Added: 4.\&19.\&0
.PP
.SH DEPENDENCIES
.PP
Packaged \fBsysusers.\&d\fR(5) files generate virtual provides for the users and/or
groups they define.\& Similarly, any non\-root ownership defined with \fB%attr()\fR or
\fB%defattr()\fR in an \fBrpm\-spec\fR(5) file generates virtual requires for the named
users and/or groups.\& Both dependencies complement each other to ensure correct
installation when a package relies on a user/group from another package.\&
.PP
Explicit group membership (the \fBm\fR sysusers.\&d directive) will also generate
virtual requires for both the user and the group name in the originating
package.\&
.PP
For more details on the mechanism itself, see \fBrpm\-dependency\-generators\fR(7).\&
.PP
.SH LIMITATIONS
.PP
Currently, RPM only supports the following sysusers.\&d directives:
.PD 0
.IP \(bu 4
\fBu\fR and \fBg\fR (Added: 4.\&19.\&0)
.IP \(bu 4
\fBm\fR (Added: 4.\&20.\&0)
.IP \(bu 4
\fBu!\&\fR (Added: 4.\&20.\&1)
.PD
.PP
Other directives, if used, will be ignored.\& If such are needed, the package has
to call \fBsystemd\-sysusers\fR(8) with the correct arguments manually.\&
.PP
.SH PORTABILITY
.PP
RPM provides a number of macros to enable vendors and packagers to implement the
declarative user and group integration on platforms that do not ship with the
default systemd tooling.\& Note, however, that some of these tunables may need
tweaking even on platforms with systemd.\&
.PP
.SS Vendors
.PP
\fB%__systemd_sysusers\fR \fIPATH\fR
.RS 4
Path to the \fBsystemd\-sysusers\fR(8) executable or a compatible program.\&
.PP
On systemd native platforms, set \fIPATH\fR to the \fBsystemd\-sysusers\fR(8)
program, typically at \fI/usr/bin/systemd\-sysusers\fR.\& Note that the program
may also be shipped by a standalone package with no systemd dependencies
(such as \fBsystemd\-standalone\-sysusers\fR on Fedora Linux) which makes it
useful in containers or similar environments.\&
.PP
RPM ships with a replacement shell script that calls the standard UNIX
tools such as \fBuseradd\fR(8) or \fBgroupadd\fR(8) for account creation.\& The
script is installed at \fB%{_rpmconfigdir}\fR\fI/sysusers.\&sh\fR and can be used
on platforms where the original program is not available.\&
.PP
On platforms without the standard UNIX account tools, a custom script or
program can be written, which must:
.PD 0
.IP \(bu 4
Process \fBsysusers.\&d\fR(5) entries on standard input
.IP \(bu 4
Create or modify users and groups accordingly
.IP \(bu 4
Never delete any users or groups
.IP \(bu 4
Handle the \fB\-\-root\fR and \fB\-\-replace\fR options like the original program
.IP \(bu 4
Avoid changing the host if \fB\-\-root\fR is used
.PD
.PP
.RE
\fB%_sysusersdir\fR \fIPATH\fR
.RS 4
Path to the drop\-in directory where packages are supposed to install the
\fBsysusers.\&d\fR(5) files.\& Defaults to \fI/usr/lib/sysusers.\&d\fR.\&
.PP
.RE
.SS Packagers
.PP
\fB%add_sysusers\fR [\fB\-b\fR] \fIENTRY\fR
.RS 4
Interpret \fIENTRY\fR as if written in a \fBsysusers.\&d\fR(5) file and expand to
a (bare) dependency string as described in \fBEncoding\fR.\& \fIENTRY\fR denotes
the individual fields passed as macro arguments.\&
.PP
When used with \fB\-b\fR, expand to a \fBb\fRare dependency string.\& This form can
be used to implement \fBrpm\-dependency\-generators\fR(7) for \fBsysusers.\&d\fR(5)
files.\& RPM ships with such a generator (\fIsysusers.\&attr\fR) installed by
default.\&
.PP
When used without \fB\-b\fR, expand to a dependency string and prefix it with
the appropriate dependency tag for use in \fBrpm\-spec\fR(5) files.\& This form
can be used in the (sub)package context of a spec file, to declare users
and/or groups directly, without having to package \fBsysusers.\&d\fR(5) files.\&
It is mainly intended for development purposes, and is discouraged
otherwise since it conflicts with the original \fBsysusers.\&d\fR(5) scheme
(see also \fBTECHNICAL DETAILS\fR).\&
.PP
.RE
.SH COMPATIBILITY
.PP
.SS Vendors
.PP
By default, the generated virtual requires are \fIhard\fR 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
\fB%_use_weak_usergroup_deps\fR to \fB1\fR in the \fBrpmbuild\-config\fR(5).\&
.PP
.SH TECHNICAL DETAILS
.SS Encoding
.PP
RPM will generate any combination of the following virtual provides based on,
and attached to, the packaged \fBsysusers.\&d\fR(5) file(s):
.PP
\fBuser(\fR\fIusername\fR\fB) = \fR\fIbase64\fR
.br
\fBgroup(\fR\fIgroupname\fR\fB) \fR[\fB= \fR\fIbase64\fR]
.br
\fBgroupmember(\fR\fIusername\fR\fB/\fR\fIgroupname\fR\fB) = \fR\fIbase64\fR
.PP
\fIbase64\fR is a base64 encoded representation of the given sysusers.\&d entry, with
the input \fB\e0\fR\-padded as needed, in order to avoid the base64 native \fB=\fR
padding in the output, which is illegal in an EVR string.\&
.PP
For example, the following sysusers.\&d entry:
.PP
.nf
.RS 4
u dnsmasq \- "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq
.fi
.RE
.PP
would emit the following provides attached to the originating file:
.PP
.nf
.RS 4
user(dnsmasq) = dSBkbnNtYXNxIC0gIkRuc21hc3EgREhDUCBhbmQgRE5TIHNlcnZlciIgL3Zhci9saWIvZG5zbWFzcQAA
group(dnsmasq)
.fi
.RE
.PP
As \fBsystemd\-sysusers\fR(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.\&
.PP
Entries adding users to groups, such as:
.PP
.nf
.RS 4
m klangd klong
.fi
.RE
.PP
will create a provides:
.PP
.nf
.RS 4
groupmember(klangd/klong) = bSBrbGFuZ2Qga2xvbmcA
.fi
.RE
.PP
They will also create two requires (or recommends if
\fB%_use_weak_usergroup_deps\fR is set to \fB1\fR):
.PP
.nf
.RS 4
group(klong)
user(klangd)
.fi
.RE
.PP
to make sure the packages creating the user and group are installed first.\&
.PP
.SS Decoding
.PP
When RPM installs a package with virtual provides as described in \fBENCODING\fR, 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 \fBsystemd\-sysusers\fR(8)
program once for each source file, with \fB\-\-replace\fR 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.\&
.PP
Since the above process happens before the payload is unpacked to disk, packages
can ship files owned by their own users and groups.\&
.PP
Virtual provides generated with the \fB%add_sysuser\fR macro in \fBrpm\-spec\fR(5) files
are package\-level, with no source files to group them by.\& Thus, RPM does not use
\fB\-\-replace\fR when calling \fBsystemd\-sysusers\fR(8) for such entries.\& That may cause
unintended behavior since the program then gives the entries on standard input
higher priority than any \fBsysusers.\&d\fR(5) overrides that the administrator may
have configured on the system.\&
.PP
Note that the packaged \fBsysusers.\&d\fR(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 \fB/etc/passwd\fR and \fB/etc/group\fR later,
as per \fBsysusers.\&d\fR(5).\&
.PP
.SH TROUBLESHOOTING
.PP
\fBrpm \-q \fR{\fB\-\-provides\fR|\fB\-\-requires\fR} \fIPACKAGE_NAME\fR \fB| grep
\&'\&\(ha\e(user(\e|group(\e|groupmember(\e)'\&\fR
.RS 4
Display the virtual user/group/groupmember provides/requires of
\fIPACKAGE_NAME\fR.\&
.PP
.RE
\fBrpm \-q \-\-queryformat '\&[%{SYSUSERS}\en]'\& \fR\fIPACKAGE_NAME\fR
.RS 4
Display the original sysusers.\&d entries decoded from the virtual
provides of \fIPACKAGE_NAME\fR by using \fBrpm\-queryformat\fR(7).\&
.PP
.RE
.SH EXAMPLES
.PP
.SS Example 1. Packaging a sysusers.d(5) file
.PP
Consider a \fIdnsmasq.\&spec\fR file with the following contents (irrelevant parts
ellipsized or omitted):
.PP
.nf
.RS 4
%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
[\&.\&.\&.]
.fi
.RE
.PP
When the package is built, it will contain the following requires and provides:
.PP
.nf
.RS 4
$ rpm \-qp \-\-requires /path/to/dnsmasq\&.rpm
group(dnsmasq)
[\&.\&.\&.]
$ rpm \-qp \-\-provides /path/to/dnsmasq\&.rpm
group(dnsmasq)
user(dnsmasq) = dSBkbnNtYXNxIC0gIkRuc21hc3EgREhDUCBhbmQgRE5TIHNlcnZlciIgL3Zhci9saWIvZG5zbWFzcQAA
[\&.\&.\&.]
.fi
.RE
.PP
Finally, when the package is installed, RPM will create the \fBdnsmasq\fR user and
group automatically, and the \fI/var/lib/dnsmasq\fR directory installed by the
package itself will be owned by that group as per the spec file:
.PP
.nf
.RS 4
$ 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
.fi
.RE
.PP
The original \fBsysusers.\&d\fR(5) file will be installed as normal:
.PP
.nf
.RS 4
$ 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
.fi
.RE
.PP
.SS Example 2. Declaring a sysusers.d entry manually
.PP
Consider a \fIdnsmasq.\&spec\fR file with the following contents starting just below
the preamble block (irrelevant parts ellipsized or omitted):
.PP
.nf
.RS 4
%{add_sysuser u dnsmasq \- "Dnsmasq DHCP and DNS server" /var/lib/dnsmasq}
[\&.\&.\&.]

%files
%dir %attr(0755,root,dnsmasq) %{_var}/lib/dnsmasq
[\&.\&.\&.]
.fi
.RE
.PP
Building and installing this package will have the same effect as described in
\fBExample 1\fR.\& The only difference is that, in this example, no \fBsysusers.\&d\fR(5)
file is packaged or installed.\&
.PP
.SH SEE ALSO
.PP
\fBrpm\fR(8),
\fBrpmbuild\-config\fR(5),
\fBrpm\-spec\fR(5),
\fBrpm\-scriptlets\fR(7),
\fBrpm\-dependency\-generators\fR(7),
\fBsysusers.\&d\fR(5),
\fBsystemd\-sysusers\fR(8),
\fBsystemd.\&exec\fR(5),
\fBuseradd\fR(8),
\fBgroupadd\fR(8)
.PP
\fBhttps://0pointer.\&net/blog/dynamic\-users\-with\-systemd.\&html\fR