mirror of
https://github.com/systemd/systemd.git
synced 2024-10-29 21:55:36 +03:00
b72308d344
Fixes #22966. Since there are competing conventions, let's not change our code, but make the docs match what is implemented.
1058 lines
63 KiB
XML
1058 lines
63 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="homectl" conditional='ENABLE_HOMED'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>homectl</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>homectl</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>homectl</refname>
|
|
<refpurpose>Create, remove, change or inspect home directories</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>homectl</command>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
<arg choice="req">COMMAND</arg>
|
|
<arg choice="opt" rep="repeat">NAME</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><command>homectl</command> may be used to create, remove, change or inspect a user's home
|
|
directory. It's primarily a command interfacing with
|
|
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
which manages home directories of users.</para>
|
|
|
|
<para>Home directories managed by <filename>systemd-homed.service</filename> are self-contained, and thus
|
|
include the user's full metadata record in the home's data storage itself, making them easy to migrate
|
|
between machines. In particular, a home directory describes a matching user record, and every user record
|
|
managed by <filename>systemd-homed.service</filename> also implies existence and encapsulation of a home
|
|
directory. The user account and home directory become the same concept.</para>
|
|
|
|
<para>The following backing storage mechanisms are supported:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>An individual LUKS2 encrypted loopback file for a user, stored in
|
|
<filename>/home/*.home</filename>. At login the file system contained in this files is mounted, after
|
|
the LUKS2 encrypted volume has been attached. The user's password is identical to the encryption
|
|
passphrase of the LUKS2 volume. Access to data without preceding user authentication is thus not
|
|
possible, even for the system administrator. This storage mechanism provides the strongest data
|
|
security and is thus recommended.</para></listitem>
|
|
|
|
<listitem><para>Similar, but the LUKS2 encrypted file system is located on regular block device, such
|
|
as an USB storage stick. In this mode home directories and all data they include are nicely migratable
|
|
between machines, simply by plugging the USB stick into different systems at different
|
|
times.</para></listitem>
|
|
|
|
<listitem><para>An encrypted directory using <literal>fscrypt</literal> on file systems that support it
|
|
(at the moment this is primarily <literal>ext4</literal>), located in
|
|
<filename>/home/*.homedir</filename>. This mechanism also provides encryption, but substantially
|
|
weaker than LUKS2, as most file system metadata is unprotected. Moreover
|
|
it currently does not support changing user passwords once the home directory has been
|
|
created.</para></listitem>
|
|
|
|
<listitem><para>A <literal>btrfs</literal> subvolume for each user, also located in
|
|
<filename>/home/*.homedir</filename>. This provides no encryption, but good quota
|
|
support.</para></listitem>
|
|
|
|
<listitem><para>A regular directory for each user, also located in
|
|
<filename>/home/*.homedir</filename>. This provides no encryption, but is a suitable fallback
|
|
available on all machines, even where LUKS2, <literal>fscrypt</literal> or <literal>btrfs</literal>
|
|
support is not available.</para></listitem>
|
|
|
|
<listitem><para>An individual Windows file share (CIFS) for each user.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Note that <filename>systemd-homed.service</filename> and <command>homectl</command> will not manage
|
|
"classic" UNIX user accounts as created with <citerefentry
|
|
project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
|
|
similar tools. In particular, this functionality is not suitable for managing system users (i.e. users
|
|
with a UID below 1000) but is exclusive to regular ("human") users.</para>
|
|
|
|
<para>Note that users/home directories managed via <command>systemd-homed.service</command> do not show
|
|
up in <filename>/etc/passwd</filename> and similar files, they are synthesized via glibc NSS during
|
|
runtime. They are thus resolvable and may be enumerated via the <citerefentry
|
|
project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
tool.</para>
|
|
|
|
<para>This tool interfaces directly with <filename>systemd-homed.service</filename>, and may execute
|
|
specific commands on the home directories it manages. Since every home directory managed that way also
|
|
defines a JSON user and group record these home directories may also be inspected and enumerated via
|
|
<citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
|
|
|
|
<para>Home directories managed by <filename>systemd-homed.service</filename> are usually in one of two
|
|
states, or in a transition state between them: when <literal>active</literal> they are unlocked and
|
|
mounted, and thus accessible to the system and its programs; when <literal>inactive</literal> they are
|
|
not mounted and thus not accessible. Activation happens automatically at login of the user and usually
|
|
can only complete after a password (or other authentication token) has been supplied. Deactivation
|
|
happens after the user fully logged out. A home directory remains active as long as the user is logged in
|
|
at least once, i.e. has at least one login session. When the user logs in a second time simultaneously
|
|
the home directory remains active. It is deactivated only after the last of the user's sessions
|
|
ends.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>The following general options are understood (further options that control the various properties
|
|
of user records managed by <filename>systemd-homed.service</filename> are documented further
|
|
down):</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--identity=</option><replaceable>FILE</replaceable></term>
|
|
|
|
<listitem><para>Read the user's JSON record from the specified file. If passed as
|
|
<literal>-</literal> read the user record from standard input. The supplied JSON object must follow
|
|
the structure documented in <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink>.
|
|
This option may be used in conjunction with the <command>create</command> and
|
|
<command>update</command> commands (see below), where it allows configuring the user record in JSON
|
|
as-is, instead of setting the individual user record properties (see below).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--json=</option><replaceable>FORMAT</replaceable></term>
|
|
<term><option>-j</option></term>
|
|
|
|
<listitem><para>Controls whether to output the user record in JSON format, if the
|
|
<command>inspect</command> command (see below) is used. Takes one of <literal>pretty</literal>,
|
|
<literal>short</literal> or <literal>off</literal>. If <literal>pretty</literal> human-friendly
|
|
whitespace and newlines are inserted in the output to make the JSON data more readable. If
|
|
<literal>short</literal> all superfluous whitespace is suppressed. If <literal>off</literal> (the
|
|
default) the user information is not shown in JSON format but in a friendly human readable formatting
|
|
instead. The <option>-j</option> option picks <literal>pretty</literal> when run interactively and
|
|
<literal>short</literal> otherwise.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--export-format=</option><replaceable>FORMAT</replaceable></term>
|
|
<term><option>-E</option></term>
|
|
<term><option>-EE</option></term>
|
|
|
|
<listitem><para>When used with the <command>inspect</command> verb in JSON mode (see above) may be
|
|
used to suppress certain aspects of the JSON user record on output. Specifically, if
|
|
<literal>stripped</literal> format is used the binding and runtime fields of the record are
|
|
removed. If <literal>minimal</literal> format is used the cryptographic signature is removed too. If
|
|
<literal>full</literal> format is used the full JSON record is shown (this is the default). This
|
|
option is useful for copying an existing user record to a different system in order to create a
|
|
similar user there with the same settings. Specifically: <command>homectl inspect -EE | ssh
|
|
root@othersystem homectl create -i-</command> may be used as simple command line for replicating a
|
|
user on another host. <option>-E</option> is equivalent to <option>-j --export-format=stripped</option>,
|
|
<option>-EE</option> to <option>-j --export-format=minimal</option>. Note that when replicating user
|
|
accounts user records acquired in <literal>stripped</literal> mode will retain the original
|
|
cryptographic signatures and thus may only be modified when the private key to update them is available
|
|
on the destination machine. When replicating users in <literal>minimal</literal> mode, the signature
|
|
is removed during the replication and thus the record will be implicitly signed with the key of the destination
|
|
machine and may be updated there without any private key replication.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<xi:include href="user-system-options.xml" xpointer="host" />
|
|
<xi:include href="user-system-options.xml" xpointer="machine" />
|
|
|
|
<xi:include href="standard-options.xml" xpointer="no-pager" />
|
|
<xi:include href="standard-options.xml" xpointer="no-legend" />
|
|
<xi:include href="standard-options.xml" xpointer="no-ask-password" />
|
|
<xi:include href="standard-options.xml" xpointer="help" />
|
|
<xi:include href="standard-options.xml" xpointer="version" />
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>User Record Properties</title>
|
|
|
|
<para>The following options control various properties of the user records/home directories that
|
|
<filename>systemd-homed.service</filename> manages. These switches may be used in conjunction with the
|
|
<command>create</command> and <command>update</command> commands for configuring various aspects of the
|
|
home directory and the user account:</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--real-name=</option><replaceable>NAME</replaceable></term>
|
|
<term><option>-c</option> <replaceable>NAME</replaceable></term>
|
|
|
|
<listitem><para>The real name for the user. This corresponds with the GECOS field on classic UNIX NSS
|
|
records.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--realm=</option><replaceable>REALM</replaceable></term>
|
|
|
|
<listitem><para>The realm for the user. The realm associates a user with a specific organization or
|
|
installation, and allows distinguishing users of the same name defined in different contexts. The
|
|
realm can be any string that also qualifies as valid DNS domain name, and it is recommended to use
|
|
the organization's or installation's domain name for this purpose, but this is not enforced nor
|
|
required. On each system only a single user of the same name may exist, and if a user with the same
|
|
name and realm is seen it is assumed to refer to the same user while a user with the same name but
|
|
different realm is considered a different user. Note that this means that two users sharing the same
|
|
name but with distinct realms are not allowed on the same system. Assigning a realm to a user is
|
|
optional.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--email-address=</option><replaceable>EMAIL</replaceable></term>
|
|
|
|
<listitem><para>Takes an electronic mail address to associate with the user. On log-in the
|
|
<varname>$EMAIL</varname> environment variable is initialized from this value.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--location=</option><replaceable>TEXT</replaceable></term>
|
|
|
|
<listitem><para>Takes location specification for this user. This is free-form text, which might or
|
|
might not be usable by geo-location applications. Example: <option>--location="Berlin,
|
|
Germany"</option> or <option>--location="Basement, Room 3a"</option></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--icon-name=</option><replaceable>ICON</replaceable></term>
|
|
|
|
<listitem><para>Takes an icon name to associate with the user, following the scheme defined by the <ulink
|
|
url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon Naming
|
|
Specification</ulink>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--home-dir=</option><replaceable>PATH</replaceable></term>
|
|
<term><option>-d</option><replaceable>PATH</replaceable></term>
|
|
|
|
<listitem><para>Takes a path to use as home directory for the user. Note that this is the directory
|
|
the user's home directory is mounted to while the user is logged in. This is not where the user's
|
|
data is actually stored, see <option>--image-path=</option> for that. If not specified defaults to
|
|
<filename>/home/$USER</filename>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--uid=</option><replaceable>UID</replaceable></term>
|
|
|
|
<listitem><para>Takes a preferred numeric UNIX UID to assign this user. If a user is to be created
|
|
with the specified UID and it is already taken by a different user on the local system then creation
|
|
of the home directory is refused. Note though, if after creating the home directory it is used on a
|
|
different system and the configured UID is taken by another user there, then
|
|
<command>systemd-homed</command> may assign the user a different UID on that system. The specified
|
|
UID must be outside of the system user range. It is recommended to use the 60001…60513 UID range for
|
|
this purpose. If not specified, the UID is automatically picked. If the home directory is found to be
|
|
owned by a different UID when logging in, the home directory and everything underneath it will have
|
|
its ownership changed automatically before login completes.</para>
|
|
|
|
<para>Note that users managed by <command>systemd-homed</command> always have a matching group
|
|
associated with the same name as well as a GID matching the UID of the user. Thus, configuring the
|
|
GID separately is not permitted.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--member-of=</option><replaceable>GROUP</replaceable></term>
|
|
<term><option>-G</option> <replaceable>GROUP</replaceable></term>
|
|
|
|
<listitem><para>Takes a comma-separated list of auxiliary UNIX groups this user shall belong
|
|
to. Example: <option>--member-of=wheel</option> to provide the user with administrator
|
|
privileges. Note that <command>systemd-homed</command> does not manage any groups besides a group
|
|
matching the user in name and numeric UID/GID. Thus any groups listed here must be registered
|
|
independently, for example with <citerefentry
|
|
project='man-pages'><refentrytitle>groupadd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
|
Any non-existent groups are ignored. This option may be used more than once, in which case all
|
|
specified group lists are combined. If the user is currently a member of a group which is not listed,
|
|
the user will be removed from the group.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--skel=</option><replaceable>PATH</replaceable></term>
|
|
|
|
<listitem><para>Takes a file system path to a directory. Specifies the skeleton directory to
|
|
initialize the home directory with. All files and directories in the specified path are copied into
|
|
any newly create home directory. If not specified defaults to <filename>/etc/skel/</filename>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--shell=</option><replaceable>SHELL</replaceable></term>
|
|
|
|
<listitem><para>Takes a file system path. Specifies the shell binary to execute on terminal
|
|
logins. If not specified defaults to <filename>/bin/bash</filename>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--setenv=</option><replaceable>VARIABLE</replaceable>[=<replaceable>VALUE</replaceable>]</term>
|
|
|
|
<listitem><para>Takes an environment variable assignment to set for all user processes. May be used
|
|
multiple times to set multiple environment variables. When <literal>=</literal> and
|
|
<replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
|
|
program environment will be used.</para>
|
|
|
|
<para>Note that a number of other settings also result in environment variables to be set for the
|
|
user, including <option>--email=</option>, <option>--timezone=</option> and
|
|
<option>--language=</option>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--timezone=</option><replaceable>TIMEZONE</replaceable></term>
|
|
|
|
<listitem><para>Takes a time zone location name that sets the timezone for the specified user. When
|
|
the user logs in the <varname>$TZ</varname> environment variable is initialized from this
|
|
setting. Example: <option>--timezone=Europe/Amsterdam</option> will result in the environment
|
|
variable <literal>TZ=:Europe/Amsterdam</literal>. (<literal>:</literal> is used intentionally as part
|
|
of the timezone specification, see
|
|
<citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--language=</option><replaceable>LANG</replaceable></term>
|
|
|
|
<listitem><para>Takes a specifier indicating the preferred language of the user. The
|
|
<varname>$LANG</varname> environment variable is initialized from this value on login, and thus a
|
|
value suitable for this environment variable is accepted here, for example
|
|
<option>--language=de_DE.UTF8</option>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--ssh-authorized-keys=</option><replaceable>KEYS</replaceable></term>
|
|
<listitem><para>Either takes a SSH authorized key line to associate with the user record or a
|
|
<literal>@</literal> character followed by a path to a file to read one or more such lines from. SSH
|
|
keys configured this way are made available to SSH to permit access to this home directory and user
|
|
record. This option may be used more than once to configure multiple SSH keys.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term>
|
|
<listitem><para>Takes an RFC 7512 PKCS#11 URI referencing a security token (e.g. YubiKey or PIV
|
|
smartcard) that shall be able to unlock the user account. The security token URI should reference a
|
|
security token with exactly one pair of X.509 certificate and private key. A random secret key is
|
|
then generated, encrypted with the public key of the X.509 certificate, and stored as part of the
|
|
user record. At login time it is decrypted with the PKCS#11 module and then used to unlock the
|
|
account and associated resources. See below for an example how to set up authentication with a
|
|
security token.</para>
|
|
|
|
<para>Instead of a valid PKCS#11 URI, the special strings <literal>list</literal> and
|
|
<literal>auto</literal> may be specified. If <literal>list</literal> is passed, a brief table of
|
|
suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs. If
|
|
<literal>auto</literal> is passed, a suitable PKCS#11 hardware token is automatically selected (this
|
|
operation will fail if there isn't exactly one suitable token discovered). The latter is a useful
|
|
shortcut for the most common case where a single PKCS#11 hardware token is plugged in.</para>
|
|
|
|
<para>Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the
|
|
<literal>hmac-secret</literal> extension (for example: the YubiKey 5 series), as supported with the
|
|
<option>--fido2-device=</option> option below. Both mechanisms are similarly powerful, though FIDO2
|
|
is the more modern technology. PKCS#11/PIV tokens have the benefit of being recognizable before
|
|
authentication and hence can be used for implying the user identity to use for logging in, which
|
|
FIDO2 does not allow. PKCS#11/PIV devices generally require initialization (i.e. storing a
|
|
private/public key pair on them, see example below) before they can be used; FIDO2 security tokens
|
|
generally do not required that, and work out of the box.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fido2-credential-algorithm=</option><replaceable>STRING</replaceable></term>
|
|
<listitem><para>Specify COSE algorithm used in credential generation. The default value is
|
|
<literal>es256</literal>. Supported values are <literal>es256</literal>, <literal>rs256</literal>
|
|
and <literal>eddsa</literal>.</para>
|
|
|
|
<para><literal>es256</literal> denotes ECDSA over NIST P-256 with SHA-256. <literal>rs256</literal>
|
|
denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. <literal>eddsa</literal> denotes
|
|
EDDSA over Curve25519 with SHA-512.</para>
|
|
|
|
<para>Note that your authenticator may not support some algorithms.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fido2-device=</option><replaceable>PATH</replaceable></term>
|
|
|
|
<listitem><para>Takes a path to a Linux <literal>hidraw</literal> device
|
|
(e.g. <filename>/dev/hidraw1</filename>), referring to a FIDO2 security token implementing the
|
|
<literal>hmac-secret</literal> extension that shall be able to unlock the user account. A random salt
|
|
value is generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the
|
|
salt using an internal secret key. The result is then used as the key to unlock the user account. The
|
|
random salt is included in the user record, so that whenever authentication is needed it can be
|
|
passed to the FIDO2 token again.</para>
|
|
|
|
<para>Instead of a valid path to a FIDO2 <literal>hidraw</literal> device the special strings
|
|
<literal>list</literal> and <literal>auto</literal> may be specified. If <literal>list</literal> is
|
|
passed, a brief table of suitable discovered FIDO2 devices is shown. If <literal>auto</literal> is
|
|
passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered. The latter is
|
|
a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in.</para>
|
|
|
|
<para>Note that FIDO2 devices suitable for this option must implement the
|
|
<literal>hmac-secret</literal> extension. Most current devices (such as the YubiKey 5 series) do. If
|
|
the extension is not implemented the device cannot be used for unlocking home directories.</para>
|
|
|
|
<para>The FIDO2 device may be subsequently removed by setting the device path to an empty string
|
|
(e.g. <command>homectl update $USER --fido2-device=""</command>).</para>
|
|
|
|
<para>Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be
|
|
used with either <option>--fido2-device=</option> or <option>--pkcs11-token-uri=</option>), for a
|
|
discussion see above.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fido2-with-client-pin=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter
|
|
a PIN when unlocking the account (the FIDO2 <literal>clientPin</literal> feature). Defaults to
|
|
<literal>yes</literal>. (Note: this setting is without effect if the security token does not support
|
|
the <literal>clientPin</literal> feature at all, or does not allow enabling or disabling
|
|
it.)</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fido2-with-user-presence=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to
|
|
verify presence (tap the token, the FIDO2 <literal>up</literal> feature) when unlocking the account.
|
|
Defaults to <literal>yes</literal>. (Note: this setting is without effect if the security token does not support
|
|
the <literal>up</literal> feature at all, or does not allow enabling or disabling it.)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fido2-with-user-verification=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>When enrolling a FIDO2 security token, controls whether to require user verification
|
|
when unlocking the account (the FIDO2 <literal>uv</literal> feature). Defaults to
|
|
<literal>no</literal>. (Note: this setting is without effect if the security token does not support
|
|
the <literal>uv</literal> feature at all, or does not allow enabling or disabling it.)</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--recovery-key=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>Accepts a boolean argument. If enabled a recovery key is configured for the
|
|
account. A recovery key is a computer generated access key that may be used to regain access to an
|
|
account if the password has been forgotten or the authentication token lost. The key is generated and
|
|
shown on screen, and should be printed or otherwise transferred to a secure location. A recovery key
|
|
may be entered instead of a regular password to unlock the account.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--locked=</option><replaceable>BOOLEAN</replaceable></term>
|
|
|
|
<listitem><para>Takes a boolean argument. Specifies whether this user account shall be locked. If
|
|
true logins into this account are prohibited, if false (the default) they are permitted (of course,
|
|
only if authorization otherwise succeeds).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--not-before=</option><replaceable>TIMESTAMP</replaceable></term>
|
|
<term><option>--not-after=</option><replaceable>TIMESTAMP</replaceable></term>
|
|
|
|
<listitem><para>These options take a timestamp string, in the format documented in
|
|
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
|
|
configures points in time before and after logins into this account are not
|
|
permitted.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--rate-limit-interval=</option><replaceable>SECS</replaceable></term>
|
|
<term><option>--rate-limit-burst=</option><replaceable>NUMBER</replaceable></term>
|
|
|
|
<listitem><para>Configures a rate limit on authentication attempts for this user. If the user
|
|
attempts to authenticate more often than the specified number, on a specific system, within the
|
|
specified time interval authentication is refused until the time interval passes. Defaults to 10
|
|
times per 1min.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--password-hint=</option><replaceable>TEXT</replaceable></term>
|
|
|
|
<listitem><para>Takes a password hint to store alongside the user record. This string is stored
|
|
accessible only to privileged users and the user itself and may not be queried by other users.
|
|
Example: <option>--password-hint="My first pet's name"</option>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--enforce-password-policy=</option><replaceable>BOOL</replaceable></term>
|
|
<term><option>-P</option></term>
|
|
|
|
<listitem><para>Takes a boolean argument. Configures whether to enforce the system's password policy
|
|
for this user, regarding quality and strength of selected passwords. Defaults to
|
|
on. <option>-P</option> is short for
|
|
<option>---enforce-password-policy=no</option>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--password-change-now=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>Takes a boolean argument. If true the user is asked to change their password on next
|
|
login.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--password-change-min=</option><replaceable>TIME</replaceable></term>
|
|
<term><option>--password-change-max=</option><replaceable>TIME</replaceable></term>
|
|
<term><option>--password-change-warn=</option><replaceable>TIME</replaceable></term>
|
|
<term><option>--password-change-inactive=</option><replaceable>TIME</replaceable></term>
|
|
|
|
<listitem><para>Each of these options takes a time span specification as argument (in the syntax
|
|
documented in
|
|
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) and
|
|
configures various aspects of the user's password expiration policy. Specifically,
|
|
<option>--password-change-min=</option> configures how much time has to pass after changing the
|
|
password of the user until the password may be changed again. If the user tries to change their
|
|
password before this time passes the attempt is refused. <option>--password-change-max=</option>
|
|
configures how soon after it has been changed the password expires and needs to be changed again.
|
|
After this time passes logging in may only proceed after the password is changed.
|
|
<option>--password-change-warn=</option> specifies how much earlier than then the time configured
|
|
with <option>--password-change-max=</option> the user is warned at login to change their password as
|
|
it will expire soon. Finally <option>--password-change-inactive=</option> configures the time which
|
|
has to pass after the password as expired until the user is not permitted to log in or change the
|
|
password anymore. Note that these options only apply to password authentication, and do not apply to
|
|
other forms of authentication, for example PKCS#11-based security token
|
|
authentication.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--disk-size=</option><replaceable>BYTES</replaceable></term>
|
|
<listitem><para>Either takes a size in bytes as argument (possibly using the usual K, M, G, …
|
|
suffixes for 1024 base values), a percentage value, or the special strings <literal>min</literal> or
|
|
<literal>max</literal>, and configures the disk space to assign to the user. If a percentage value is
|
|
specified (i.e. the argument suffixed with <literal>%</literal>) it is taken relative to the
|
|
available disk space of the backing file system. If specified as <literal>min</literal> assigns the
|
|
minimal disk space permitted by the constraints of the backing file system and other limits, when
|
|
specified as <literal>max</literal> assigns the maximum disk space available. If the LUKS2 backend is
|
|
used this configures the size of the loopback file and file system contained therein. For the other
|
|
storage backends configures disk quota using the filesystem's native quota logic, if available. If
|
|
not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for
|
|
the others.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--access-mode=</option><replaceable>MODE</replaceable></term>
|
|
|
|
<listitem><para>Takes a UNIX file access mode written in octal. Configures the access mode of the
|
|
home directory itself. Note that this is only used when the directory is first created, and the user
|
|
may change this any time afterwards. Example:
|
|
<option>--access-mode=0700</option></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--umask=</option><replaceable>MASK</replaceable></term>
|
|
|
|
<listitem><para>Takes the access mode mask (in octal syntax) to apply to newly created files and
|
|
directories of the user ("umask"). If set this controls the initial umask set for all login sessions of
|
|
the user, possibly overriding the system's defaults.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--nice=</option><replaceable>NICE</replaceable></term>
|
|
|
|
<listitem><para>Takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login
|
|
time. Takes a numeric value in the range -20 (highest priority) to 19 (lowest priority).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--rlimit=</option><replaceable>LIMIT</replaceable>=<replaceable>VALUE</replaceable><optional>:<replaceable>VALUE</replaceable></optional></term>
|
|
|
|
<listitem><para>Allows configuration of resource limits for processes of this user, see <citerefentry
|
|
project='man-pages'><refentrytitle>getrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
|
for details. Takes a resource limit name (e.g. <literal>LIMIT_NOFILE</literal>) followed by an equal
|
|
sign, followed by a numeric limit. Optionally, separated by colon a second numeric limit may be
|
|
specified. If two are specified this refers to the soft and hard limits, respectively. If only one
|
|
limit is specified the setting sets both limits in one.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--tasks-max=</option><replaceable>TASKS</replaceable></term>
|
|
|
|
<listitem><para>Takes a non-zero unsigned integer as argument. Configures the maximum number of tasks
|
|
(i.e. threads, where each process is at least one thread) the user may have at any given time. This
|
|
limit applies to all tasks forked off the user's sessions, even if they change user identity via
|
|
<citerefentry project='man-pages'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
or a similar tool. Use <option>--rlimit=LIMIT_NPROC=</option> to place a limit on the tasks actually
|
|
running under the UID of the user, thus excluding any child processes that might have changed user
|
|
identity. This controls the <varname>TasksMax=</varname> setting of the per-user systemd slice unit
|
|
<filename>user-$UID.slice</filename>. See
|
|
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for further details.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--memory-high=</option><replaceable>BYTES</replaceable></term>
|
|
<term><option>--memory-max=</option><replaceable>BYTES</replaceable></term>
|
|
|
|
<listitem><para>Set a limit on the memory a user may take up on a system at any given time in bytes
|
|
(the usual K, M, G, … suffixes are supported, to the base of 1024). This includes all memory used by
|
|
the user itself and all processes they forked off that changed user credentials. This controls the
|
|
<varname>MemoryHigh=</varname> and <varname>MemoryMax=</varname> settings of the per-user systemd
|
|
slice unit <filename>user-$UID.slice</filename>. See
|
|
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for further details.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--cpu-weight=</option><replaceable>WEIGHT</replaceable></term>
|
|
<term><option>--io-weight=</option><replaceable>WEIGHT</replaceable></term>
|
|
|
|
<listitem><para>Set CPU and IO scheduling weights of the processes of the user, including those of
|
|
processes forked off by the user that changed user credentials. Takes a numeric value in the range
|
|
1…10000. This controls the <varname>CPUWeight=</varname> and <varname>IOWeight=</varname> settings of
|
|
the per-user systemd slice unit <filename>user-$UID.slice</filename>. See
|
|
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for further details.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--storage=</option><replaceable>STORAGE</replaceable></term>
|
|
|
|
<listitem><para>Selects the storage mechanism to use for this home directory. Takes one of
|
|
<literal>luks</literal>, <literal>fscrypt</literal>, <literal>directory</literal>,
|
|
<literal>subvolume</literal>, <literal>cifs</literal>. For details about these mechanisms, see
|
|
above. If a new home directory is created and the storage type is not specifically specified,
|
|
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
defines which default storage to use.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--image-path=</option><replaceable>PATH</replaceable></term>
|
|
|
|
<listitem><para>Takes a file system path. Configures where to place the user's home directory. When
|
|
LUKS2 storage is used refers to the path to the loopback file, otherwise to the path to the home
|
|
directory (which may be in <filename>/home/</filename> or any other accessible filesystem). When
|
|
unspecified defaults to <filename>/home/$USER.home</filename> when LUKS storage is used and
|
|
<filename>/home/$USER.homedir</filename> for the other storage mechanisms. Not defined for the
|
|
<literal>cifs</literal> storage mechanism. To use LUKS2 storage on a regular block device (for
|
|
example a USB stick) pass the path to the block device here. Specifying the path to a directory here
|
|
when using LUKS2 storage is not allowed. Similar, specifying the path to a regular file or device
|
|
node is not allowed if any of the other storage backends are used.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--drop-caches=</option><replaceable>BOOL</replaceable></term>
|
|
|
|
<listitem><para>Automatically flush OS file system caches on logout. This is useful in combination
|
|
with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and
|
|
directories in memory (and accessible) after logout. This option is also supported on other backends,
|
|
but should not bring any benefit there. Defaults to off, except if the selected storage backend is
|
|
fscrypt, where it defaults to on. Note that flushing OS caches will negatively influence performance
|
|
of the OS shortly after logout.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fs-type=</option><replaceable>TYPE</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--luks-discard=</option><replaceable>BOOL</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--luks-offline-discard=</option><replaceable>BOOL</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--luks-extra-mount-options=</option><replaceable>OPTIONS</replaceable></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.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--luks-cipher=</option><replaceable>CIPHER</replaceable></term>
|
|
<term><option>--luks-cipher-mode=</option><replaceable>MODE</replaceable></term>
|
|
<term><option>--luks-volume-key-size=</option><replaceable>BYTES</replaceable></term>
|
|
<term><option>--luks-pbkdf-type=</option><replaceable>TYPE</replaceable></term>
|
|
<term><option>--luks-pbkdf-hash-algorithm=</option><replaceable>ALGORITHM</replaceable></term>
|
|
<term><option>--luks-pbkdf-time-cost=</option><replaceable>SECONDS</replaceable></term>
|
|
<term><option>--luks-pbkdf-memory-cost=</option><replaceable>BYTES</replaceable></term>
|
|
<term><option>--luks-pbkdf-parallel-threads=</option><replaceable>THREADS</replaceable></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></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></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--nosuid=</option><replaceable>BOOL</replaceable></term>
|
|
<term><option>--nodev=</option><replaceable>BOOL</replaceable></term>
|
|
<term><option>--noexec=</option><replaceable>BOOL</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--cifs-domain=</option><replaceable>DOMAIN</replaceable></term>
|
|
<term><option>--cifs-user-name=</option><replaceable>USER</replaceable></term>
|
|
<term><option>--cifs-service=</option><replaceable>SERVICE</replaceable></term>
|
|
<term><option>--cifs-extra-mount-options=</option><replaceable>OPTIONS</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--stop-delay=</option><replaceable>SECS</replaceable></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 doesn't
|
|
have to be started every time.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--kill-processes=</option><replaceable>BOOL</replaceable></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--auto-login=</option><replaceable>BOOL</replaceable></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></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></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></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></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></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>create</command> <replaceable>USER</replaceable></term>
|
|
<term><command>create</command> <option>--identity=</option><replaceable>PATH</replaceable> <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></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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>update</command> <replaceable>USER</replaceable></term>
|
|
<term><command>update</command> <option>--identity=</option><replaceable>PATH</replaceable> <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></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>passwd</command> <replaceable>USER</replaceable></term>
|
|
|
|
<listitem><para>Change the password of the specified home directory/user account.</para></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></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></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></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></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></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></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></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 don't 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>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<citerefentry project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|