Bug 1402834

Summary:	Document guidelines for general troubleshooting
Product:	Red Hat Enterprise Linux 7	Reporter:	Aneta Šteflová Petrová <apetrova>
Component:	doc-Linux_Domain_Identity_Management_Guide	Assignee:	Aneta Šteflová Petrová <apetrova>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Namita Soman <nsoman>
Severity:	unspecified	Docs Contact:
Priority:	high
Version:	7.3	CC:	rhel-docs
Target Milestone:	rc	Keywords:	Documentation
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2017-08-22 06:12:34 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Bug Depends On:
Bug Blocks:	1425467

Description Aneta Šteflová Petrová 2016-12-08 12:42:30 UTC

The guide currently includes a troubleshooting appendix listing common problems + their solutions: https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/trouble.html

To complement this, we need guidelines for *general* troubleshooting: for example, advice on how to investigate the problem, how to find out where in the architecture it occurs, etc.
These guidelines might also include more architecture-related information so that users can better understand the framework, which could put them into a position where they can fix issues on their own.

The current proposal is to create a decision tree based on the situation in which the problem occurred (for example, server/replica/client installation, migration, command doesn't work, etc.) + steps to further investigate the problem (which logs to check, possibly links to solutions if they are obvious at this stage, what to do when the logs don't show anything, etc.).

Comment 5 Aneta Šteflová Petrová 2017-01-24 12:48:24 UTC

As part of this BZ, I will also review the current files and logs reference material (current chapter Identity Management Files and Logs). Some of this material will need to be removed to prevent duplication with the new troubleshooting content.

Comment 7 Aneta Šteflová Petrová 2017-05-09 07:18:50 UTC

I have all the feedback I need for now. Now it's up to me to implement it.

Comment 8 Aneta Šteflová Petrová 2017-05-12 06:21:04 UTC

All available feedback implemented. New updates are waiting for another SME review.

Comment 11 Aneta Šteflová Petrová 2017-07-17 12:09:47 UTC

Alexander's blog post about the changes that affect some of the troubleshooting procedures: https://vda.li/en/docs/freeipa-debug-privsep/  I changed the procedures based on the article, and I'm currently waiting for more details as noted in c#10.

Comment 12 Aneta Šteflová Petrová 2017-08-22 06:12:34 UTC

I hit a bit of a dead end with this BZ. The product behavior unexpectedly changed while I was working on it, which affected a few of the planned procedures; for a few others, I failed to get the required information.

I wrote seven troubleshooting procedures that have been reviewed and acked: https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/trouble-general.html This should be sufficient to consider this BZ done.

We can always add more if there is new information.