]>
Commit | Line | Data |
---|---|---|
ea7a19e9 LP |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
ea7a19e9 LP |
5 | |
6 | <refentry id="homectl" conditional='ENABLE_HOMED' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
10 | <title>homectl</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>homectl</refentrytitle> | |
16 | <manvolnum>1</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>homectl</refname> | |
3ccadbce | 21 | <refname>systemd-homed-firstboot.service</refname> |
ea7a19e9 LP |
22 | <refpurpose>Create, remove, change or inspect home directories</refpurpose> |
23 | </refnamediv> | |
24 | ||
25 | <refsynopsisdiv> | |
26 | <cmdsynopsis> | |
27 | <command>homectl</command> | |
28 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
29 | <arg choice="req">COMMAND</arg> | |
30 | <arg choice="opt" rep="repeat">NAME</arg> | |
31 | </cmdsynopsis> | |
32 | </refsynopsisdiv> | |
33 | ||
34 | <refsect1> | |
35 | <title>Description</title> | |
36 | ||
37 | <para><command>homectl</command> may be used to create, remove, change or inspect a user's home | |
38 | directory. It's primarily a command interfacing with | |
39 | <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
40 | which manages home directories of users.</para> | |
41 | ||
42 | <para>Home directories managed by <filename>systemd-homed.service</filename> are self-contained, and thus | |
2a4be3c5 ZJS |
43 | include the user's full metadata record in the home's data storage itself, making them easy to migrate |
44 | between machines. In particular, a home directory describes a matching user record, and every user record | |
45 | managed by <filename>systemd-homed.service</filename> also implies existence and encapsulation of a home | |
46 | directory. The user account and home directory become the same concept.</para> | |
47 | ||
48 | <para>The following backing storage mechanisms are supported:</para> | |
ea7a19e9 LP |
49 | |
50 | <itemizedlist> | |
2a4be3c5 ZJS |
51 | <listitem><para>An individual LUKS2 encrypted loopback file for a user, stored in |
52 | <filename>/home/*.home</filename>. At login the file system contained in this files is mounted, after | |
53 | the LUKS2 encrypted volume has been attached. The user's password is identical to the encryption | |
86b52a39 | 54 | passphrase of the LUKS2 volume. Access to data without preceding user authentication is thus not |
2a4be3c5 | 55 | possible, even for the system administrator. This storage mechanism provides the strongest data |
ea7a19e9 LP |
56 | security and is thus recommended.</para></listitem> |
57 | ||
58 | <listitem><para>Similar, but the LUKS2 encrypted file system is located on regular block device, such | |
5bc9ea07 | 59 | as a USB storage stick. In this mode home directories and all data they include are nicely migratable |
ea7a19e9 LP |
60 | between machines, simply by plugging the USB stick into different systems at different |
61 | times.</para></listitem> | |
62 | ||
63 | <listitem><para>An encrypted directory using <literal>fscrypt</literal> on file systems that support it | |
64 | (at the moment this is primarily <literal>ext4</literal>), located in | |
65 | <filename>/home/*.homedir</filename>. This mechanism also provides encryption, but substantially | |
2a4be3c5 | 66 | weaker than LUKS2, as most file system metadata is unprotected. Moreover |
ea7a19e9 LP |
67 | it currently does not support changing user passwords once the home directory has been |
68 | created.</para></listitem> | |
69 | ||
70 | <listitem><para>A <literal>btrfs</literal> subvolume for each user, also located in | |
71 | <filename>/home/*.homedir</filename>. This provides no encryption, but good quota | |
72 | support.</para></listitem> | |
73 | ||
74 | <listitem><para>A regular directory for each user, also located in | |
75 | <filename>/home/*.homedir</filename>. This provides no encryption, but is a suitable fallback | |
76 | available on all machines, even where LUKS2, <literal>fscrypt</literal> or <literal>btrfs</literal> | |
77 | support is not available.</para></listitem> | |
78 | ||
79 | <listitem><para>An individual Windows file share (CIFS) for each user.</para></listitem> | |
80 | </itemizedlist> | |
81 | ||
82 | <para>Note that <filename>systemd-homed.service</filename> and <command>homectl</command> will not manage | |
83 | "classic" UNIX user accounts as created with <citerefentry | |
84 | project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry> or | |
85 | similar tools. In particular, this functionality is not suitable for managing system users (i.e. users | |
86 | with a UID below 1000) but is exclusive to regular ("human") users.</para> | |
87 | ||
88 | <para>Note that users/home directories managed via <command>systemd-homed.service</command> do not show | |
89 | up in <filename>/etc/passwd</filename> and similar files, they are synthesized via glibc NSS during | |
90 | runtime. They are thus resolvable and may be enumerated via the <citerefentry | |
91 | project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
92 | tool.</para> | |
93 | ||
94 | <para>This tool interfaces directly with <filename>systemd-homed.service</filename>, and may execute | |
95 | specific commands on the home directories it manages. Since every home directory managed that way also | |
96 | defines a JSON user and group record these home directories may also be inspected and enumerated via | |
97 | <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> | |
98 | ||
99 | <para>Home directories managed by <filename>systemd-homed.service</filename> are usually in one of two | |
100 | states, or in a transition state between them: when <literal>active</literal> they are unlocked and | |
101 | mounted, and thus accessible to the system and its programs; when <literal>inactive</literal> they are | |
2a4be3c5 | 102 | not mounted and thus not accessible. Activation happens automatically at login of the user and usually |
ea7a19e9 LP |
103 | can only complete after a password (or other authentication token) has been supplied. Deactivation |
104 | happens after the user fully logged out. A home directory remains active as long as the user is logged in | |
105 | at least once, i.e. has at least one login session. When the user logs in a second time simultaneously | |
106 | the home directory remains active. It is deactivated only after the last of the user's sessions | |
107 | ends.</para> | |
108 | </refsect1> | |
109 | ||
110 | <refsect1> | |
111 | <title>Options</title> | |
112 | ||
113 | <para>The following general options are understood (further options that control the various properties | |
114 | of user records managed by <filename>systemd-homed.service</filename> are documented further | |
115 | down):</para> | |
116 | ||
117 | <variablelist> | |
118 | ||
119 | <varlistentry> | |
120 | <term><option>--identity=</option><replaceable>FILE</replaceable></term> | |
121 | ||
122 | <listitem><para>Read the user's JSON record from the specified file. If passed as | |
e9dd6984 | 123 | <literal>-</literal> read the user record from standard input. The supplied JSON object must follow |
885a4e6c | 124 | the structure documented in <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink>. |
e9dd6984 | 125 | This option may be used in conjunction with the <command>create</command> and |
ea7a19e9 | 126 | <command>update</command> commands (see below), where it allows configuring the user record in JSON |
ec07c3c8 AK |
127 | as-is, instead of setting the individual user record properties (see below).</para> |
128 | ||
129 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
130 | </varlistentry> |
131 | ||
132 | <varlistentry> | |
133 | <term><option>--json=</option><replaceable>FORMAT</replaceable></term> | |
2a703778 | 134 | <term><option>-j</option></term> |
ea7a19e9 LP |
135 | |
136 | <listitem><para>Controls whether to output the user record in JSON format, if the | |
137 | <command>inspect</command> command (see below) is used. Takes one of <literal>pretty</literal>, | |
138 | <literal>short</literal> or <literal>off</literal>. If <literal>pretty</literal> human-friendly | |
139 | whitespace and newlines are inserted in the output to make the JSON data more readable. If | |
140 | <literal>short</literal> all superfluous whitespace is suppressed. If <literal>off</literal> (the | |
141 | default) the user information is not shown in JSON format but in a friendly human readable formatting | |
2a703778 | 142 | instead. The <option>-j</option> option picks <literal>pretty</literal> when run interactively and |
aefdc112 AK |
143 | <literal>short</literal> otherwise.</para> |
144 | ||
145 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
146 | </varlistentry> |
147 | ||
148 | <varlistentry> | |
149 | <term><option>--export-format=</option><replaceable>FORMAT</replaceable></term> | |
150 | <term><option>-E</option></term> | |
151 | <term><option>-EE</option></term> | |
152 | ||
153 | <listitem><para>When used with the <command>inspect</command> verb in JSON mode (see above) may be | |
154 | used to suppress certain aspects of the JSON user record on output. Specifically, if | |
155 | <literal>stripped</literal> format is used the binding and runtime fields of the record are | |
156 | removed. If <literal>minimal</literal> format is used the cryptographic signature is removed too. If | |
157 | <literal>full</literal> format is used the full JSON record is shown (this is the default). This | |
158 | option is useful for copying an existing user record to a different system in order to create a | |
159 | similar user there with the same settings. Specifically: <command>homectl inspect -EE | ssh | |
160 | root@othersystem homectl create -i-</command> may be used as simple command line for replicating a | |
161 | user on another host. <option>-E</option> is equivalent to <option>-j --export-format=stripped</option>, | |
162 | <option>-EE</option> to <option>-j --export-format=minimal</option>. Note that when replicating user | |
163 | accounts user records acquired in <literal>stripped</literal> mode will retain the original | |
2a4be3c5 ZJS |
164 | cryptographic signatures and thus may only be modified when the private key to update them is available |
165 | on the destination machine. When replicating users in <literal>minimal</literal> mode, the signature | |
166 | is removed during the replication and thus the record will be implicitly signed with the key of the destination | |
ec07c3c8 AK |
167 | machine and may be updated there without any private key replication.</para> |
168 | ||
169 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
170 | </varlistentry> |
171 | ||
172 | <xi:include href="user-system-options.xml" xpointer="host" /> | |
173 | <xi:include href="user-system-options.xml" xpointer="machine" /> | |
174 | ||
175 | <xi:include href="standard-options.xml" xpointer="no-pager" /> | |
176 | <xi:include href="standard-options.xml" xpointer="no-legend" /> | |
177 | <xi:include href="standard-options.xml" xpointer="no-ask-password" /> | |
178 | <xi:include href="standard-options.xml" xpointer="help" /> | |
179 | <xi:include href="standard-options.xml" xpointer="version" /> | |
180 | </variablelist> | |
181 | </refsect1> | |
182 | ||
183 | <refsect1> | |
184 | <title>User Record Properties</title> | |
185 | ||
186 | <para>The following options control various properties of the user records/home directories that | |
187 | <filename>systemd-homed.service</filename> manages. These switches may be used in conjunction with the | |
188 | <command>create</command> and <command>update</command> commands for configuring various aspects of the | |
189 | home directory and the user account:</para> | |
190 | ||
191 | <variablelist> | |
192 | ||
193 | <varlistentry> | |
194 | <term><option>--real-name=</option><replaceable>NAME</replaceable></term> | |
195 | <term><option>-c</option> <replaceable>NAME</replaceable></term> | |
196 | ||
197 | <listitem><para>The real name for the user. This corresponds with the GECOS field on classic UNIX NSS | |
ec07c3c8 AK |
198 | records.</para> |
199 | ||
200 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
201 | </varlistentry> |
202 | ||
203 | <varlistentry> | |
204 | <term><option>--realm=</option><replaceable>REALM</replaceable></term> | |
205 | ||
206 | <listitem><para>The realm for the user. The realm associates a user with a specific organization or | |
d008666a | 207 | installation, and allows distinguishing users of the same name defined in different contexts. The |
ea7a19e9 LP |
208 | realm can be any string that also qualifies as valid DNS domain name, and it is recommended to use |
209 | the organization's or installation's domain name for this purpose, but this is not enforced nor | |
210 | required. On each system only a single user of the same name may exist, and if a user with the same | |
211 | name and realm is seen it is assumed to refer to the same user while a user with the same name but | |
212 | different realm is considered a different user. Note that this means that two users sharing the same | |
213 | name but with distinct realms are not allowed on the same system. Assigning a realm to a user is | |
ec07c3c8 AK |
214 | optional.</para> |
215 | ||
216 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
217 | </varlistentry> |
218 | ||
219 | <varlistentry> | |
220 | <term><option>--email-address=</option><replaceable>EMAIL</replaceable></term> | |
221 | ||
222 | <listitem><para>Takes an electronic mail address to associate with the user. On log-in the | |
ec07c3c8 AK |
223 | <varname>$EMAIL</varname> environment variable is initialized from this value.</para> |
224 | ||
225 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
226 | </varlistentry> |
227 | ||
228 | <varlistentry> | |
229 | <term><option>--location=</option><replaceable>TEXT</replaceable></term> | |
230 | ||
231 | <listitem><para>Takes location specification for this user. This is free-form text, which might or | |
232 | might not be usable by geo-location applications. Example: <option>--location="Berlin, | |
ec07c3c8 AK |
233 | Germany"</option> or <option>--location="Basement, Room 3a"</option></para> |
234 | ||
235 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
236 | </varlistentry> |
237 | ||
238 | <varlistentry> | |
239 | <term><option>--icon-name=</option><replaceable>ICON</replaceable></term> | |
240 | ||
241 | <listitem><para>Takes an icon name to associate with the user, following the scheme defined by the <ulink | |
242 | url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon Naming | |
ec07c3c8 AK |
243 | Specification</ulink>.</para> |
244 | ||
245 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
246 | </varlistentry> |
247 | ||
248 | <varlistentry> | |
249 | <term><option>--home-dir=</option><replaceable>PATH</replaceable></term> | |
250 | <term><option>-d</option><replaceable>PATH</replaceable></term> | |
251 | ||
252 | <listitem><para>Takes a path to use as home directory for the user. Note that this is the directory | |
253 | the user's home directory is mounted to while the user is logged in. This is not where the user's | |
254 | data is actually stored, see <option>--image-path=</option> for that. If not specified defaults to | |
ec07c3c8 AK |
255 | <filename>/home/$USER</filename>.</para> |
256 | ||
257 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
258 | </varlistentry> |
259 | ||
260 | <varlistentry> | |
261 | <term><option>--uid=</option><replaceable>UID</replaceable></term> | |
262 | ||
263 | <listitem><para>Takes a preferred numeric UNIX UID to assign this user. If a user is to be created | |
264 | with the specified UID and it is already taken by a different user on the local system then creation | |
265 | of the home directory is refused. Note though, if after creating the home directory it is used on a | |
266 | different system and the configured UID is taken by another user there, then | |
267 | <command>systemd-homed</command> may assign the user a different UID on that system. The specified | |
268 | UID must be outside of the system user range. It is recommended to use the 60001…60513 UID range for | |
e9dd6984 ZJS |
269 | this purpose. If not specified, the UID is automatically picked. If the home directory is found to be |
270 | owned by a different UID when logging in, the home directory and everything underneath it will have | |
271 | its ownership changed automatically before login completes.</para> | |
ea7a19e9 | 272 | |
d33121d2 LP |
273 | <para>Note that changing this option for existing home directories generally has no effect on home |
274 | directories that already have been registered locally (have a local <emphasis>binding</emphasis>), as | |
275 | the UID used for an account on the local system is determined when the home directory is first | |
276 | activated on it, and then remains in effect until the home directory is removed.</para> | |
277 | ||
ea7a19e9 LP |
278 | <para>Note that users managed by <command>systemd-homed</command> always have a matching group |
279 | associated with the same name as well as a GID matching the UID of the user. Thus, configuring the | |
ec07c3c8 AK |
280 | GID separately is not permitted.</para> |
281 | ||
282 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
283 | </varlistentry> |
284 | ||
285 | <varlistentry> | |
286 | <term><option>--member-of=</option><replaceable>GROUP</replaceable></term> | |
287 | <term><option>-G</option> <replaceable>GROUP</replaceable></term> | |
288 | ||
289 | <listitem><para>Takes a comma-separated list of auxiliary UNIX groups this user shall belong | |
290 | to. Example: <option>--member-of=wheel</option> to provide the user with administrator | |
291 | privileges. Note that <command>systemd-homed</command> does not manage any groups besides a group | |
292 | matching the user in name and numeric UID/GID. Thus any groups listed here must be registered | |
293 | independently, for example with <citerefentry | |
e9dd6984 ZJS |
294 | project='man-pages'><refentrytitle>groupadd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
295 | Any non-existent groups are ignored. This option may be used more than once, in which case all | |
296 | specified group lists are combined. If the user is currently a member of a group which is not listed, | |
ec07c3c8 AK |
297 | the user will be removed from the group.</para> |
298 | ||
299 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
300 | </varlistentry> |
301 | ||
fada2c75 LP |
302 | <varlistentry> |
303 | <term><option>--capability-bounding-set=</option><replaceable>CAPABILITIES</replaceable></term> | |
304 | <term><option>--capability-ambient-set=</option><replaceable>CAPABILITIES</replaceable></term> | |
305 | ||
306 | <listitem><para>These options take a space separated list of process capabilities | |
307 | (e.g. <constant>CAP_WAKE_ALARM</constant>, <constant>CAP_BLOCK_SUSPEND</constant>, …) that shall be | |
308 | set in the capability bounding and ambient sets for all the user's sessions. See <citerefentry | |
309 | project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
310 | for details on the capabilities concept. These options may be used more than once, in which case the | |
311 | specified lists are combined. If the parameter begins with a <literal>~</literal> character the | |
ec07c3c8 AK |
312 | effect is inverted: the specified capability is dropped from the specific set.</para> |
313 | ||
314 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
fada2c75 LP |
315 | </varlistentry> |
316 | ||
ea7a19e9 LP |
317 | <varlistentry> |
318 | <term><option>--skel=</option><replaceable>PATH</replaceable></term> | |
319 | ||
320 | <listitem><para>Takes a file system path to a directory. Specifies the skeleton directory to | |
e9dd6984 ZJS |
321 | initialize the home directory with. All files and directories in the specified path are copied into |
322 | any newly create home directory. If not specified defaults to <filename>/etc/skel/</filename>. | |
ec07c3c8 AK |
323 | </para> |
324 | ||
325 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
326 | </varlistentry> |
327 | ||
328 | <varlistentry> | |
329 | <term><option>--shell=</option><replaceable>SHELL</replaceable></term> | |
330 | ||
331 | <listitem><para>Takes a file system path. Specifies the shell binary to execute on terminal | |
ec07c3c8 AK |
332 | logins. If not specified defaults to <filename>/bin/bash</filename>.</para> |
333 | ||
334 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
335 | </varlistentry> |
336 | ||
337 | <varlistentry> | |
4bbafcc3 | 338 | <term><option>--setenv=</option><replaceable>VARIABLE</replaceable>[=<replaceable>VALUE</replaceable>]</term> |
ea7a19e9 | 339 | |
4bbafcc3 ZJS |
340 | <listitem><para>Takes an environment variable assignment to set for all user processes. May be used |
341 | multiple times to set multiple environment variables. When <literal>=</literal> and | |
342 | <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the | |
343 | program environment will be used.</para> | |
344 | ||
345 | <para>Note that a number of other settings also result in environment variables to be set for the | |
346 | user, including <option>--email=</option>, <option>--timezone=</option> and | |
ec07c3c8 AK |
347 | <option>--language=</option>.</para> |
348 | ||
aefdc112 | 349 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> |
ea7a19e9 LP |
350 | </varlistentry> |
351 | ||
352 | <varlistentry> | |
353 | <term><option>--timezone=</option><replaceable>TIMEZONE</replaceable></term> | |
354 | ||
7fd897c5 ZJS |
355 | <listitem><para>Takes a time zone location name that sets the timezone for the specified user. When |
356 | the user logs in the <varname>$TZ</varname> environment variable is initialized from this | |
357 | setting. Example: <option>--timezone=Europe/Amsterdam</option> will result in the environment | |
358 | variable <literal>TZ=:Europe/Amsterdam</literal>. (<literal>:</literal> is used intentionally as part | |
359 | of the timezone specification, see | |
21556381 | 360 | <citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>.) |
ec07c3c8 AK |
361 | </para> |
362 | ||
363 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
364 | </varlistentry> |
365 | ||
366 | <varlistentry> | |
367 | <term><option>--language=</option><replaceable>LANG</replaceable></term> | |
368 | ||
49e55abb AV |
369 | <listitem><para>Takes a comma- or colon-separated list of languages preferred by the user, ordered |
370 | by descending priority. The <varname>$LANG</varname> and <varname>$LANGUAGE</varname> environment | |
371 | variables are initialized from this value on login, and thus values suitible for these environment | |
372 | variables are accepted here, for example <option>--language=de_DE.UTF-8</option>. This option may | |
373 | be used more than once, in which case the language lists are concatenated.</para> | |
ec07c3c8 AK |
374 | |
375 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
376 | </varlistentry> |
377 | ||
378 | <varlistentry> | |
379 | <term><option>--ssh-authorized-keys=</option><replaceable>KEYS</replaceable></term> | |
380 | <listitem><para>Either takes a SSH authorized key line to associate with the user record or a | |
381 | <literal>@</literal> character followed by a path to a file to read one or more such lines from. SSH | |
382 | keys configured this way are made available to SSH to permit access to this home directory and user | |
ec07c3c8 AK |
383 | record. This option may be used more than once to configure multiple SSH keys.</para> |
384 | ||
385 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
386 | </varlistentry> |
387 | ||
388 | <varlistentry> | |
389 | <term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term> | |
390 | <listitem><para>Takes an RFC 7512 PKCS#11 URI referencing a security token (e.g. YubiKey or PIV | |
391 | smartcard) that shall be able to unlock the user account. The security token URI should reference a | |
392 | security token with exactly one pair of X.509 certificate and private key. A random secret key is | |
393 | then generated, encrypted with the public key of the X.509 certificate, and stored as part of the | |
394 | user record. At login time it is decrypted with the PKCS#11 module and then used to unlock the | |
e9dd6984 ZJS |
395 | account and associated resources. See below for an example how to set up authentication with a |
396 | security token.</para> | |
4442c269 LP |
397 | |
398 | <para>Instead of a valid PKCS#11 URI, the special strings <literal>list</literal> and | |
399 | <literal>auto</literal> may be specified. If <literal>list</literal> is passed, a brief table of | |
400 | suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs. If | |
401 | <literal>auto</literal> is passed, a suitable PKCS#11 hardware token is automatically selected (this | |
402 | operation will fail if there isn't exactly one suitable token discovered). The latter is a useful | |
403 | shortcut for the most common case where a single PKCS#11 hardware token is plugged in.</para> | |
404 | ||
405 | <para>Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the | |
406 | <literal>hmac-secret</literal> extension (for example: the YubiKey 5 series), as supported with the | |
407 | <option>--fido2-device=</option> option below. Both mechanisms are similarly powerful, though FIDO2 | |
408 | is the more modern technology. PKCS#11/PIV tokens have the benefit of being recognizable before | |
409 | authentication and hence can be used for implying the user identity to use for logging in, which | |
410 | FIDO2 does not allow. PKCS#11/PIV devices generally require initialization (i.e. storing a | |
411 | private/public key pair on them, see example below) before they can be used; FIDO2 security tokens | |
ec07c3c8 AK |
412 | generally do not required that, and work out of the box.</para> |
413 | ||
414 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
4442c269 LP |
415 | </varlistentry> |
416 | ||
70e723c0 M |
417 | <varlistentry> |
418 | <term><option>--fido2-credential-algorithm=</option><replaceable>STRING</replaceable></term> | |
419 | <listitem><para>Specify COSE algorithm used in credential generation. The default value is | |
420 | <literal>es256</literal>. Supported values are <literal>es256</literal>, <literal>rs256</literal> | |
421 | and <literal>eddsa</literal>.</para> | |
422 | ||
423 | <para><literal>es256</literal> denotes ECDSA over NIST P-256 with SHA-256. <literal>rs256</literal> | |
424 | denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. <literal>eddsa</literal> denotes | |
425 | EDDSA over Curve25519 with SHA-512.</para> | |
426 | ||
ec07c3c8 AK |
427 | <para>Note that your authenticator may not support some algorithms.</para> |
428 | ||
429 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
70e723c0 M |
430 | </varlistentry> |
431 | ||
4442c269 LP |
432 | <varlistentry> |
433 | <term><option>--fido2-device=</option><replaceable>PATH</replaceable></term> | |
434 | ||
435 | <listitem><para>Takes a path to a Linux <literal>hidraw</literal> device | |
436 | (e.g. <filename>/dev/hidraw1</filename>), referring to a FIDO2 security token implementing the | |
e0c60bf6 ZJS |
437 | <literal>hmac-secret</literal> extension that shall be able to unlock the user account. A random salt |
438 | value is generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the | |
41b6ae4d ZJS |
439 | salt using an internal secret key. The result is then used as the key to unlock the user account. The |
440 | random salt is included in the user record, so that whenever authentication is needed it can be | |
441 | passed to the FIDO2 token again.</para> | |
4442c269 LP |
442 | |
443 | <para>Instead of a valid path to a FIDO2 <literal>hidraw</literal> device the special strings | |
444 | <literal>list</literal> and <literal>auto</literal> may be specified. If <literal>list</literal> is | |
445 | passed, a brief table of suitable discovered FIDO2 devices is shown. If <literal>auto</literal> is | |
446 | passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered. The latter is | |
447 | a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in.</para> | |
448 | ||
449 | <para>Note that FIDO2 devices suitable for this option must implement the | |
450 | <literal>hmac-secret</literal> extension. Most current devices (such as the YubiKey 5 series) do. If | |
451 | the extension is not implemented the device cannot be used for unlocking home directories.</para> | |
21505c93 LP |
452 | |
453 | <para>The FIDO2 device may be subsequently removed by setting the device path to an empty string | |
6d5ea0f1 | 454 | (e.g. <command>homectl update $USER --fido2-device=""</command>).</para> |
4442c269 LP |
455 | |
456 | <para>Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be | |
457 | used with either <option>--fido2-device=</option> or <option>--pkcs11-token-uri=</option>), for a | |
ec07c3c8 AK |
458 | discussion see above.</para> |
459 | ||
460 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
ea7a19e9 LP |
461 | </varlistentry> |
462 | ||
17e7561a LP |
463 | <varlistentry> |
464 | <term><option>--fido2-with-client-pin=</option><replaceable>BOOL</replaceable></term> | |
465 | ||
466 | <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter | |
467 | a PIN when unlocking the account (the FIDO2 <literal>clientPin</literal> feature). Defaults to | |
468 | <literal>yes</literal>. (Note: this setting is without effect if the security token does not support | |
469 | the <literal>clientPin</literal> feature at all, or does not allow enabling or disabling | |
ec07c3c8 AK |
470 | it.)</para> |
471 | ||
472 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
17e7561a LP |
473 | </varlistentry> |
474 | ||
475 | <varlistentry> | |
476 | <term><option>--fido2-with-user-presence=</option><replaceable>BOOL</replaceable></term> | |
477 | ||
478 | <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to | |
479 | verify presence (tap the token, the FIDO2 <literal>up</literal> feature) when unlocking the account. | |
480 | Defaults to <literal>yes</literal>. (Note: this setting is without effect if the security token does not support | |
481 | the <literal>up</literal> feature at all, or does not allow enabling or disabling it.) | |
ec07c3c8 AK |
482 | </para> |
483 | ||
484 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
17e7561a LP |
485 | </varlistentry> |
486 | ||
487 | <varlistentry> | |
488 | <term><option>--fido2-with-user-verification=</option><replaceable>BOOL</replaceable></term> | |
489 | ||
490 | <listitem><para>When enrolling a FIDO2 security token, controls whether to require user verification | |
491 | when unlocking the account (the FIDO2 <literal>uv</literal> feature). Defaults to | |
492 | <literal>no</literal>. (Note: this setting is without effect if the security token does not support | |
ec07c3c8 AK |
493 | the <literal>uv</literal> feature at all, or does not allow enabling or disabling it.)</para> |
494 | ||
495 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
17e7561a LP |
496 | </varlistentry> |
497 | ||
05c8e12c LP |
498 | <varlistentry> |
499 | <term><option>--recovery-key=</option><replaceable>BOOL</replaceable></term> | |
500 | ||
501 | <listitem><para>Accepts a boolean argument. If enabled a recovery key is configured for the | |
502 | account. A recovery key is a computer generated access key that may be used to regain access to an | |
503 | account if the password has been forgotten or the authentication token lost. The key is generated and | |
504 | shown on screen, and should be printed or otherwise transferred to a secure location. A recovery key | |
ec07c3c8 AK |
505 | may be entered instead of a regular password to unlock the account.</para> |
506 | ||
507 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
05c8e12c LP |
508 | </varlistentry> |
509 | ||
25c89b89 AV |
510 | <varlistentry> |
511 | <term><option>--blob=</option><replaceable>PATH</replaceable></term> | |
512 | <term><option>-b</option> <replaceable>PATH</replaceable></term> | |
513 | <term><option>--blob=</option><replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable></term> | |
514 | <term><option>-b</option> <replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable></term> | |
515 | ||
516 | <listitem><para>Accepts either a directory path, or a file name followed by a file path. If just a | |
517 | directory path is specified, then the user's entire blob directory is replaced the specified path. | |
518 | Note that this replacement is performed before per-file manipulations are applied, which means these per-file | |
519 | manipulations will be applied on top of the specified directory. If a filename and file path are specified, then | |
520 | the single specified blob file will be overwritten with the specified path. If completely blank, the entire blob | |
521 | directory is emptied out (which also resets all previous blob-related flags up to this point). If a filename is | |
522 | specified but the corresponding path is blank, that single file will be deleted from the blob directory. All changes | |
523 | are performed in temporary copies of the specified files in directories, which means that the originals specified on | |
524 | the command line are not modified. See <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink> | |
525 | for more information about blob directories.</para> | |
526 | ||
527 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
528 | </varlistentry> | |
529 | ||
530 | <varlistentry> | |
531 | <term><option>--avatar=</option><replaceable>PATH</replaceable></term> | |
532 | <term><option>--login-background=</option><replaceable>PATH</replaceable></term> | |
533 | ||
4b6d8de0 | 534 | <listitem><para>Accept a file path. If set, the specified file is used to overwrite the |
25c89b89 AV |
535 | corresponding file in the user's blob directory. If blank, the corresponding file is deleted |
536 | from the blob directory. Essentially, these options are shortcuts to | |
537 | <option>--blob=</option><replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable> | |
538 | for the known filenames defined in | |
539 | <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink>.</para> | |
540 | ||
541 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
542 | </varlistentry> | |
543 | ||
ea7a19e9 LP |
544 | <varlistentry> |
545 | <term><option>--locked=</option><replaceable>BOOLEAN</replaceable></term> | |
546 | ||
547 | <listitem><para>Takes a boolean argument. Specifies whether this user account shall be locked. If | |
548 | true logins into this account are prohibited, if false (the default) they are permitted (of course, | |
ec07c3c8 AK |
549 | only if authorization otherwise succeeds).</para> |
550 | ||
551 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
552 | </varlistentry> |
553 | ||
554 | <varlistentry> | |
555 | <term><option>--not-before=</option><replaceable>TIMESTAMP</replaceable></term> | |
556 | <term><option>--not-after=</option><replaceable>TIMESTAMP</replaceable></term> | |
557 | ||
558 | <listitem><para>These options take a timestamp string, in the format documented in | |
559 | <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> and | |
560 | configures points in time before and after logins into this account are not | |
ec07c3c8 AK |
561 | permitted.</para> |
562 | ||
563 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
564 | </varlistentry> |
565 | ||
566 | <varlistentry> | |
567 | <term><option>--rate-limit-interval=</option><replaceable>SECS</replaceable></term> | |
568 | <term><option>--rate-limit-burst=</option><replaceable>NUMBER</replaceable></term> | |
569 | ||
570 | <listitem><para>Configures a rate limit on authentication attempts for this user. If the user | |
571 | attempts to authenticate more often than the specified number, on a specific system, within the | |
572 | specified time interval authentication is refused until the time interval passes. Defaults to 10 | |
ec07c3c8 AK |
573 | times per 1min.</para> |
574 | ||
575 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
576 | </varlistentry> |
577 | ||
578 | <varlistentry> | |
579 | <term><option>--password-hint=</option><replaceable>TEXT</replaceable></term> | |
580 | ||
581 | <listitem><para>Takes a password hint to store alongside the user record. This string is stored | |
582 | accessible only to privileged users and the user itself and may not be queried by other users. | |
ec07c3c8 AK |
583 | Example: <option>--password-hint="My first pet's name"</option>.</para> |
584 | ||
585 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
586 | </varlistentry> |
587 | ||
588 | <varlistentry> | |
589 | <term><option>--enforce-password-policy=</option><replaceable>BOOL</replaceable></term> | |
590 | <term><option>-P</option></term> | |
591 | ||
592 | <listitem><para>Takes a boolean argument. Configures whether to enforce the system's password policy | |
593 | for this user, regarding quality and strength of selected passwords. Defaults to | |
594 | on. <option>-P</option> is short for | |
ec07c3c8 AK |
595 | <option>---enforce-password-policy=no</option>.</para> |
596 | ||
597 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
598 | </varlistentry> |
599 | ||
600 | <varlistentry> | |
601 | <term><option>--password-change-now=</option><replaceable>BOOL</replaceable></term> | |
602 | ||
603 | <listitem><para>Takes a boolean argument. If true the user is asked to change their password on next | |
ec07c3c8 AK |
604 | login.</para> |
605 | ||
606 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
607 | </varlistentry> |
608 | ||
609 | <varlistentry> | |
610 | <term><option>--password-change-min=</option><replaceable>TIME</replaceable></term> | |
611 | <term><option>--password-change-max=</option><replaceable>TIME</replaceable></term> | |
612 | <term><option>--password-change-warn=</option><replaceable>TIME</replaceable></term> | |
613 | <term><option>--password-change-inactive=</option><replaceable>TIME</replaceable></term> | |
614 | ||
615 | <listitem><para>Each of these options takes a time span specification as argument (in the syntax | |
616 | documented in | |
675fa6ea | 617 | <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) and |
e9dd6984 | 618 | configures various aspects of the user's password expiration policy. Specifically, |
ea7a19e9 LP |
619 | <option>--password-change-min=</option> configures how much time has to pass after changing the |
620 | password of the user until the password may be changed again. If the user tries to change their | |
621 | password before this time passes the attempt is refused. <option>--password-change-max=</option> | |
e9dd6984 ZJS |
622 | configures how soon after it has been changed the password expires and needs to be changed again. |
623 | After this time passes logging in may only proceed after the password is changed. | |
624 | <option>--password-change-warn=</option> specifies how much earlier than then the time configured | |
625 | with <option>--password-change-max=</option> the user is warned at login to change their password as | |
626 | it will expire soon. Finally <option>--password-change-inactive=</option> configures the time which | |
627 | has to pass after the password as expired until the user is not permitted to log in or change the | |
628 | password anymore. Note that these options only apply to password authentication, and do not apply to | |
629 | other forms of authentication, for example PKCS#11-based security token | |
ec07c3c8 AK |
630 | authentication.</para> |
631 | ||
632 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
633 | </varlistentry> |
634 | ||
635 | <varlistentry> | |
636 | <term><option>--disk-size=</option><replaceable>BYTES</replaceable></term> | |
637 | <listitem><para>Either takes a size in bytes as argument (possibly using the usual K, M, G, … | |
078dfb06 LP |
638 | suffixes for 1024 base values), a percentage value, or the special strings <literal>min</literal> or |
639 | <literal>max</literal>, and configures the disk space to assign to the user. If a percentage value is | |
640 | specified (i.e. the argument suffixed with <literal>%</literal>) it is taken relative to the | |
641 | available disk space of the backing file system. If specified as <literal>min</literal> assigns the | |
642 | minimal disk space permitted by the constraints of the backing file system and other limits, when | |
643 | specified as <literal>max</literal> assigns the maximum disk space available. If the LUKS2 backend is | |
644 | used this configures the size of the loopback file and file system contained therein. For the other | |
ea7a19e9 LP |
645 | storage backends configures disk quota using the filesystem's native quota logic, if available. If |
646 | not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for | |
ec07c3c8 AK |
647 | the others.</para> |
648 | ||
649 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
650 | </varlistentry> |
651 | ||
652 | <varlistentry> | |
653 | <term><option>--access-mode=</option><replaceable>MODE</replaceable></term> | |
654 | ||
655 | <listitem><para>Takes a UNIX file access mode written in octal. Configures the access mode of the | |
656 | home directory itself. Note that this is only used when the directory is first created, and the user | |
657 | may change this any time afterwards. Example: | |
ec07c3c8 AK |
658 | <option>--access-mode=0700</option></para> |
659 | ||
660 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
661 | </varlistentry> |
662 | ||
663 | <varlistentry> | |
664 | <term><option>--umask=</option><replaceable>MASK</replaceable></term> | |
665 | ||
666 | <listitem><para>Takes the access mode mask (in octal syntax) to apply to newly created files and | |
667 | directories of the user ("umask"). If set this controls the initial umask set for all login sessions of | |
ec07c3c8 AK |
668 | the user, possibly overriding the system's defaults.</para> |
669 | ||
670 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
671 | </varlistentry> |
672 | ||
673 | <varlistentry> | |
674 | <term><option>--nice=</option><replaceable>NICE</replaceable></term> | |
675 | ||
676 | <listitem><para>Takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login | |
ec07c3c8 AK |
677 | time. Takes a numeric value in the range -20 (highest priority) to 19 (lowest priority).</para> |
678 | ||
679 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
680 | </varlistentry> |
681 | ||
682 | <varlistentry> | |
683 | <term><option>--rlimit=</option><replaceable>LIMIT</replaceable>=<replaceable>VALUE</replaceable><optional>:<replaceable>VALUE</replaceable></optional></term> | |
684 | ||
685 | <listitem><para>Allows configuration of resource limits for processes of this user, see <citerefentry | |
686 | project='man-pages'><refentrytitle>getrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
687 | for details. Takes a resource limit name (e.g. <literal>LIMIT_NOFILE</literal>) followed by an equal | |
688 | sign, followed by a numeric limit. Optionally, separated by colon a second numeric limit may be | |
689 | specified. If two are specified this refers to the soft and hard limits, respectively. If only one | |
ec07c3c8 AK |
690 | limit is specified the setting sets both limits in one.</para> |
691 | ||
692 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
693 | </varlistentry> |
694 | ||
695 | <varlistentry> | |
696 | <term><option>--tasks-max=</option><replaceable>TASKS</replaceable></term> | |
697 | ||
84a1ff94 | 698 | <listitem><para>Takes a non-zero unsigned integer as argument. Configures the maximum number of tasks |
8dc647fd ZJS |
699 | (i.e. threads, where each process is at least one thread) the user may have at any given time. This |
700 | limit applies to all tasks forked off the user's sessions, even if they change user identity via | |
701 | <citerefentry project='man-pages'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
702 | or a similar tool. Use <option>--rlimit=LIMIT_NPROC=</option> to place a limit on the tasks actually | |
ea7a19e9 | 703 | running under the UID of the user, thus excluding any child processes that might have changed user |
86b52a39 | 704 | identity. This controls the <varname>TasksMax=</varname> setting of the per-user systemd slice unit |
ea7a19e9 LP |
705 | <filename>user-$UID.slice</filename>. See |
706 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
707 | for further details.</para> |
708 | ||
709 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
710 | </varlistentry> |
711 | ||
712 | <varlistentry> | |
713 | <term><option>--memory-high=</option><replaceable>BYTES</replaceable></term> | |
714 | <term><option>--memory-max=</option><replaceable>BYTES</replaceable></term> | |
715 | ||
716 | <listitem><para>Set a limit on the memory a user may take up on a system at any given time in bytes | |
717 | (the usual K, M, G, … suffixes are supported, to the base of 1024). This includes all memory used by | |
718 | the user itself and all processes they forked off that changed user credentials. This controls the | |
719 | <varname>MemoryHigh=</varname> and <varname>MemoryMax=</varname> settings of the per-user systemd | |
720 | slice unit <filename>user-$UID.slice</filename>. See | |
721 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
722 | for further details.</para> |
723 | ||
724 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
725 | </varlistentry> |
726 | ||
727 | <varlistentry> | |
728 | <term><option>--cpu-weight=</option><replaceable>WEIGHT</replaceable></term> | |
729 | <term><option>--io-weight=</option><replaceable>WEIGHT</replaceable></term> | |
730 | ||
24c8d4d3 | 731 | <listitem><para>Set CPU and IO scheduling weights of the processes of the user, including those of |
ea7a19e9 LP |
732 | processes forked off by the user that changed user credentials. Takes a numeric value in the range |
733 | 1…10000. This controls the <varname>CPUWeight=</varname> and <varname>IOWeight=</varname> settings of | |
734 | the per-user systemd slice unit <filename>user-$UID.slice</filename>. See | |
735 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
736 | for further details.</para> |
737 | ||
738 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
739 | </varlistentry> |
740 | ||
741 | <varlistentry> | |
742 | <term><option>--storage=</option><replaceable>STORAGE</replaceable></term> | |
743 | ||
744 | <listitem><para>Selects the storage mechanism to use for this home directory. Takes one of | |
745 | <literal>luks</literal>, <literal>fscrypt</literal>, <literal>directory</literal>, | |
746 | <literal>subvolume</literal>, <literal>cifs</literal>. For details about these mechanisms, see | |
feb86ca9 LP |
747 | above. If a new home directory is created and the storage type is not specifically specified, |
748 | <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
749 | defines which default storage to use.</para> |
750 | ||
751 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
752 | </varlistentry> |
753 | ||
754 | <varlistentry> | |
755 | <term><option>--image-path=</option><replaceable>PATH</replaceable></term> | |
756 | ||
757 | <listitem><para>Takes a file system path. Configures where to place the user's home directory. When | |
758 | LUKS2 storage is used refers to the path to the loopback file, otherwise to the path to the home | |
f9d525ae LP |
759 | directory (which may be in <filename>/home/</filename> or any other accessible filesystem). When |
760 | unspecified defaults to <filename>/home/$USER.home</filename> when LUKS storage is used and | |
761 | <filename>/home/$USER.homedir</filename> for the other storage mechanisms. Not defined for the | |
762 | <literal>cifs</literal> storage mechanism. To use LUKS2 storage on a regular block device (for | |
763 | example a USB stick) pass the path to the block device here. Specifying the path to a directory here | |
764 | when using LUKS2 storage is not allowed. Similar, specifying the path to a regular file or device | |
ec07c3c8 AK |
765 | node is not allowed if any of the other storage backends are used.</para> |
766 | ||
767 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
768 | </varlistentry> |
769 | ||
86019efa LP |
770 | <varlistentry> |
771 | <term><option>--drop-caches=</option><replaceable>BOOL</replaceable></term> | |
772 | ||
773 | <listitem><para>Automatically flush OS file system caches on logout. This is useful in combination | |
774 | with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and | |
775 | directories in memory (and accessible) after logout. This option is also supported on other backends, | |
776 | but should not bring any benefit there. Defaults to off, except if the selected storage backend is | |
777 | fscrypt, where it defaults to on. Note that flushing OS caches will negatively influence performance | |
ec07c3c8 AK |
778 | of the OS shortly after logout.</para> |
779 | ||
780 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
86019efa LP |
781 | </varlistentry> |
782 | ||
ea7a19e9 LP |
783 | <varlistentry> |
784 | <term><option>--fs-type=</option><replaceable>TYPE</replaceable></term> | |
785 | ||
786 | <listitem><para>When LUKS2 storage is used configures the file system type to use inside the home | |
caf6bd16 LP |
787 | directory LUKS2 container. One of <literal>btrfs</literal>, <literal>ext4</literal>, |
788 | <literal>xfs</literal>. If not specified | |
feb86ca9 LP |
789 | <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
790 | defines which default file system type to use. Note that <literal>xfs</literal> is not recommended as | |
ec07c3c8 AK |
791 | its support for file system resizing is too limited.</para> |
792 | ||
793 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
794 | </varlistentry> |
795 | ||
796 | <varlistentry> | |
797 | <term><option>--luks-discard=</option><replaceable>BOOL</replaceable></term> | |
798 | ||
799 | <listitem><para>When LUKS2 storage is used configures whether to enable the | |
800 | <literal>discard</literal> feature of the file system. If enabled the file system on top of the LUKS2 | |
801 | volume will report empty block information to LUKS2 and the loopback file below, ensuring that empty | |
802 | space in the home directory is returned to the backing file system below the LUKS2 volume, resulting | |
803 | in a "sparse" loopback file. This option mostly defaults to off, since this permits over-committing | |
804 | home directories which results in I/O errors if the underlying file system runs full while the upper | |
805 | file system wants to allocate a block. Such I/O errors are generally not handled well by file systems | |
806 | nor applications. When LUKS2 storage is used on top of regular block devices (instead of on top a | |
ec07c3c8 AK |
807 | loopback file) the discard logic defaults to on.</para> |
808 | ||
809 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
810 | </varlistentry> |
811 | ||
c0440512 LP |
812 | <varlistentry> |
813 | <term><option>--luks-offline-discard=</option><replaceable>BOOL</replaceable></term> | |
814 | ||
815 | <listitem><para>Similar to <option>--luks-discard=</option>, controls the trimming of the file | |
816 | system. However, while <option>--luks-discard=</option> controls what happens when the home directory | |
817 | is active, <option>--luks-offline-discard=</option> controls what happens when it becomes inactive, | |
818 | i.e. whether to trim/allocate the storage when deactivating the home directory. This option defaults | |
ec07c3c8 AK |
819 | to on, to ensure disk space is minimized while a user is not logged in.</para> |
820 | ||
821 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
5dd57a00 LP |
822 | </varlistentry> |
823 | ||
824 | <varlistentry> | |
825 | <term><option>--luks-extra-mount-options=</option><replaceable>OPTIONS</replaceable></term> | |
826 | ||
827 | <listitem><para>Takes a string containing additional mount options to use when mounting the LUKS | |
828 | volume. If specified, this string will be appended to the default, built-in mount | |
ec07c3c8 AK |
829 | options.</para> |
830 | ||
831 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c0440512 LP |
832 | </varlistentry> |
833 | ||
ea7a19e9 LP |
834 | <varlistentry> |
835 | <term><option>--luks-cipher=</option><replaceable>CIPHER</replaceable></term> | |
836 | <term><option>--luks-cipher-mode=</option><replaceable>MODE</replaceable></term> | |
b72308d3 | 837 | <term><option>--luks-volume-key-size=</option><replaceable>BYTES</replaceable></term> |
ea7a19e9 LP |
838 | <term><option>--luks-pbkdf-type=</option><replaceable>TYPE</replaceable></term> |
839 | <term><option>--luks-pbkdf-hash-algorithm=</option><replaceable>ALGORITHM</replaceable></term> | |
b04ff66b | 840 | <term><option>--luks-pbkdf-force-iterations=</option><replaceable>ITERATIONS</replaceable></term> |
ea7a19e9 LP |
841 | <term><option>--luks-pbkdf-time-cost=</option><replaceable>SECONDS</replaceable></term> |
842 | <term><option>--luks-pbkdf-memory-cost=</option><replaceable>BYTES</replaceable></term> | |
843 | <term><option>--luks-pbkdf-parallel-threads=</option><replaceable>THREADS</replaceable></term> | |
fd83c98e | 844 | <term><option>--luks-sector-size=</option><replaceable>BYTES</replaceable></term> |
ea7a19e9 LP |
845 | |
846 | <listitem><para>Configures various cryptographic parameters for the LUKS2 storage mechanism. See | |
847 | <citerefentry | |
848 | project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
b72308d3 ZJS |
849 | for details on the specific attributes.</para> |
850 | ||
851 | <para>Note that <command>homectl</command> uses bytes for key size, like | |
852 | <filename>/proc/crypto</filename>, but <citerefentry | |
853 | project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
aefdc112 AK |
854 | uses bits.</para> |
855 | ||
856 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
857 | </varlistentry> |
858 | ||
2f09e2ee LP |
859 | <varlistentry> |
860 | <term><option>--auto-resize-mode=</option></term> | |
861 | ||
862 | <listitem><para>Configures whether to automatically grow and/or shrink the backing file system on | |
863 | login and logout. Takes one of the strings <literal>off</literal>, <literal>grow</literal>, | |
864 | <literal>shrink-and-grow</literal>. Only applies to the LUKS2 backend currently, and if the btrfs | |
865 | file system is used inside it (since only then online growing/shrinking of the file system is | |
866 | supported). Defaults to <literal>shrink-and-grow</literal>, if LUKS2/btrfs is used, otherwise is | |
867 | off. If set to <literal>off</literal> no automatic shrinking/growing during login or logout is | |
868 | done. If set to <literal>grow</literal> the home area is grown to the size configured via | |
869 | <option>--disk-size=</option> should it currently be smaller. If it already matches the configured | |
870 | size or is larger no operation is executed. If set to <literal>shrink-and-grow</literal> the home | |
fe003f02 ZJS |
871 | area is also resized during logout to the minimal size the used disk space and file system |
872 | constraints permit. This mode thus ensures that while a home area is activated it is sized to the | |
873 | configured size, but while deactivated it is compacted taking up only the minimal space possible. | |
874 | Note that if the system is powered off abnormally or if the user otherwise not logged out cleanly the | |
875 | shrinking operation will not take place, and the user has to re-login/logout again before it is | |
ec07c3c8 AK |
876 | executed again.</para> |
877 | ||
878 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
2f09e2ee LP |
879 | </varlistentry> |
880 | ||
21505c93 LP |
881 | <varlistentry> |
882 | <term><option>--rebalance-weight=</option></term> | |
883 | ||
884 | <listitem><para>Configures the weight parameter for the free disk space rebalancing logic. Only | |
885 | applies to the LUKS2 backend (since for the LUKS2 backend disk space is allocated from a per-user | |
886 | loopback file system instead of immediately from a common pool like the other backends do it). In | |
887 | regular intervals free disk space in the active home areas and their backing storage is redistributed | |
888 | among them, taking the weight value configured here into account. Expects an integer in the range | |
889 | 1…10000, or the special string <literal>off</literal>. If not specified defaults to 100. The weight | |
890 | is used to scale free space made available to the home areas: a home area with a weight of 200 will | |
891 | get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half | |
892 | of that. The backing file system will be assigned space for a weight of 20. If set to | |
893 | <literal>off</literal> no automatic free space distribution is done for this home area. Note that | |
894 | resizing the home area explicitly (with <command>homectl resize</command> see below) will implicitly | |
895 | turn off the automatic rebalancing. To reenable the automatic rebalancing use | |
ec07c3c8 AK |
896 | <option>--rebalance-weight=</option> with an empty parameter.</para> |
897 | ||
898 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
21505c93 LP |
899 | </varlistentry> |
900 | ||
ea7a19e9 LP |
901 | <varlistentry> |
902 | <term><option>--nosuid=</option><replaceable>BOOL</replaceable></term> | |
903 | <term><option>--nodev=</option><replaceable>BOOL</replaceable></term> | |
904 | <term><option>--noexec=</option><replaceable>BOOL</replaceable></term> | |
905 | ||
906 | <listitem><para>Configures the <literal>nosuid</literal>, <literal>nodev</literal> and | |
907 | <literal>noexec</literal> mount options for the home directories. By default <literal>nodev</literal> | |
908 | and <literal>nosuid</literal> are on, while <literal>noexec</literal> is off. For details about these | |
909 | mount options see <citerefentry | |
ec07c3c8 AK |
910 | project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
911 | ||
912 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
913 | </varlistentry> |
914 | ||
915 | <varlistentry> | |
916 | <term><option>--cifs-domain=</option><replaceable>DOMAIN</replaceable></term> | |
917 | <term><option>--cifs-user-name=</option><replaceable>USER</replaceable></term> | |
918 | <term><option>--cifs-service=</option><replaceable>SERVICE</replaceable></term> | |
4c2ee5c7 | 919 | <term><option>--cifs-extra-mount-options=</option><replaceable>OPTIONS</replaceable></term> |
ea7a19e9 LP |
920 | |
921 | <listitem><para>Configures the Windows File Sharing (CIFS) domain and user to associate with the home | |
bf15879b LP |
922 | directory/user account, as well as the file share ("service") to mount as directory. The latter is |
923 | used when <literal>cifs</literal> storage is selected. The file share should be specified in format | |
924 | <literal>//<replaceable>host</replaceable>/<replaceable>share</replaceable>/<replaceable>directory/…</replaceable></literal>. The | |
925 | directory part is optional — if not specified the home directory will be placed in the top-level | |
4c2ee5c7 LP |
926 | directory of the share. The <option>--cifs-extra-mount-options=</option> setting allows specifying |
927 | additional mount options when mounting the share, see <citerefentry | |
928 | project='man-pages'><refentrytitle>mount.cifs</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
aefdc112 AK |
929 | for details.</para> |
930 | ||
931 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
932 | </varlistentry> |
933 | ||
934 | <varlistentry> | |
935 | <term><option>--stop-delay=</option><replaceable>SECS</replaceable></term> | |
936 | ||
937 | <listitem><para>Configures the time the per-user service manager shall continue to run after the all | |
938 | sessions of the user ended. The default is configured in | |
939 | <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> (for | |
940 | home directories of LUKS2 storage located on removable media this defaults to 0 though). A longer | |
941 | time makes sure quick, repetitive logins are more efficient as the user's service manager doesn't | |
ec07c3c8 AK |
942 | have to be started every time.</para> |
943 | ||
944 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
945 | </varlistentry> |
946 | ||
947 | <varlistentry> | |
948 | <term><option>--kill-processes=</option><replaceable>BOOL</replaceable></term> | |
949 | ||
950 | <listitem><para>Configures whether to kill all processes of the user on logout. The default is | |
951 | configured in | |
ec07c3c8 AK |
952 | <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> |
953 | ||
954 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
955 | </varlistentry> |
956 | ||
957 | <varlistentry> | |
958 | <term><option>--auto-login=</option><replaceable>BOOL</replaceable></term> | |
959 | ||
960 | <listitem><para>Takes a boolean argument. Configures whether the graphical UI of the system should | |
961 | automatically log this user in if possible. Defaults to off. If less or more than one user is marked | |
ec07c3c8 AK |
962 | this way automatic login is disabled.</para> |
963 | ||
964 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 | 965 | </varlistentry> |
793ceda1 AV |
966 | |
967 | <varlistentry> | |
968 | <term><option>--session-launcher=</option><replaceable>LAUNCHER</replaceable></term> | |
969 | ||
970 | <listitem><para>Takes a string argument. Configures the user's preferred session launcher | |
971 | .desktop entry file (i.e. <literal>gnome</literal>, <literal>plasma</literal>, or other names that | |
972 | appear in <filename>/usr/share/xesssions/</filename> or <filename>/usr/share/wayland-sessions</filename>). | |
973 | This is read by the display manager to pick the default session that is launched when the user logs in.</para> | |
974 | ||
975 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
976 | </varlistentry> | |
977 | ||
978 | <varlistentry> | |
979 | <term><option>--session-type=</option><replaceable>TYPE</replaceable></term> | |
980 | ||
981 | <listitem><para>Takes a string argument. Configures the user's preferred session type | |
982 | (i.e. <literal>x11</literal>, <literal>wayland</literal>, and other values accepted by | |
983 | <varname>$XDG_SESSION_TYPE</varname>). This is read by the display manage to pick the | |
984 | default session type the user is logged into.</para> | |
985 | ||
986 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
987 | </varlistentry> | |
ea7a19e9 LP |
988 | </variablelist> |
989 | </refsect1> | |
990 | ||
991 | <refsect1> | |
992 | <title>Commands</title> | |
993 | ||
994 | <para>The following commands are understood:</para> | |
995 | ||
996 | <variablelist> | |
997 | ||
998 | <varlistentry> | |
999 | <term><command>list</command></term> | |
1000 | ||
1001 | <listitem><para>List all home directories (along with brief details) currently managed by | |
1002 | <filename>systemd-homed.service</filename>. This command is also executed if none is specified on the | |
1003 | command line. (Note that the list of users shown by this command does not include users managed by | |
1004 | other subsystems, such as system users or any traditional users listed in | |
ec07c3c8 AK |
1005 | <filename>/etc/passwd</filename>.)</para> |
1006 | ||
1007 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1008 | </varlistentry> |
1009 | ||
1010 | <varlistentry> | |
1011 | <term><command>activate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term> | |
1012 | ||
1013 | <listitem><para>Activate one or more home directories. The home directories of each listed user will | |
1014 | be activated and made available under their mount points (typically in | |
1015 | <filename>/home/$USER</filename>). Note that any home activated this way stays active indefinitely, | |
1016 | until it is explicitly deactivated again (with <command>deactivate</command>, see below), or the user | |
1017 | logs in and out again and it thus is deactivated due to the automatic deactivation-on-logout | |
1018 | logic.</para> | |
1019 | ||
1020 | <para>Activation of a home directory involves various operations that depend on the selected storage | |
1021 | mechanism. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a | |
1022 | password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file | |
e9dd6984 | 1023 | system, mounting the file system, and potentially changing the ownership of all included files to the |
ec07c3c8 AK |
1024 | correct UID/GID.</para> |
1025 | ||
1026 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1027 | </varlistentry> |
1028 | ||
1029 | <varlistentry> | |
1030 | <term><command>deactivate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term> | |
1031 | ||
1032 | <listitem><para>Deactivate one or more home directories. This undoes the effect of | |
ec07c3c8 AK |
1033 | <command>activate</command>.</para> |
1034 | ||
1035 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1036 | </varlistentry> |
1037 | ||
1038 | <varlistentry> | |
1039 | <term><command>inspect</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term> | |
1040 | ||
1041 | <listitem><para>Show various details about the specified home directories. This shows various | |
1042 | information about the home directory and its user account, including runtime data such as current | |
1043 | state, disk use and similar. Combine with <option>--json=</option> to show the detailed JSON user | |
1044 | record instead, possibly combined with <option>--export-format=</option> to suppress certain aspects | |
ec07c3c8 AK |
1045 | of the output.</para> |
1046 | ||
1047 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1048 | </varlistentry> |
1049 | ||
1050 | <varlistentry> | |
1051 | <term><command>authenticate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term> | |
1052 | ||
1053 | <listitem><para>Validate authentication credentials of a home directory. This queries the caller for | |
1054 | a password (or similar) and checks that it correctly unlocks the home directory. This leaves the home | |
1055 | directory in the state it is in, i.e. it leaves the home directory in inactive state if it was | |
ec07c3c8 AK |
1056 | inactive before, and in active state if it was active before.</para> |
1057 | ||
1058 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1059 | </varlistentry> |
1060 | ||
1061 | <varlistentry> | |
1062 | <term><command>create</command> <replaceable>USER</replaceable></term> | |
1063 | <term><command>create</command> <option>--identity=</option><replaceable>PATH</replaceable> <optional><replaceable>USER</replaceable></optional></term> | |
1064 | ||
1065 | <listitem><para>Create a new home directory/user account of the specified name. Use the various | |
1066 | user record property options (as documented above) to control various aspects of the home directory | |
887a8fa3 LP |
1067 | and its user accounts.</para> |
1068 | ||
1069 | <para>The specified user name should follow the strict syntax described on <ulink | |
ec07c3c8 AK |
1070 | url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para> |
1071 | ||
1072 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1073 | </varlistentry> |
1074 | ||
1075 | <varlistentry> | |
1076 | <term><command>remove</command> <replaceable>USER</replaceable></term> | |
1077 | ||
1078 | <listitem><para>Remove a home directory/user account. This will remove both the home directory's user | |
1079 | record and the home directory itself, and thus delete all files and directories owned by the | |
ec07c3c8 AK |
1080 | user.</para> |
1081 | ||
1082 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1083 | </varlistentry> |
1084 | ||
1085 | <varlistentry> | |
1086 | <term><command>update</command> <replaceable>USER</replaceable></term> | |
1087 | <term><command>update</command> <option>--identity=</option><replaceable>PATH</replaceable> <optional><replaceable>USER</replaceable></optional></term> | |
1088 | ||
1089 | <listitem><para>Update a home directory/user account. Use the various user record property options | |
1090 | (as documented above) to make changes to the account, or alternatively provide a full, updated JSON | |
1091 | user record via the <option>--identity=</option> option.</para> | |
1092 | ||
1093 | <para>Note that changes to user records not signed by a cryptographic private key available locally | |
1094 | are not permitted, unless <option>--identity=</option> is used with a user record that is already | |
ec07c3c8 AK |
1095 | correctly signed by a recognized private key.</para> |
1096 | ||
1097 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1098 | </varlistentry> |
1099 | ||
1100 | <varlistentry> | |
1101 | <term><command>passwd</command> <replaceable>USER</replaceable></term> | |
1102 | ||
ec07c3c8 AK |
1103 | <listitem><para>Change the password of the specified home directory/user account.</para> |
1104 | ||
1105 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1106 | </varlistentry> |
1107 | ||
1108 | <varlistentry> | |
1109 | <term><command>resize</command> <replaceable>USER</replaceable> <replaceable>BYTES</replaceable></term> | |
1110 | ||
1111 | <listitem><para>Change the disk space assigned to the specified home directory. If the LUKS2 storage | |
1112 | mechanism is used this will automatically resize the loopback file and the file system contained | |
1113 | within. Note that if <literal>ext4</literal> is used inside of the LUKS2 volume, it is necessary to | |
1114 | deactivate the home directory before shrinking it (i.e the user has to log out). Growing can be done | |
1115 | while the home directory is active. If <literal>xfs</literal> is used inside of the LUKS2 volume the | |
1116 | home directory may not be shrunk whatsoever. On all three of <literal>ext4</literal>, | |
1117 | <literal>xfs</literal> and <literal>btrfs</literal> the home directory may be grown while the user is | |
1118 | logged in, and on the latter also shrunk while the user is logged in. If the | |
1119 | <literal>subvolume</literal>, <literal>directory</literal>, <literal>fscrypt</literal> storage | |
9f5827e0 LP |
1120 | mechanisms are used, resizing will change file system quota. The size parameter may make use of the |
1121 | usual suffixes B, K, M, G, T (to the base of 1024). The special strings <literal>min</literal> and | |
1122 | <literal>max</literal> may be specified in place of a numeric size value, for minimizing or | |
1123 | maximizing disk space assigned to the home area, taking constraints of the file system, disk usage inside | |
ec07c3c8 AK |
1124 | the home area and on the backing storage into account.</para> |
1125 | ||
1126 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1127 | </varlistentry> |
1128 | ||
1129 | <varlistentry> | |
1130 | <term><command>lock</command> <replaceable>USER</replaceable></term> | |
1131 | ||
1132 | <listitem><para>Temporarily suspend access to the user's home directory and remove any associated | |
1133 | cryptographic keys from memory. Any attempts to access the user's home directory will stall until the | |
1134 | home directory is unlocked again (i.e. re-authenticated). This functionality is primarily intended to | |
1135 | be used during system suspend to make sure the user's data cannot be accessed until the user | |
1136 | re-authenticates on resume. This operation is only defined for home directories that use the LUKS2 | |
ec07c3c8 AK |
1137 | storage mechanism.</para> |
1138 | ||
1139 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1140 | </varlistentry> |
1141 | ||
1142 | <varlistentry> | |
1143 | <term><command>unlock</command> <replaceable>USER</replaceable></term> | |
1144 | ||
1145 | <listitem><para>Resume access to the user's home directory again, undoing the effect of | |
1146 | <command>lock</command> above. This requires authentication of the user, as the cryptographic keys | |
ec07c3c8 AK |
1147 | required for access to the home directory need to be reacquired.</para> |
1148 | ||
1149 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1150 | </varlistentry> |
1151 | ||
1152 | <varlistentry> | |
1153 | <term><command>lock-all</command></term> | |
1154 | ||
1155 | <listitem><para>Execute the <command>lock</command> command on all suitable home directories at | |
1156 | once. This operation is generally executed on system suspend (i.e. by <command>systemctl | |
1157 | suspend</command> and related commands), to ensure all active user's cryptographic keys for accessing | |
ec07c3c8 AK |
1158 | their home directories are removed from memory.</para> |
1159 | ||
1160 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 LP |
1161 | </varlistentry> |
1162 | ||
d1f6e01e LP |
1163 | <varlistentry> |
1164 | <term><command>deactivate-all</command></term> | |
1165 | ||
1166 | <listitem><para>Execute the <command>deactivate</command> command on all active home directories at | |
1167 | once. This operation is generally executed on system shut down (i.e. by <command>systemctl | |
1168 | poweroff</command> and related commands), to ensure all active user's home directories are fully | |
ec07c3c8 AK |
1169 | deactivated before <filename>/home/</filename> and related file systems are unmounted.</para> |
1170 | ||
1171 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
d1f6e01e LP |
1172 | </varlistentry> |
1173 | ||
ea7a19e9 LP |
1174 | <varlistentry> |
1175 | <term><command>with</command> <replaceable>USER</replaceable> <replaceable>COMMAND…</replaceable></term> | |
1176 | ||
1177 | <listitem><para>Activate the specified user's home directory, run the specified command (under the | |
1178 | caller's identity, not the specified user's) and deactivate the home directory afterwards again | |
1179 | (unless the user is logged in otherwise). This command is useful for running privileged backup | |
1180 | scripts and such, but requires authentication with the user's credentials in order to be able to | |
ec07c3c8 AK |
1181 | unlock the user's home directory.</para> |
1182 | ||
1183 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
ea7a19e9 | 1184 | </varlistentry> |
6d6d4459 LP |
1185 | |
1186 | <varlistentry> | |
1187 | <term><command>rebalance</command></term> | |
1188 | ||
1189 | <listitem><para>Rebalance free disk space between active home areas and the backing storage. See | |
1190 | <option>--rebalance-weight=</option> above. This executes no operation unless there's at least one | |
1191 | active LUKS2 home area that has disk space rebalancing enabled. This operation is synchronous: it | |
1192 | will only complete once disk space is rebalanced according to the rebalancing weights. Note that | |
1193 | rebalancing also takes place automatically in the background in regular intervals. Use this command | |
1194 | to synchronously ensure disk space is properly redistributed before initiating an operation requiring | |
ec07c3c8 AK |
1195 | large amounts of disk space.</para> |
1196 | ||
1197 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
6d6d4459 | 1198 | </varlistentry> |
3ccadbce LP |
1199 | |
1200 | <varlistentry> | |
1201 | <term><command>firstboot</command></term> | |
1202 | ||
1203 | <listitem><para>This command is supposed to be invoked during the initial boot of the system. It | |
1204 | checks whether any regular home area exists so far, and if not queries the user interactively on the | |
1205 | console for user name and password and creates one. Alternatively, if one or more service credentials | |
1206 | whose name starts with <literal>home.create.</literal> are passed to the command (containing a user | |
1207 | record in JSON format) these users are automatically created at boot.</para> | |
1208 | ||
1209 | <para>This command is invoked by the <filename>systemd-homed-firstboot.service</filename> service | |
1210 | unit.</para> | |
1211 | ||
1212 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
1213 | </varlistentry> | |
1214 | </variablelist> | |
1215 | </refsect1> | |
1216 | ||
1217 | <refsect1> | |
1218 | <title>Credentials</title> | |
1219 | ||
1220 | <para>When invoked with the <command>firstboot</command> command, <command>homectl</command> supports the | |
1221 | service credentials logic as implemented by | |
1222 | <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname> | |
658dc909 | 1223 | (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for |
3ccadbce LP |
1224 | details). The following credentials are used when passed in:</para> |
1225 | ||
1226 | <variablelist class='system-credentials'> | |
1227 | <varlistentry> | |
1228 | <term><varname>home.create.*</varname></term> | |
1229 | ||
1230 | <listitem><para>If one or more credentials whose names begin with <literal>home.create.</literal>, | |
1231 | followed by a valid UNIX username are passed, a new home area is created, one for each specified user | |
1232 | record.</para> | |
1233 | ||
1234 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
1235 | </varlistentry> | |
1236 | </variablelist> | |
1237 | </refsect1> | |
1238 | ||
1239 | <refsect1> | |
1240 | <title>Kernel Command Line</title> | |
1241 | ||
1242 | <variablelist class='kernel-commandline-options'> | |
1243 | <varlistentry> | |
1244 | <term><varname>systemd.firstboot=</varname></term> | |
1245 | ||
1246 | <listitem><para>This boolean will disable the effect of <command>homectl firstboot</command> | |
1247 | command. It's primarily interpreted by | |
1248 | <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> | |
1249 | ||
1250 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
1251 | </varlistentry> | |
ea7a19e9 LP |
1252 | </variablelist> |
1253 | </refsect1> | |
1254 | ||
1255 | <refsect1> | |
1256 | <title>Exit status</title> | |
1257 | ||
1258 | <para>On success, 0 is returned, a non-zero failure code otherwise.</para> | |
b9bfa250 ZJS |
1259 | |
1260 | <para>When a command is invoked with <command>with</command>, the exit status of the child is | |
1261 | propagated. Effectively, <command>homectl</command> will exit without error if the command is | |
1262 | successfully invoked <emphasis>and</emphasis> finishes successfully.</para> | |
ea7a19e9 LP |
1263 | </refsect1> |
1264 | ||
4ef3ca34 | 1265 | <xi:include href="common-variables.xml" /> |
ea7a19e9 LP |
1266 | |
1267 | <refsect1> | |
1268 | <title>Examples</title> | |
1269 | ||
1270 | <example> | |
1271 | <title>Create a user <literal>waldo</literal> in the administrator group <literal>wheel</literal>, and | |
1272 | assign 500 MiB disk space to them.</title> | |
1273 | ||
1274 | <programlisting>homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M</programlisting> | |
1275 | </example> | |
1276 | ||
1277 | <example> | |
1278 | <title>Create a user <literal>wally</literal> on a USB stick, and assign a maximum of 500 concurrent | |
1279 | tasks to them.</title> | |
1280 | ||
1281 | <programlisting>homectl create wally --real-name="Wally McWally" --image-path=/dev/disk/by-id/usb-SanDisk_Ultra_Fit_476fff954b2b5c44-0:0 --tasks-max=500</programlisting> | |
1282 | </example> | |
1283 | ||
1284 | <example> | |
1285 | <title>Change nice level of user <literal>odlaw</literal> to +5 and make sure the environment variable | |
1286 | <varname>$SOME</varname> is set to the string <literal>THING</literal> for them on login.</title> | |
1287 | ||
1288 | <programlisting>homectl update odlaw --nice=5 --setenv=SOME=THING</programlisting> | |
1289 | </example> | |
1290 | ||
1291 | <example> | |
4442c269 | 1292 | <title>Set up authentication with a YubiKey security token using PKCS#11/PIV:</title> |
ea7a19e9 LP |
1293 | |
1294 | <programlisting># Clear the Yubikey from any old keys (careful!) | |
1295 | ykman piv reset | |
1296 | ||
1297 | # Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'. | |
1298 | ykman piv generate-key -a RSA2048 9d pubkey.pem | |
1299 | ||
1300 | # Create a self-signed certificate from this public key, and store it on the device. | |
1301 | ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem | |
1302 | ||
4442c269 | 1303 | # We don't need the public key on disk anymore |
ea7a19e9 LP |
1304 | rm pubkey.pem |
1305 | ||
4442c269 LP |
1306 | # Allow the security token to unlock the account of user 'lafcadio'. |
1307 | homectl update lafcadio --pkcs11-token-uri=auto</programlisting> | |
1308 | </example> | |
1309 | ||
1310 | <example> | |
1311 | <title>Set up authentication with a FIDO2 security token:</title> | |
ea7a19e9 | 1312 | |
4442c269 LP |
1313 | <programlisting># Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'. |
1314 | homectl update nihilbaxter --fido2-device=auto</programlisting> | |
ea7a19e9 LP |
1315 | </example> |
1316 | </refsect1> | |
1317 | ||
1318 | <refsect1> | |
1319 | <title>See Also</title> | |
13a69c12 DT |
1320 | <para><simplelist type="inline"> |
1321 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
1322 | <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
1323 | <member><citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
1324 | <member><citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
1325 | <member><citerefentry project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
1326 | <member><citerefentry project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
1327 | </simplelist></para> | |
ea7a19e9 LP |
1328 | </refsect1> |
1329 | ||
1330 | </refentry> |