Troubleshooting#
This document should help FreeIPA users who are trying to troubleshoot why their setup is not working as expected. After following the steps and advises described in this article, users should be able to either fix the configuration themselves or provide the right information for developers/support to investigate and advise or to fix the issue.
Feedback is expected to be sent either to:
or by filing an issue to FreeIPA Codeberg ticketing system or Red Hat Bugzilla.
Before we dive into particular scenarios we offer you a presentation about
FreeIPA troubleshooting principles.
Reporting bugs#
Providing the right information in a report, regardless whether it is filed by mail or in bug tracking system will help FreeIPA developers quickly identify the root cause of an issue and provide help.
The following information is expected to be passed in the report:
Version and distribution: we need to know the version (and distribution) of the FreeIPA you are running on. If other components (like NFS, sudo) are involved, their versions may be useful as well.
Problem description: What happened, in what part/component of FreeIPA it happened, how severe is the issue. The problem description should help us to either reproduce the problem or identify the faulty component.
What have you tried: transcript of what you already did to investigate the issue
Logs: Related (and sanitized) logs are essential source of information. At least the logs mentioned in the different scenarios below or the ones mentioned on the Files to be attached to bug report page should be included.
If you want to read some theory about bug reporting we recommend you the famous article How to Report Bugs Effectively.
Troubleshooting scenarios#
FreeIPA consists of many integrated technologies and components. Therefore, investigation of issues occurring in one part of FreeIPA will take different path and steps from investigation of issues in other part. The same applies for the list of information expected to be provided. Please consult the dedicated troubleshooting page for the relevant aspect or component of FreeIPA:
- Installation
- Server Installation
- pki-selinux policy not loaded properly
- Replica Installation
- Client Installation
- Directory_Server
- Replication issues
- Obsolete RUV records
- Performance tuning
- Advanced Troubleshooting
- Kerberos
- kinit does not work
- Service does not start
- Cannot authenticate on client
- Failed auth increments failed login count by 2
- Cannot authenticate user with OTP with Google Authenticator
- Smart Card authentication
- Trusts
- DNS
- Getting logs
- Reporting bugs
- Kerberos does not work
- named on server does not start
- PTR synchronization does not work
- Forward zone does not work
- DNSSEC signing does not work
- PKI
- IPA won’t start, expired certificates
- PKI-tomcatd fails to start
- Authentication Errors
- CRL gets very old
- External CA renewal with ipa-cacert-manage fails
- Administration_and_Web_UI
- Administration Framework
- Web UI
- Active Directory trust setup
- Description
- Prerequisites
- Assumptions
- Install and configure IPA server
- Cross-forest trust checklist
- Establish and verify cross-forest trust
- Test cross-forest trust
- Debugging trust
- PrivilegeSeparation
- How to debug FreeIPA privilege separation issues
- Integration
- sudo does not work for hostgroups