<?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">
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="homectl" conditional='ENABLE_HOMED'
<refnamediv>
<refname>homectl</refname>
+ <refname>systemd-homed-firstboot.service</refname>
<refpurpose>Create, remove, change or inspect home directories</refpurpose>
</refnamediv>
<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>
+ <literal>short</literal> otherwise.</para>
+
+ <xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
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 changing this option for existing home directories generally has no effect on home
+ directories that already have been registered locally (have a local <emphasis>binding</emphasis>), as
+ the UID used for an account on the local system is determined when the home directory is first
+ activated on it, and then remains in effect until the home directory is removed.</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>
user, including <option>--email=</option>, <option>--timezone=</option> and
<option>--language=</option>.</para>
- <xi:include href="version-info.xml" xpointer="v250"/></listitem>
+ <xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<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><para>Takes a comma- or colon-separated list of languages preferred by the user, ordered
+ by descending priority. The <varname>$LANG</varname> and <varname>$LANGUAGE</varname> environment
+ variables are initialized from this value on login, and thus values suitible for these environment
+ variables are accepted here, for example <option>--language=de_DE.UTF-8</option>. This option may
+ be used more than once, in which case the language lists are concatenated.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--blob=</option><replaceable>PATH</replaceable></term>
+ <term><option>-b</option> <replaceable>PATH</replaceable></term>
+ <term><option>--blob=</option><replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable></term>
+ <term><option>-b</option> <replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable></term>
+
+ <listitem><para>Accepts either a directory path, or a file name followed by a file path. If just a
+ directory path is specified, then the user's entire blob directory is replaced the specified path.
+ Note that this replacement is performed before per-file manipulations are applied, which means these per-file
+ manipulations will be applied on top of the specified directory. If a filename and file path are specified, then
+ the single specified blob file will be overwritten with the specified path. If completely blank, the entire blob
+ directory is emptied out (which also resets all previous blob-related flags up to this point). If a filename is
+ specified but the corresponding path is blank, that single file will be deleted from the blob directory. All changes
+ are performed in temporary copies of the specified files in directories, which means that the originals specified on
+ the command line are not modified. See <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink>
+ for more information about blob directories.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--avatar=</option><replaceable>PATH</replaceable></term>
+ <term><option>--login-background=</option><replaceable>PATH</replaceable></term>
+
+ <listitem><para>Accept a file path. If set, the specified file is used to overwrite the
+ corresponding file in the user's blob directory. If blank, the corresponding file is deleted
+ from the blob directory. Essentially, these options are shortcuts to
+ <option>--blob=</option><replaceable>FILENAME</replaceable>=<replaceable>PATH</replaceable>
+ for the known filenames defined in
+ <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--locked=</option><replaceable>BOOLEAN</replaceable></term>
<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>
+ uses bits.</para>
+
+ <xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
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>
+ for details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--session-launcher=</option><replaceable>LAUNCHER</replaceable></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=</option><replaceable>TYPE</replaceable></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>
<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. 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>
+ </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>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>
+ <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>