mirror of
https://github.com/morgan9e/systemd
synced 2026-04-14 00:14:32 +09:00
docs: document the new area functionality
This commit is contained in:
Lennart Poettering
@@ -632,6 +632,16 @@ default limit.
|
||||
`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.
|
||||
|
||||
|
||||
@@ -416,6 +416,24 @@
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
@@ -192,6 +192,39 @@
|
||||
<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>
|
||||
@@ -348,6 +381,16 @@
|
||||
|
||||
<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
|
||||
|
||||
@@ -99,6 +99,53 @@
|
||||
</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>
|
||||
|
||||
|
||||
31
man/run0.xml
31
man/run0.xml
@@ -138,7 +138,9 @@
|
||||
<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>
|
||||
@@ -231,7 +233,7 @@
|
||||
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>
|
||||
|
||||
@@ -239,6 +241,31 @@
|
||||
</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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user