From 9e6df034128936895df2d6348eefce61317ebcc2 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Wed, 13 Jul 2022 10:19:19 +0200
Subject: man: lift pam_systemd_homed description to Summary

Also change the title to describe the module more comprehensively.
Follow-up for 90bc309aa2c1430941f4c50f73e681ab3e488bd3. Suggested
in https://bugzilla.redhat.com/show_bug.cgi?id=2085485#c5.
---
 man/pam_systemd_home.xml | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

(limited to 'man/pam_systemd_home.xml')

diff --git a/man/pam_systemd_home.xml b/man/pam_systemd_home.xml
index 93153b57aa..9fa0e0a7e7 100644
--- a/man/pam_systemd_home.xml
+++ b/man/pam_systemd_home.xml
@@ -17,8 +17,8 @@
 
   <refnamediv>
     <refname>pam_systemd_home</refname>
-    <refpurpose>Automatically mount home directories managed by <filename>systemd-homed.service</filename> on
-    login, and unmount them on logout</refpurpose>
+    <refpurpose>Authenticate users and mount home directories via <filename>systemd-homed.service</filename>
+    </refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -31,7 +31,11 @@
     <para><command>pam_systemd_home</command> ensures that home directories managed by
     <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last
-    session of the user ends.</para>
+    session of the user ends. For such users, it also provides authentication (when per-user disk encryption
+    is used, the disk encryption key is derived from the authentication credential supplied at login time),
+    account management (the <ulink url="https://systemd.io/USER_RECORD/">JSON user record</ulink> embedded in
+    the home store contains account details), and implements the updating of the encryption password (which
+    is also used for user authentication).</para>
   </refsect1>
 
   <refsect1>
@@ -93,13 +97,13 @@
   <refsect1>
     <title>Module Types Provided</title>
 
-    <para>The module implements all four PAM operations: <option>auth</option> (reason: when per-user
-    disk encryption is used, the disk encryption key is derived from the authentication credential supplied
-    at login time), <option>account</option> (reason: <filename>systemd-homed.service</filename> account
-    validity may be configured in more detail than in the traditional Linux user database, and thus needs to
-    be verified separately), <option>session</option> (user sessions must be tracked, in order to implement
-    automatic release when the last session of a managed user is gone), <option>password</option> (user
-    passwords may be changed through PAM).</para>
+    <para>The module implements all four PAM operations: <option>auth</option> (reason: to allow
+    authentication using the encrypted data), <option>account</option> (reason: users with
+    <filename>systemd-homed.service</filename> user accounts are described in a <ulink
+    url="https://systemd.io/USER_RECORD/">JSON user record</ulink> and may be configured in more detail than
+    in the traditional Linux user database), <option>session</option> (user sessions must be tracked in order
+    to implement automatic release when the last session of the user is gone), <option>password</option> (to
+    change the encryption password — also used for user authentication — through PAM).</para>
   </refsect1>
 
   <refsect1>
-- 
cgit v1.2.3