`devShmLimit`, `devShmLimitScale` → Similar to the previous two, but apply to
`/dev/shm/` rather than `/tmp/`.
+`defaultArea` → The default home directory "area" to enter after logging
+in. Areas are named subdirectories below `~/Areas/` of the user, and can be used
+to maintain separate secondary home directories within the primary home
+directory of the user. Typically, a home directory "area" can be specified at
+login time, but if that's not done, and `defaultArea` is set, this area is
+selected. The value must be a string that qualifies as a valid filename. After
+login, the `$HOME` environment variable will point to `~/Areas/` of the user,
+suffixed by the selected area name, and `$XDG_AREA` will be set to the area
+string (unprefixed).
+
`privileged` → An object, which contains the fields of the `privileged` section
of the user record, see below.
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--default-area=<replaceable>AREA</replaceable></option></term>
+
+ <listitem><para>Takes a string identifying a home directory "area" to use as default. Areas are
+ secondary home directories within the primary home directory of a user. When logging in a user can
+ specify the area they wish to log into, which ensures that the <varname>$HOME</varname> environment
+ variable is set to <filename>~/Areas/</filename> suffixed by the area name.</para>
+
+ <para>For details on the area concept see
+ <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Note
+ that this option just defines the default, which can be overridden at login time.</para>
+
+ <para>When this option is specified with an empty string as value any previously declared default area
+ is removed from the user record.</para>
+
+ <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>area=</varname></term>
+
+ <listitem><para>Takes a filename as parameter. If specified and the user logs into their account the
+ <varname>$HOME</varname> environment variable will be set to <filename>~/Areas/</filename> suffixed
+ by the specified string, but only if that directory exists. Moreover, the
+ <varname>$XDG_AREA</varname> variable will be set to the (unprefixed) parameter.</para>
+
+ <para>This functionality may be used to maintain multiple separate secondary home directories within
+ the primary home directory of the user. Typically, the area to log into is specified while logging
+ in, if the account permits that (accounts provided by
+ <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ do), but this parameter may be used to define a default if that's not provided.</para>
+
+ <para>Note that this only adjusts <varname>$HOME</varname> during login, it does not affect the
+ otherwise reported home directory of the user. Specifically this means that <citerefentry
+ project='man-pages'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
+ continue to look for SSH keys of the user only in the primary home directory of the user, not in any
+ of their areas.</para>
+
+ <para>Note that the default area to log into can also be configured as part of the user account. The
+ area specified via <varname>area=</varname> overrides the default area configured there. Also note
+ that if the area is specified explicitly by the user at login time, it overrides both. Also note that
+ setting this parameter to an empty string has the effect of undoing the effect of any default area
+ configured as part of the user record, i.e. ensuring the user logs into the primary home directory of
+ their account.</para>
+
+ <para>For details on the area concept see
+ <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>default-capability-bounding-set=</varname></term>
<term><varname>default-capability-ambient-set=</varname></term>
<xi:include href="version-info.xml" xpointer="v209"/></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>$XDG_AREA</varname></term>
+
+ <listitem><para>If an area (secondary home directories of the user, within the primary home
+ directory) to log into has been selected this variable is set to the area name (without any path
+ prefix). It is otherwise unset. For details about areas, see above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+ </varlistentry>
</variablelist>
<para>If not set, <command>pam_systemd</command> will initialize
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Home Area Support</title>
+
+ <para>Home directories managed by
+ <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ support multiple home "areas", which are additional secondary home directories of the user within the
+ primary home directory. An example: at login time if a user <literal>lennart</literal> with a home
+ directory of <filename>/home/lennart</filename> specifies <literal>lennart%versuch1</literal> as account
+ name during login, then <command>pam_systemd_home</command> will execute a login into
+ <literal>lennart</literal> but ensure that the <varname>$HOME</varname> variable is set to
+ <filename>/home/lennart/Areas/versuch1</filename> instead of the usual
+ <filename>/home/lennart</filename>.</para>
+
+ <para>This is particularly useful when sharing the same home directory between multiple systems (for
+ example between a host and a VM), with the desire to share the home directory to a large degree, but
+ still have separate session configuration in place.</para>
+
+ <para>Note that the default area to log into can also be encoded in the user record, and it can be
+ specified among
+ <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ configuration parameters. However, an explicit area specified at login time (via the <literal>%</literal>
+ described above) overrides any such default. Also note that simply suffixing an account with
+ <literal>%</literal> at login time (i.e. specifying an empty area name) has the effect of ensuring a
+ login into the primary home directory, overriding any default area configuration via the user record or
+ PAM.</para>
+
+ <para>Note that not all login mechanisms are compatible with the <literal>%</literal> syntax at login
+ time. Most notably <citerefentry
+ project='man-pages'><refentrytitle>ssh</refentrytitle><manvolnum>8</manvolnum></citerefentry> is not.</para>
+
+ <para>Note that the area directory to log into must exist for the area specification to be respected. If
+ an area is specified during login via the <literal>%</literal> logic (or the other mentioned mechanisms)
+ and it does not actually exist the request will be ignored, and the user will log into the primary home
+ directory instead.</para>
+
+ <para>Typically, in order to make use of the mechanism set up an area first, like this:</para>
+
+ <programlisting>lennart@zeta$ mkdir -p ~/Areas
+lennart@zeta$ cp -av /etc/skel ~/Areas/versuch1</programlisting>
+
+ <para>This should be enough to log into the newly created area, either via a regular terminal (using
+ <literal>lennart%versuch1</literal> when prompted for a user name), or via
+ <citerefentry><refentrytitle>run0</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
+
+ <programlisting>lennart@zeta$ run0 -a versuch1</programlisting>
+ </refsect1>
+
<refsect1>
<title>Module Types Provided</title>
<term><option>--group=</option></term>
<term><option>-g</option></term>
- <listitem><para>Switches to the specified user/group instead of root.</para>
+ <listitem><para>Switches to the specified user/group. If not specified defaults to
+ <literal>root</literal>, unless <option>--area=</option> is used (see below), in which case this
+ defaults to the invoking user.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
default if the target user is <literal>root</literal> or a system user the per-user service manager
is not activated as effect of the <command>run0</command> invocation, otherwise it is.</para>
- <para>This ultimately controls the <varname>$XDG_SESSION_CLASS</varname> variable
+ <para>This ultimately controls the <varname>$XDG_SESSION_CLASS</varname> environment variable
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
respects.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-a <replaceable>AREA</replaceable></option></term>
+ <term><option>--area=<replaceable>AREA</replaceable></option></term>
+
+ <listitem><para>Controls the "area" of the target account to log into. Areas are secondary home
+ directories within the primary home directory of the target user, i.e. logging into area
+ <literal>foobar</literal> of an account translates to <varname>$HOME</varname> being set to
+ <filename>~/Areas/foobar</filename> on login.</para>
+
+ <para>If this option is used, the default user to transition to changes from root to the calling
+ user's (but <option>--user=</option> takes precedence, see above). Or in other words, just specifying
+ an area without a user is a mechanism to create a new session of the calling user, just with a
+ different area.</para>
+
+ <para>This ultimately controls the <varname>$XDG_AREA</varname> environment variable
+ <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ respects.</para>
+
+ <para>For details on the area concept see
+ <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v258"/>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--machine=</option></term>
projects / thirdparty / systemd.git / commitdiff
