From 59995f35b7dd6ec552be1081b0120f2344e3ded3 Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jhrozek@redhat.com>
Date: Tue, 25 Feb 2014 17:09:00 +0100
Subject: [PATCH 99/99] MAN: Clarify that changing ID mapping options might
 require purging the cache

https://fedorahosted.org/sssd/ticket/2252

Currently SSSD chokes when IDs of users change, we don't support ID
changes yet. Because some users were confused about the failures, this
patch adds additional clarification.

Reviewed-by: Sumit Bose <sbose@redhat.com>
Reviewed-by: Stephen Gallagher <sgallagh@redhat.com>
(cherry picked from commit 3dfa09a826e5f63b4948462c2452937fc329834d)
---
 src/man/include/ldap_id_mapping.xml | 42 +++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/man/include/ldap_id_mapping.xml b/src/man/include/ldap_id_mapping.xml
index 71ff248f1f24242b911f615fd6afeb0382dfa5a1..7f5dbd30be67745b26dbced341762705d6e09f14 100644
--- a/src/man/include/ldap_id_mapping.xml
+++ b/src/man/include/ldap_id_mapping.xml
@@ -12,6 +12,48 @@
         need to use manually-assigned values, ALL values must be
         manually-assigned.
     </para>
+    <para>
+        Please note that changing the ID mapping related configuration
+        options will cause user and group IDs to change. At the moment,
+        SSSD does not support changing IDs, so the SSSD database must
+        be removed. Because cached passwords are also stored in the
+        database, removing the database should only be performed while
+        the authentication servers are reachable, otherwise users might
+        get locked out. In order to cache the password, an authentication
+        must be performed. It is not sufficient to use
+        <citerefentry>
+            <refentrytitle>sss_cache</refentrytitle>
+            <manvolnum>8</manvolnum>
+        </citerefentry>
+        to remove the database, rather the process
+        consists of:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Making sure the remote servers are reachable
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Stopping the SSSD service
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Removing the database
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Starting the SSSD service
+                    </para>
+                </listitem>
+            </itemizedlist>
+        Moreover, as the change of IDs might necessitate the adjustment
+        of other system properties such as file and directory ownership,
+        it's advisable to plan ahead and test the ID mapping configuration
+        thoroughly.
+    </para>
 
     <refsect2 id='idmap_algorithm'>
         <title>Mapping Algorithm</title>
-- 
1.8.5.3