diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md index ae1173c560..24075dc1b1 100644 --- a/docs/USER_RECORD.md +++ b/docs/USER_RECORD.md @@ -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. diff --git a/man/homectl.xml b/man/homectl.xml index 51e38ee84e..abcdd88529 100644 --- a/man/homectl.xml +++ b/man/homectl.xml @@ -416,6 +416,24 @@ + + + + + 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 $HOME environment + variable is set to ~/Areas/ suffixed by the area name. + + For details on the area concept see + pam_systemd_home8. Note + that this option just defines the default, which can be overridden at login time. + + When this option is specified with an empty string as value any previously declared default area + is removed from the user record. + + + diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index 1093df9f82..f240cc755a 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -192,6 +192,39 @@ + + area= + + Takes a filename as parameter. If specified and the user logs into their account the + $HOME environment variable will be set to ~/Areas/ suffixed + by the specified string, but only if that directory exists. Moreover, the + $XDG_AREA variable will be set to the (unprefixed) parameter. + + 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 + pam_systemd_home8 + do), but this parameter may be used to define a default if that's not provided. + + Note that this only adjusts $HOME during login, it does not affect the + otherwise reported home directory of the user. Specifically this means that sshd8 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. + + Note that the default area to log into can also be configured as part of the user account. The + area specified via area= 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. + + For details on the area concept see + pam_systemd_home8. + + + + default-capability-bounding-set= default-capability-ambient-set= @@ -348,6 +381,16 @@ + + + $XDG_AREA + + 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. + + + If not set, pam_systemd will initialize diff --git a/man/pam_systemd_home.xml b/man/pam_systemd_home.xml index 74c4363b73..ed117cfed2 100644 --- a/man/pam_systemd_home.xml +++ b/man/pam_systemd_home.xml @@ -99,6 +99,53 @@ + + Home Area Support + + Home directories managed by + systemd-homed.service8 + 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 lennart with a home + directory of /home/lennart specifies lennart%versuch1 as account + name during login, then pam_systemd_home will execute a login into + lennart but ensure that the $HOME variable is set to + /home/lennart/Areas/versuch1 instead of the usual + /home/lennart. + + 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. + + Note that the default area to log into can also be encoded in the user record, and it can be + specified among + pam_systemd8 + configuration parameters. However, an explicit area specified at login time (via the % + described above) overrides any such default. Also note that simply suffixing an account with + % 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. + + Note that not all login mechanisms are compatible with the % syntax at login + time. Most notably ssh8 is not. + + 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 % 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. + + Typically, in order to make use of the mechanism set up an area first, like this: + + lennart@zeta$ mkdir -p ~/Areas +lennart@zeta$ cp -av /etc/skel ~/Areas/versuch1 + + This should be enough to log into the newly created area, either via a regular terminal (using + lennart%versuch1 when prompted for a user name), or via + run01: + + lennart@zeta$ run0 -a versuch1 + + Module Types Provided diff --git a/man/run0.xml b/man/run0.xml index 59aa6d05d9..f431358e0a 100644 --- a/man/run0.xml +++ b/man/run0.xml @@ -138,7 +138,9 @@ - Switches to the specified user/group instead of root. + Switches to the specified user/group. If not specified defaults to + root, unless is used (see below), in which case this + defaults to the invoking user. @@ -231,7 +233,7 @@ default if the target user is root or a system user the per-user service manager is not activated as effect of the run0 invocation, otherwise it is. - This ultimately controls the $XDG_SESSION_CLASS variable + This ultimately controls the $XDG_SESSION_CLASS environment variable pam_systemd8 respects. @@ -239,6 +241,31 @@ + + + + + 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 + foobar of an account translates to $HOME being set to + ~/Areas/foobar on login. + + If this option is used, the default user to transition to changes from root to the calling + user's (but 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. + + This ultimately controls the $XDG_AREA environment variable + pam_systemd8 + respects. + + For details on the area concept see + pam_systemd_home8. + + + + +