HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/homectl.xml
Git blob: 41d7ce52b520811fe068a2dcf26fe591a9d0a794
Lines 1001–1682 of 1,682
<term><option>--fs-type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>When LUKS2 storage is used configures the file system type to use inside the home
directory LUKS2 container. One of <literal>btrfs</literal>, <literal>ext4</literal>,
<literal>xfs</literal>. If not specified
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
defines which default file system type to use. Note that <literal>xfs</literal> is not recommended as
its support for file system resizing is too limited.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-discard=<replaceable>BOOL</replaceable></option></term>
<listitem><para>When LUKS2 storage is used configures whether to enable the
<literal>discard</literal> feature of the file system. If enabled the file system on top of the LUKS2
volume will report empty block information to LUKS2 and the loopback file below, ensuring that empty
space in the home directory is returned to the backing file system below the LUKS2 volume, resulting
in a "sparse" loopback file. This option mostly defaults to off, since this permits over-committing
home directories which results in I/O errors if the underlying file system runs full while the upper
file system wants to allocate a block. Such I/O errors are generally not handled well by file systems
nor applications. When LUKS2 storage is used on top of regular block devices (instead of on top a
loopback file) the discard logic defaults to on.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-offline-discard=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Similar to <option>--luks-discard=</option>, controls the trimming of the file
system. However, while <option>--luks-discard=</option> controls what happens when the home directory
is active, <option>--luks-offline-discard=</option> controls what happens when it becomes inactive,
i.e. whether to trim/allocate the storage when deactivating the home directory. This option defaults
to on, to ensure disk space is minimized while a user is not logged in.</para>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-extra-mount-options=<replaceable>OPTIONS</replaceable></option></term>
<listitem><para>Takes a string containing additional mount options to use when mounting the LUKS
volume. If specified, this string will be appended to the default, built-in mount
options. Defaults to "compress=zstd:1,noacl,user_subvol_rm_allowed".</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--luks-cipher=<replaceable>CIPHER</replaceable></option></term>
<term><option>--luks-cipher-mode=<replaceable>MODE</replaceable></option></term>
<term><option>--luks-volume-key-size=<replaceable>BYTES</replaceable></option></term>
<term><option>--luks-pbkdf-type=<replaceable>TYPE</replaceable></option></term>
<term><option>--luks-pbkdf-hash-algorithm=<replaceable>ALGORITHM</replaceable></option></term>
<term><option>--luks-pbkdf-force-iterations=<replaceable>ITERATIONS</replaceable></option></term>
<term><option>--luks-pbkdf-time-cost=<replaceable>SECONDS</replaceable></option></term>
<term><option>--luks-pbkdf-memory-cost=<replaceable>BYTES</replaceable></option></term>
<term><option>--luks-pbkdf-parallel-threads=<replaceable>THREADS</replaceable></option></term>
<term><option>--luks-sector-size=<replaceable>BYTES</replaceable></option></term>
<listitem><para>Configures various cryptographic parameters for the LUKS2 storage mechanism. See
<citerefentry
project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for details on the specific attributes.</para>
<para>Note that <command>homectl</command> uses bytes for key size, like
<filename>/proc/crypto</filename>, but <citerefentry
project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
uses bits.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--auto-resize-mode=</option></term>
<listitem><para>Configures whether to automatically grow and/or shrink the backing file system on
login and logout. Takes one of the strings <literal>off</literal>, <literal>grow</literal>,
<literal>shrink-and-grow</literal>. Only applies to the LUKS2 backend currently, and if the btrfs
file system is used inside it (since only then online growing/shrinking of the file system is
supported). Defaults to <literal>shrink-and-grow</literal>, if LUKS2/btrfs is used, otherwise is
off. If set to <literal>off</literal> no automatic shrinking/growing during login or logout is
done. If set to <literal>grow</literal> the home area is grown to the size configured via
<option>--disk-size=</option> should it currently be smaller. If it already matches the configured
size or is larger no operation is executed. If set to <literal>shrink-and-grow</literal> the home
area is also resized during logout to the minimal size the used disk space and file system
constraints permit. This mode thus ensures that while a home area is activated it is sized to the
configured size, but while deactivated it is compacted taking up only the minimal space possible.
Note that if the system is powered off abnormally or if the user otherwise not logged out cleanly the
shrinking operation will not take place, and the user has to re-login/logout again before it is
executed again.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--rebalance-weight=</option></term>
<listitem><para>Configures the weight parameter for the free disk space rebalancing logic. Only
applies to the LUKS2 backend (since for the LUKS2 backend disk space is allocated from a per-user
loopback file system instead of immediately from a common pool like the other backends do it). In
regular intervals free disk space in the active home areas and their backing storage is redistributed
among them, taking the weight value configured here into account. Expects an integer in the range
1…10000, or the special string <literal>off</literal>. If not specified, defaults to 100. The weight
is used to scale free space made available to the home areas: a home area with a weight of 200 will
get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half
of that. The backing file system will be assigned space for a weight of 20. If set to
<literal>off</literal> no automatic free space distribution is done for this home area. Note that
resizing the home area explicitly (with <command>homectl resize</command> see below) will implicitly
turn off the automatic rebalancing. To reenable the automatic rebalancing use
<option>--rebalance-weight=</option> with an empty parameter.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Mounting User Record Properties</title>
<variablelist>
<varlistentry>
<term><option>--nosuid=<replaceable>BOOL</replaceable></option></term>
<term><option>--nodev=<replaceable>BOOL</replaceable></option></term>
<term><option>--noexec=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configures the <literal>nosuid</literal>, <literal>nodev</literal> and
<literal>noexec</literal> mount options for the home directories. By default, <literal>nodev</literal>
and <literal>nosuid</literal> are on, while <literal>noexec</literal> is off. For details about these
mount options see <citerefentry
project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>CIFS User Record Properties</title>
<variablelist>
<varlistentry>
<term><option>--cifs-domain=<replaceable>DOMAIN</replaceable></option></term>
<term><option>--cifs-user-name=<replaceable>USER</replaceable></option></term>
<term><option>--cifs-service=<replaceable>SERVICE</replaceable></option></term>
<term><option>--cifs-extra-mount-options=<replaceable>OPTIONS</replaceable></option></term>
<listitem><para>Configures the Windows File Sharing (CIFS) domain and user to associate with the home
directory/user account, as well as the file share ("service") to mount as directory. The latter is
used when <literal>cifs</literal> storage is selected. The file share should be specified in format
<literal>//<replaceable>host</replaceable>/<replaceable>share</replaceable>/<replaceable>directory/…</replaceable></literal>. The
directory part is optional — if not specified, the home directory will be placed in the top-level
directory of the share. The <option>--cifs-extra-mount-options=</option> setting allows specifying
additional mount options when mounting the share, see <citerefentry
project='man-pages'><refentrytitle>mount.cifs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for details.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Login Behaviour Record Properties</title>
<variablelist>
<varlistentry>
<term><option>--stop-delay=<replaceable>SECS</replaceable></option></term>
<listitem><para>Configures the time the per-user service manager shall continue to run after the all
sessions of the user ended. The default is configured in
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> (for
home directories of LUKS2 storage located on removable media this defaults to 0 though). A longer
time makes sure quick, repetitive logins are more efficient as the user's service manager does not
have to be started every time.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--kill-processes=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configures whether to kill all processes of the user on logout. The default is
configured in
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--auto-login=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Takes a boolean argument. Configures whether the graphical UI of the system should
automatically log this user in if possible. Defaults to off. If less or more than one user is marked
this way automatic login is disabled.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--session-launcher=<replaceable>LAUNCHER</replaceable></option></term>
<listitem><para>Takes a string argument. Configures the user's preferred session launcher
.desktop entry file (i.e. <literal>gnome</literal>, <literal>plasma</literal>, or other names that
appear in <filename>/usr/share/xesssions/</filename> or <filename>/usr/share/wayland-sessions</filename>).
This is read by the display manager to pick the default session that is launched when the user logs in.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--session-type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>Takes a string argument. Configures the user's preferred session type
(i.e. <literal>x11</literal>, <literal>wayland</literal>, and other values accepted by
<varname>$XDG_SESSION_TYPE</varname>). This is read by the display manage to pick the
default session type the user is logged into.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Commands</title>
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term><command>list</command></term>
<listitem><para>List all home directories (along with brief details) currently managed by
<filename>systemd-homed.service</filename>. This command is also executed if none is specified on the
command line. (Note that the list of users shown by this command does not include users managed by
other subsystems, such as system users or any traditional users listed in
<filename>/etc/passwd</filename>.)</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>activate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term>
<listitem><para>Activate one or more home directories. The home directories of each listed user will
be activated and made available under their mount points (typically in
<filename>/home/$USER</filename>). Note that any home activated this way stays active indefinitely,
until it is explicitly deactivated again (with <command>deactivate</command>, see below), or the user
logs in and out again and it thus is deactivated due to the automatic deactivation-on-logout
logic.</para>
<para>Activation of a home directory involves various operations that depend on the selected storage
mechanism. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a
password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file
system, mounting the file system, and potentially changing the ownership of all included files to the
correct UID/GID.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>deactivate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term>
<listitem><para>Deactivate one or more home directories. This undoes the effect of
<command>activate</command>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>inspect</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term>
<listitem><para>Show various details about the specified home directories. This shows various
information about the home directory and its user account, including runtime data such as current
state, disk use and similar. Combine with <option>--json=</option> to show the detailed JSON user
record instead, possibly combined with <option>--export-format=</option> to suppress certain aspects
of the output.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>authenticate</command> <replaceable>USER</replaceable> [<replaceable>USER…</replaceable>]</term>
<listitem><para>Validate authentication credentials of a home directory. This queries the caller for
a password (or similar) and checks that it correctly unlocks the home directory. This leaves the home
directory in the state it is in, i.e. it leaves the home directory in inactive state if it was
inactive before, and in active state if it was active before.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>create</command> <replaceable>USER</replaceable></term>
<term><command>create</command> <option>--identity=<replaceable>PATH</replaceable></option> <optional><replaceable>USER</replaceable></optional></term>
<listitem><para>Create a new home directory/user account of the specified name. Use the various
user record property options (as documented above) to control various aspects of the home directory
and its user accounts.</para>
<para>The specified user name should follow the strict syntax described on <ulink
url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>adopt</command> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>…]</term>
<listitem><para>Adopts one or more existing home directories on the local system. Takes one or more paths to
<filename>*.home</filename> LUKS home directories or <filename>*.homedir/</filename> standalone home
directories or subvolumes previously created by <filename>systemd-homed</filename> and makes them
available locally for login. The referenced files are not moved. This is an alternative for moving
such home directories into <filename>/home/</filename> (where they would be picked up
automatically).</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>register</command> <replaceable>FILE</replaceable> [<replaceable>FILE</replaceable>…]</term>
<listitem><para>Registers one or more users, without creating their home directories. Takes one or
more paths to JSON user record files. If the path is specified as <literal>-</literal> reads the
JSON user record from standard input.</para>
<para>Registering a user makes it accessible on the local system without creating a new home
directory. This is particularly useful for making a user accessible on a system it was not originally
created on.</para>
<para>Here's an example how to make a local user account with its home directory accessible on a
remote system, using SMB/CIFS file sharing. With Samba installed in its default configuration invoke
as <literal>root</literal>:</para>
<programlisting># smbpasswd -a lennart</programlisting>
<para>Continue as regular user <literal>lennart</literal>:</para>
<programlisting>$ homectl update lennart --ssh-authorized-keys=… -N --storage=cifs --cifs-service="//$HOSTNAME/lennart"
$ homectl get-signing-key | ssh targetsystem homectl add-signing-key --key-name="$HOSTNAME".public
$ homectl inspect -E lennart | ssh targetsystem homectl register -
$ ssh lennart@targetsystem</programlisting>
<para>This first ensures the user account <literal>lennart</literal> is known to and accessible by
Samba. It then registers a local SSH access that shall be used for accessing this user, and
configures CIFS as default storage for non-local systems on the account. It then adds the local
system's account signing key to the target system. Then it registers the local user account with the
target system. Finally it logs into the account on the target system. The target system will then
connect back via SMB/CIFS to access the home directory.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>unregister</command> <replaceable>USER</replaceable>…</term>
<listitem><para>Unregisters one or more user accounts. This only removes the user record from the
local system, it does not delete the home directory. The home directory can be readded via the
<command>register</command> or <command>adopt</command> command later, on this or another
system. Note that unregistering a user whose home directory is placed in <filename>/home/</filename>
will not make the user disappear from the local user database, as all supported home directories
placed there will show up in the user database. However, the user record will become "unfixated",
i.e. lose its binding to the local system. When logged into it will automatically regain the binding,
and acquire a local UID/GID pair.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>remove</command> <replaceable>USER</replaceable></term>
<listitem><para>Remove a home directory/user account. This will remove both the home directory's user
record and the home directory itself, and thus delete all files and directories owned by the
user.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>update</command> <replaceable>USER</replaceable></term>
<term><command>update</command> <option>--identity=<replaceable>PATH</replaceable></option> <optional><replaceable>USER</replaceable></optional></term>
<listitem><para>Update a home directory/user account. Use the various user record property options
(as documented above) to make changes to the account, or alternatively provide a full, updated JSON
user record via the <option>--identity=</option> option.</para>
<para>Note that changes to user records not signed by a cryptographic private key available locally
are not permitted, unless <option>--identity=</option> is used with a user record that is already
correctly signed by a recognized private key.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>passwd</command> <replaceable>USER</replaceable></term>
<listitem><para>Change the password of the specified home directory/user account.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>resize</command> <replaceable>USER</replaceable> <replaceable>BYTES</replaceable></term>
<listitem><para>Change the disk space assigned to the specified home directory. If the LUKS2 storage
mechanism is used this will automatically resize the loopback file and the file system contained
within. Note that if <literal>ext4</literal> is used inside of the LUKS2 volume, it is necessary to
deactivate the home directory before shrinking it (i.e the user has to log out). Growing can be done
while the home directory is active. If <literal>xfs</literal> is used inside of the LUKS2 volume the
home directory may not be shrunk whatsoever. On all three of <literal>ext4</literal>,
<literal>xfs</literal> and <literal>btrfs</literal> the home directory may be grown while the user is
logged in, and on the latter also shrunk while the user is logged in. If the
<literal>subvolume</literal>, <literal>directory</literal>, <literal>fscrypt</literal> storage
mechanisms are used, resizing will change file system quota. The size parameter may make use of the
usual suffixes B, K, M, G, T (to the base of 1024). The special strings <literal>min</literal> and
<literal>max</literal> may be specified in place of a numeric size value, for minimizing or
maximizing disk space assigned to the home area, taking constraints of the file system, disk usage inside
the home area and on the backing storage into account.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>lock</command> <replaceable>USER</replaceable></term>
<listitem><para>Temporarily suspend access to the user's home directory and remove any associated
cryptographic keys from memory. Any attempts to access the user's home directory will stall until the
home directory is unlocked again (i.e. re-authenticated). This functionality is primarily intended to
be used during system suspend to make sure the user's data cannot be accessed until the user
re-authenticates on resume. This operation is only defined for home directories that use the LUKS2
storage mechanism.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>unlock</command> <replaceable>USER</replaceable></term>
<listitem><para>Resume access to the user's home directory again, undoing the effect of
<command>lock</command> above. This requires authentication of the user, as the cryptographic keys
required for access to the home directory need to be reacquired.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>lock-all</command></term>
<listitem><para>Execute the <command>lock</command> command on all suitable home directories at
once. This operation is generally executed on system suspend (i.e. by <command>systemctl
suspend</command> and related commands), to ensure all active user's cryptographic keys for accessing
their home directories are removed from memory.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>deactivate-all</command></term>
<listitem><para>Execute the <command>deactivate</command> command on all active home directories at
once. This operation is generally executed on system shut down (i.e. by <command>systemctl
poweroff</command> and related commands), to ensure all active user's home directories are fully
deactivated before <filename>/home/</filename> and related file systems are unmounted.</para>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<term><command>with</command> <replaceable>USER</replaceable> <replaceable>COMMAND…</replaceable></term>
<listitem><para>Activate the specified user's home directory, run the specified command (under the
caller's identity, not the specified user's) and deactivate the home directory afterwards again
(unless the user is logged in otherwise). This command is useful for running privileged backup
scripts and such, but requires authentication with the user's credentials in order to be able to
unlock the user's home directory.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><command>rebalance</command></term>
<listitem><para>Rebalance free disk space between active home areas and the backing storage. See
<option>--rebalance-weight=</option> above. This executes no operation unless there's at least one
active LUKS2 home area that has disk space rebalancing enabled. This operation is synchronous: it
will only complete once disk space is rebalanced according to the rebalancing weights. Note that
rebalancing also takes place automatically in the background in regular intervals. Use this command
to synchronously ensure disk space is properly redistributed before initiating an operation requiring
large amounts of disk space.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<varlistentry>
<term><command>firstboot</command></term>
<listitem><para>This command is supposed to be invoked during the initial boot of the system. It
checks whether any regular home area exists so far, and if not queries the user interactively on the
console for user name and password and creates one (only if <option>--prompt-new-user</option> is
specified). Alternatively, if one or more service credentials whose name starts with
<literal>home.create.</literal> are passed to the command (containing a user record in JSON format)
these users are automatically created at boot.</para>
<para>This command is invoked by the <filename>systemd-homed-firstboot.service</filename> service
unit.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><command>list-signing-keys</command></term>
<listitem><para>Show a list of public keys that home directories can be signed with to be allowed for
local login. One such key (<filename>local.public</filename>) will be generated automatically for
signing locally created home directories, but additional public keys may be registered to accept home
directories from other origins too (see <command>add-signing-key</command> below).</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>get-signing-key</command> [<replaceable>NAME…</replaceable>]</term>
<listitem><para>Write the public key identified by the specified name to standard output (in PEM
format). If no name is specified defaults to <filename>local.public</filename>, i.e. the
automatically generated key for locally created home directories.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>add-signing-key</command> [<replaceable>FILE…</replaceable>]</term>
<listitem><para>Add public key(s) from the specified PEM key file(s) to the list of keys that home
areas have to be signed by to be permitted for local login. If a path of <literal>-</literal> is
specified, or if no file is specified at all, the key will be read from standard input. The key file
name(s) must carry the <filename>.public</filename> suffix, and the file name(s) will be used to name
the key(s) once added, too. If a key is added from standard input the key name must be specified
explicitly via <option>--key-name=</option>, see above.</para>
<para>This command is useful for permitting local home directories to be used on a remote
system. Example:</para>
<programlisting>homectl get-signing-key | ssh myotherhost homectl add-signing-key --key-name="$HOSTNAME".public</programlisting>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><command>remove-signing-key</command> <replaceable>NAME…</replaceable></term>
<listitem><para>Remove the public key identified by the specified name from the list of keys that
control from which origins to permit home directories for login.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Credentials</title>
<para>When invoked with the <command>firstboot</command> command, <command>homectl</command> supports the
service credentials logic as implemented by
<varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
(see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details). The following credentials are used when passed in:</para>
<variablelist class='system-credentials'>
<varlistentry>
<term><varname>home.create.*</varname></term>
<listitem><para>If one or more credentials whose names begin with <literal>home.create.</literal>,
followed by a valid UNIX username are passed, a new home area is created, one for each specified user
record.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Kernel Command Line</title>
<variablelist class='kernel-commandline-options'>
<varlistentry>
<term><varname>systemd.firstboot=</varname></term>
<listitem><para>This boolean will disable the effect of <command>homectl firstboot</command>
command. It's primarily interpreted by
<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
<para>When a command is invoked with <command>with</command>, the exit status of the child is
propagated. Effectively, <command>homectl</command> will exit without error if the command is
successfully invoked <emphasis>and</emphasis> finishes successfully.</para>
</refsect1>
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>
<example>
<title>Create a user <literal>waldo</literal> in the administrator group <literal>wheel</literal>, and
assign 500 MiB disk space to them.</title>
<programlisting>homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M</programlisting>
</example>
<example>
<title>Create a user <literal>wally</literal> on a USB stick, and assign a maximum of 500 concurrent
tasks to them.</title>
<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>
</example>
<example>
<title>Change nice level of user <literal>odlaw</literal> to +5 and make sure the environment variable
<varname>$SOME</varname> is set to the string <literal>THING</literal> for them on login.</title>
<programlisting>homectl update odlaw --nice=5 --setenv=SOME=THING</programlisting>
</example>
<example>
<title>Set up authentication with a YubiKey security token using PKCS#11/PIV:</title>
<programlisting># Clear the Yubikey from any old keys (careful!)
ykman piv reset
# Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'.
ykman piv generate-key -a RSA2048 9d pubkey.pem
# Create a self-signed certificate from this public key, and store it on the device.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
# We do not need the public key on disk anymore
rm pubkey.pem
# Allow the security token to unlock the account of user 'lafcadio'.
homectl update lafcadio --pkcs11-token-uri=auto</programlisting>
</example>
<example>
<title>Set up authentication with a FIDO2 security token:</title>
<programlisting># Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'.
homectl update nihilbaxter --fido2-device=auto</programlisting>
</example>
<example>
<title>Add a recovery key to an existing user account:</title>
<programlisting># Generate and add a recovery key for user 'emily'.
homectl update emily --recovery-key=yes</programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>