Chapter 1. Installing and running the IdM Healthcheck tool
Learn more about the IdM Healthcheck tool and how to install and run it.
1.1. Healthcheck in IdM
The Healthcheck
command line tool in Identity Management (IdM) helps find issues that can impact the performance of your IdM environment. Using Healthcheck, you can identify an issue in advance so that you can correct it before it becomes critical.
You can use Healthcheck without obtaining a Kerberos ticket.
Modules are independent
Healthcheck consists of independent modules which check for:
- Replication issues
- Certificate validity
- Certificate authority infrastructure issues
- IdM and Active Directory trust issues
- Correct file permissions and ownership settings
Output formats and destination
You can set the following types of output for Healthcheck to generate by using the output-type
option:
-
json
: Machine-readable output in JSON format (default) -
human
: Human-readable output
You can specify a file to store the output by using the --output-file
option.
Results
Each Healthcheck module returns one of the following results:
- SUCCESS
- The system is configured as expected.
- WARNING
- It is advisable to monitor or evaluate the configuration.
- ERROR
- The system is not configured as expected.
- CRITICAL
- The configuration is not as expected, with a significant potential to impact the functioning of your IdM deployment.
Additional resources
-
man ipa-healthcheck
1.2. Installing IdM Healthcheck
Learn how you can install the IdM Healthcheck tool.
Prerequisites
-
You are logged in as
root
.
Procedure
Install the
ipa-healthcheck
package:Copy to Clipboard Copied! Toggle word wrap Toggle overflow dnf install ipa-healthcheck
[root@server ~]# dnf install ipa-healthcheck
Verification
Perform a basic Healthcheck test:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow ipa-healthcheck
[root@server ~]# ipa-healthcheck []
The empty square brackets
[]
indicate a fully-functioning IdM installation.
Additional resources
-
Run
ipa-healthcheck --help
to see all supported arguments.
1.3. Running IdM Healthcheck
You can execute Healthcheck tests in one of the following ways:
- Manually
- Automatically by using log rotation.
This section describes how to execute the tests manually.
Prerequisites
- The Healthcheck tool is installed. See Installing IdM Healthcheck.
Procedure
[Optional] To display a list of all available Healthcheck tests, enter:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow ipa-healthcheck --list-sources
[root@server ~]# ipa-healthcheck --list-sources
To run the Healthcheck utility, enter:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow ipa-healthcheck
[root@server ~]# ipa-healthcheck
Additional resources
-
man ipa-healthcheck
1.4. Log rotation
Log rotation creates a new log file every day and the files are organized by date. The date is included in the filename.
Using log rotation, you can configure the maximum number of log files to be stored. If this number is exceeded, the newest file replaces the oldest one. For example, if the maximum rotation number is thirty, the thirty-first log file replaces the first, that is the oldest one.
Log rotation reduces voluminous log files and organizes them. This helps you analyze the logs.
1.5. Running IdM Healthcheck on a schedule
Follow this procedure to configure IdM Healthcheck to run on a schedule. This includes configuring the following utilities:
-
The
systemd
timer to run the Healthcheck tool periodically and generate the logs. -
The
crond
service to ensure log rotation.
The default log name is healthcheck.log
and the rotated logs use the healthcheck.log-YYYYMMDD
format.
The Healthcheck timer tool is not a real-time tool. It is only meant to be run a few times an hour. If you require real-time monitoring of, for example, services or disk space, use a different tool.
Prerequisites
-
You have
root
privileges.
Procedure
Enable a
systemd
timer:Copy to Clipboard Copied! Toggle word wrap Toggle overflow systemctl enable ipa-healthcheck.timer
# systemctl enable ipa-healthcheck.timer Created symlink /etc/systemd/system/multi-user.target.wants/ipa-healthcheck.timer -> /usr/lib/systemd/system/ipa-healthcheck.timer.
Start the
systemd
timer:Copy to Clipboard Copied! Toggle word wrap Toggle overflow systemctl start ipa-healthcheck.timer
# systemctl start ipa-healthcheck.timer
Open the
/etc/logrotate.d/ipahealthcheck
file to configure the number of logs you want to be saved:Copy to Clipboard Copied! Toggle word wrap Toggle overflow [...] rotate 30 }
[...] rotate 30 }
By default, logs are stored for 30 days before they are overwritten by newer logs.
In the same file, configure the path to the file storing the logs.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow /var/log/ipa/healthcheck/healthcheck.log { [...]
/var/log/ipa/healthcheck/healthcheck.log { [...]
By default, logs are saved in the
/var/log/ipa/healthcheck/
directory.- Save the file.
Ensure that the
crond
service is enabled and running:Copy to Clipboard Copied! Toggle word wrap Toggle overflow systemctl enable crond systemctl start crond
# systemctl enable crond # systemctl start crond
To start generating logs, start the IdM healthcheck service:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow systemctl start ipa-healthcheck
# systemctl start ipa-healthcheck
Verification
-
Navigate to the
/var/log/ipa/healthcheck/
directory. - Display the contents of the log file to check if it was created correctly.
1.6. IdM Healthcheck configuration modifications
You can change Identity Management (IdM) Healthcheck settings by adding the desired command line options to the /etc/ipahealthcheck/ipahealthcheck.conf
file. This can be useful when, for example, you configured log rotation previously and now want to ensure the logs are in a format suitable for automatic analysis, but do not want to set up a new timer.
This Healthcheck feature is only available on RHEL 9.1 and newer.
After the modification, all logs that Healthcheck creates follow the new settings. These settings also apply to any manual execution of Healthcheck.
When running Healthcheck manually, the settings in the configuration file take precedence over the options specified in the command line. For example, if output_type
is set to human
in the configuration file, specifying json
on the command line has no effect. Any command line options you use that are not specified in the configuration file are applied normally.
1.7. Configuring Healthcheck to change the output logs format
Follow this procedure to configure Healthcheck with a timer already configured. In this example, you re-configure Healthcheck to start producing logs in a human-readable format and to also include successful results instead of only errors.
Prerequisites
- Your system is running RHEL 9.1 or later.
-
You have
root
privileges. - You have previously configured log rotation on a timer.
Procedure
-
Open the
/etc/ipahealthcheck/ipahealthcheck.conf
file in a text editor. -
Add options
output_type=human
andall=True
to the[default]
section. - Save and close the file.
Verification
Run Healthcheck manually:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow ipa-healthcheck
# ipa-healthcheck
-
Go to
/var/log/ipa/healthcheck/
and check that the logs are in the correct format.
1.8. Additional resources
See the following sections of the Using IdM Healthcheck to monitor your IdM environment guide for examples of using IdM Healthcheck.