HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/homectl.xml

95,551 bytesGit mode 100644Download original fileLGPL-2.1-or-later

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>