1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="systemd-sysusers" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>systemd-sysusers</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>systemd-sysusers</refentrytitle> 16 <manvolnum>8</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>systemd-sysusers</refname> 21 <refname>systemd-sysusers.service</refname> 22 <refpurpose>Allocate system users and groups</refpurpose> 23 </refnamediv> 24 25 <refsynopsisdiv> 26 <cmdsynopsis> 27 <command>systemd-sysusers</command> 28 <arg choice="opt" rep="repeat">OPTIONS</arg> 29 <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> 30 </cmdsynopsis> 31 32 <para><filename>systemd-sysusers.service</filename></para> 33 </refsynopsisdiv> 34 35 <refsect1> 36 <title>Description</title> 37 38 <para><command>systemd-sysusers</command> creates system users and 39 groups, based on the file format and location specified in 40 <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 41 </para> 42 43 <para>If invoked with no arguments, it applies all directives from all files 44 found in the directories specified by 45 <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 46 When invoked with positional arguments, if option 47 <option>--replace=<replaceable>PATH</replaceable></option> is specified, arguments 48 specified on the command line are used instead of the configuration file 49 <replaceable>PATH</replaceable>. Otherwise, just the configuration specified by 50 the command line arguments is executed. The string <literal>-</literal> may be 51 specified instead of a filename to instruct <command>systemd-sysusers</command> 52 to read the configuration from standard input. If only the basename of a file is 53 specified, all configuration directories are searched for a matching file and 54 the file found that has the highest priority is executed.</para> 55 </refsect1> 56 57 <refsect1> 58 <title>Options</title> 59 60 <para>The following options are understood:</para> 61 62 <variablelist> 63 <varlistentry> 64 <term><option>--root=<replaceable>root</replaceable></option></term> 65 <listitem><para>Takes a directory path as an argument. All 66 paths will be prefixed with the given alternate 67 <replaceable>root</replaceable> path, including config search 68 paths. </para></listitem> 69 </varlistentry> 70 71 <varlistentry> 72 <term><option>--image=<replaceable>image</replaceable></option></term> 73 74 <listitem><para>Takes a path to a disk image file or block device node. If specified all operations 75 are applied to file system in the indicated disk image. This is similar to <option>--root=</option> 76 but operates on file systems stored in disk images or block devices. The disk image should either 77 contain just a file system or a set of file systems within a GPT partition table, following the 78 <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions 79 Specification</ulink>. For further information on supported disk images, see 80 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s 81 switch of the same name.</para></listitem> 82 </varlistentry> 83 84 <varlistentry> 85 <term><option>--replace=<replaceable>PATH</replaceable></option></term> 86 <listitem><para>When this option is given, one or more positional arguments 87 must be specified. All configuration files found in the directories listed in 88 <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> 89 will be read, and the configuration given on the command line will be 90 handled instead of and with the same priority as the configuration file 91 <replaceable>PATH</replaceable>.</para> 92 93 <para>This option is intended to be used when package installation scripts 94 are running and files belonging to that package are not yet available on 95 disk, so their contents must be given on the command line, but the admin 96 configuration might already exist and should be given higher priority. 97 </para> 98 99 <example> 100 <title>RPM installation script for radvd</title> 101 102 <programlisting>echo 'u radvd - "radvd daemon"' | \ 103 systemd-sysusers --replace=/usr/lib/sysusers.d/radvd.conf -</programlisting> 104 105 <para>This will create the radvd user as if 106 <filename>/usr/lib/sysusers.d/radvd.conf</filename> was already on disk. 107 An admin might override the configuration specified on the command line by 108 placing <filename>/etc/sysusers.d/radvd.conf</filename> or even 109 <filename>/etc/sysusers.d/00-overrides.conf</filename>.</para> 110 111 <para>Note that this is the expanded form, and when used in a package, this 112 would be written using a macro with "radvd" and a file containing the 113 configuration line as arguments.</para> 114 </example> 115 </listitem> 116 </varlistentry> 117 118 <varlistentry> 119 <term><option>--dry-run</option></term> 120 <listitem><para>Process the configuration and figure out what entries would be created, but don't 121 actually write anything.</para></listitem> 122 </varlistentry> 123 124 <varlistentry> 125 <term><option>--inline</option></term> 126 <listitem><para>Treat each positional argument as a separate configuration 127 line instead of a file name.</para></listitem> 128 </varlistentry> 129 130 <xi:include href="standard-options.xml" xpointer="cat-config" /> 131 <xi:include href="standard-options.xml" xpointer="no-pager" /> 132 <xi:include href="standard-options.xml" xpointer="help" /> 133 <xi:include href="standard-options.xml" xpointer="version" /> 134 </variablelist> 135 </refsect1> 136 137 <refsect1> 138 <title>Credentials</title> 139 140 <para><command>systemd-sysusers</command> supports the service credentials logic as implemented by 141 <varname>LoadCredential=</varname>/<varname>SetCredential=</varname> (see 142 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for 143 details). The following credentials are used when passed in:</para> 144 145 <variablelist> 146 <varlistentry> 147 <term><literal>passwd.hashed-password.<replaceable>user</replaceable></literal></term> 148 <listitem><para>A UNIX hashed password string to use for the specified user, when creating an entry 149 for it. This is particularly useful for the <literal>root</literal> user as it allows provisioning 150 the default root password to use via a unit file drop-in or from a container manager passing in this 151 credential. Note that setting this credential has no effect if the specified user account already 152 exists. This credential is hence primarily useful in first boot scenarios or systems that are fully 153 stateless and come up with an empty <filename>/etc/</filename> on every boot.</para></listitem> 154 </varlistentry> 155 156 <varlistentry> 157 <term><literal>passwd.plaintext-password.<replaceable>user</replaceable></literal></term> 158 159 <listitem><para>Similar to <literal>passwd.hashed-password.<replaceable>user</replaceable></literal> 160 but expect a literal, plaintext password, which is then automatically hashed before used for the user 161 account. If both the hashed and the plaintext credential are specified for the same user the 162 former takes precedence. It's generally recommended to specify the hashed version; however in test 163 environments with weaker requirements on security it might be easier to pass passwords in plaintext 164 instead.</para></listitem> 165 </varlistentry> 166 167 <varlistentry> 168 <term><literal>passwd.shell.<replaceable>user</replaceable></literal></term> 169 170 <listitem><para>Specifies the shell binary to use for the specified account when creating it.</para></listitem> 171 </varlistentry> 172 </variablelist> 173 174 <para>Note that by default the <filename>systemd-sysusers.service</filename> unit file is set up to 175 inherit the <literal>passwd.hashed-password.root</literal>, 176 <literal>passwd.plaintext-password.root</literal> and <literal>passwd.shell.root</literal> credentials 177 from the service manager. Thus, when invoking a container with an unpopulated <filename>/etc/</filename> 178 for the first time it is possible to configure the root user's password to be <literal>systemd</literal> 179 like this:</para> 180 181 <para><programlisting># systemd-nspawn --image=… --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' …</programlisting></para> 182 183 <para>Note again that the data specified in these credentials is consulted only when creating an account 184 for the first time, it may not be used for changing the password or shell of an account that already 185 exists.</para> 186 187 <para>Use <citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry> 188 for generating UNIX password hashes from the command line.</para> 189 </refsect1> 190 191 <refsect1> 192 <title>Exit status</title> 193 194 <para>On success, 0 is returned, a non-zero failure code 195 otherwise.</para> 196 </refsect1> 197 198 <refsect1> 199 <title>See Also</title> 200 <para> 201 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 202 <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 203 <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>, 204 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 205 <citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry> 206 </para> 207 </refsect1> 208 209</refentry> 210