Added new section "Logging in without home directory to fix DOCTEAM 1977 / BZ#1240603

articles/cockpit.asm.xml

@@ -15,8 +15,8 @@ xmlns="http://docbook.org/ns/docbook">
 <!-- R E S O U R C E S -->
 <resources>
 <!-- concepts -->
-<resource href="../concepts/cockpit-about-cockpit.xml" xml:id="_cocpit-about-cockpit"/> 
-<resource href="../concepts/cockpit-authetication.xml" xml:id="_cocpit-authentication-concept"/> 
+<resource href="../concepts/cockpit-about-cockpit.xml" xml:id="_cockpit-about-cockpit"/> 
+<resource href="../concepts/cockpit-authetication.xml" xml:id="_cockpit-authentication-concept"/> 
 <resource href="../concepts/cockpit-authentication-basics.xml" xml:id="_cockpit-authentication-basics"/> 
 <resource href="../concepts/cockpit-network-bonds.xml" xml:id="_cockpit-network-bonds"/> 
 <resource href="../concepts/cockpit-selinux.xml" xml:id="_cockpit-selinux"/> 
@@ -35,6 +35,7 @@ xmlns="http://docbook.org/ns/docbook">
 <!-- tasks -->
 <resource href="../tasks/cockpit-primary-servers.xml" xml:id="_cockpit-primary-servers"/> 
 <resource href="../tasks/cockpit-secondary-servers.xml" xml:id="_cockpit-secondary-servers"/> 
+<resource href="../tasks/cockpit-loginwithouthome.xml" xml:id="_cockpit-loginwithouthome"/> 
 <resource href="../tasks/cockpit-adding-2fa.xml" xml:id="_cockpit-adding-2fa"/> 
 <resource href="../tasks/cockpit-allow-rootlogin.xml" xml:id="_cockpit-allow-rootlogin"/> 
 <resource href="../tasks/cockpit-creating-raids.xml" xml:id="_cockpit-creating-raids"/> 
@@ -91,6 +92,13 @@ xmlns="http://docbook.org/ns/docbook">
 <title>Administering &productname; Using &cockpit;</title>
 <!-- History -->
 <revhistory xml:id="rh-sles-cockpit">
+  <revision><date>2026-05-29</date>
+<revdescription>
+<para>
+Added a new section on logging in without a home directory
+</para>
+</revdescription>
+</revision>
   <revision><date>2026-04-28</date>
 <revdescription>
 <para>
@@ -196,7 +204,7 @@ To fully administer the system using &cockpit;, you must have
 </variablelist>
 </abstract>
 </merge>
-<module renderas="section" resourceref="_cocpit-about-cockpit">
+<module renderas="section" resourceref="_cockpit-about-cockpit">
 <merge>
 <abstract>
 <para/>
@@ -210,7 +218,7 @@ To fully administer the system using &cockpit;, you must have
 </abstract>
 </merge>
 </module>
-<module renderas="section" resourceref="_cocpit-authentication-concept">
+<module renderas="section" resourceref="_cockpit-authentication-concept">
 <merge>
 <abstract>
 <para/>
@@ -245,6 +253,13 @@ To fully administer the system using &cockpit;, you must have
 </abstract>
 </merge>
 </module>
+<module renderas="section" resourceref="_cockpit-loginwithouthome">
+<merge>
+<abstract>
+<para/>
+</abstract>
+</merge>
+</module>
 <module renderas="section" resourceref="_cockpit-switching-access">
 <merge>
 <abstract>

tasks/cockpit-loginwithouthome.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="cockpit-logging-in-without-home-directory"
+ role="task" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Logging in without a home directory</title>
+    <meta name="maintainer" content="shalaka.harne@suse.com" its:translate="no"/>
+    <abstract>
+      <para>
+        By default, logging into Cockpit as a regular user requires an existing <literal>$HOME</literal> directory. This requirement exists because the system defaults to supporting standard Multi-Factor Authentication (MFA) mechanisms via PAM.
+      </para>
+    </abstract>
+  </info>
+  <para>If a user does not have a <literal>$HOME</literal> directory&mdash;which frequently occurs during the initial login of network users managed via SSSD&mdash;the login attempt fails. To allow users without home directories to log into Cockpit, override the default PAM configuration to disable the look-up for the second-factor authentication file:</para>
+  <procedure xml:id="logging-in-without-home-directory">
+    <title>Logging in without a home directory</title>
+    <important>
+      <para>
+        By following this procedure, you will not be able to use a second-factor authentication token via <literal>pam_oath</literal>.
+      </para>
+    </important>
+    <step>
+      <para>
+        Copy the system default Cockpit PAM configuration to the administrator override directory:</para>
+<screen>&prompt.sudo; cp /usr/lib/pam.d/cockpit /etc/pam.d/cockpit</screen>
+    </step>
+    <step>
+      <para>
+        Open <filename>/etc/pam.d/cockpit</filename> in an editor and locate the line referencing <literal>pam_oath.so</literal> at the end of the file.
+      </para>
+    </step>
+    <step><para>Comment out or remove the line entirely:</para>
+
+      <screen>&prompt.root; auth [user_unknown=ignore success=ok] pam_oath.so usersfile=${HOME}/.pam_oath_usersfile no_usersfile_okay window=20 digits=6</screen></step>
+    <step><para>Save and close the file.</para>
+
+    </step>
+  </procedure>
+</topic>