The FreeIPA Master Class - Part 1

Published Jan. 20, 2025, 3:27 p.m. by dwest

Introduction to Directory Servers and FreeIPA

Managing user accounts across a growing infrastructure can quickly become painful. If you have multiple servers, desktops, web applications, file shares and other shared services, you eventually run into the problem of account sprawl. Each system requires its own user database, password management becomes inconsistent and access control quickly turns into a mess. This is where directory servers come in.

A directory server is a centralized system designed to manage identities and authentication across multiple systems. Instead of storing usernames and passwords on every machine, systems query a central directory to determine who a user is and what they are allowed to access.

You can think of it like a digital phone book or employee directory, except instead of just storing names and phone numbers, it stores:

Users
Groups
Computers
Services
Access policies
Security credentials

The goal is to provide centralized identity management and enable single sign-on (SSO) so one account can access many systems.

Directory Servers in Enterprise IT

Directory services are foundational to enterprise infrastructure because they handle:

Authentication - verifying who a user is
Authorization - determining what they are allowed to do
Access control - enforcing policies across systems

The most widely known directory service is Microsoft Active Directory, which dominates Windows environments.

However, many organizations, especially Linux-heavy ones, rely on open source alternatives such as:

OpenLDAP
FreeIPA
389 Directory Server
Legacy solutions like NIS

These systems typically use the LDAP protocol (Lightweight Directory Access Protocol) to store and retrieve identity information.

Even Apple provided their own solution called Open Directory, which bundled several open-source components to manage macOS environments in a way similar to Active Directory.

Enter FreeIPA

In this series, we’re going to focus on FreeIPA, an enterprise-grade identity management system designed primarily for Linux environments.

FreeIPA integrates several powerful technologies into a single platform, providing:

LDAP directory services
Kerberos authentication
DNS integration
Certificate authority services
Host and service management
Web-based administration

Rather than stitching together separate tools yourself, FreeIPA bundles them into a unified identity platform.

This makes it an excellent choice for:

Linux server fleets
Mixed Linux/Unix environments
DevOps infrastructure
Homelabs and research networks
Enterprises looking for an open-source Active Directory alternative

Core Components of FreeIPA

FreeIPA follows a classic open-source philosophy: each component focuses on doing one thing well.

Several mature projects work together to create the full identity management stack.

389 Directory Server

The LDAP directory backend.

This stores identity data such as:

Users
Groups
Hosts
Policies
Services

All authentication and access information ultimately lives here.

MIT Kerberos

Kerberos handles secure authentication and single sign-on.

Instead of sending passwords across the network repeatedly, Kerberos uses tickets that prove a user has already authenticated.

This greatly improves security and enables seamless login between services.

Dogtag Certificate System

Dogtag provides a Certificate Authority (CA).

It manages:

TLS/SSL certificates
Certificate renewal
Revocation lists (CRL)
Trust relationships between hosts and services

FreeIPA automatically issues certificates to hosts when they join the domain.

BIND DNS (Optional)

When DNS integration is enabled, FreeIPA manages DNS records for:

Hosts
Services
Kerberos entries

This allows automatic DNS updates and simplifies service discovery.

Samba (Optional)

Samba enables cross-forest trust with Active Directory.

It allows:

AD trust relationships
SMB/CIFS file sharing
Windows clients to authenticate against FreeIPA

Apache + Python

These power the FreeIPA WebUI, which provides a graphical interface for managing:

Users
Groups
Hosts
Policies
Certificates

Additionally, end-users can also manage their own passwords and account details through the web interface.

SSSD (System Security Services Daemon)

SSSD runs on client machines and communicates with FreeIPA.

It handles:

Authentication
Credential caching
Access policies
Offline logins

SSSD ensures clients can continue functioning even if the FreeIPA server is temporarily unreachable.

Installing FreeIPA

The installation process has changed slightly across different versions of FreeIPA and RHEL-based distributions.

At the time of writing, the typical workflow is:

Install the system as a FreeIPA client
Promote it to a FreeIPA master
Optionally configure replicas and certificate authorities

These instructions assume a CentOS Stream / RHEL-based system, but they work similarly on other distributions.

Installing a FreeIPA Client

This step is identical regardless of whether the machine will become a client or a server.

Install the client

CentOS / RHEL:

dnf install ipa-client

Ubuntu / Debian:

apt install freeipa-client

Join the IPA domain

ipa-client-install
--server=ipa1.example.com
--server=ipa2.example.com
--domain=example.com
--mkhomedir

If a host record already exists:

ipa-client-install --force-join

FreeIPA automatically configures certificates, Kerberos, and authentication policies.

Installing the First FreeIPA Master

The first master is special because it typically becomes:

the initial Certificate Authority
the CRL manager
the primary trust anchor for the domain

Additional replicas can later take over these roles.

First, let’s start with the following steps:

Install the server package

dnf install freeipa-server

Run the installer

ipa-server-install

If you do not want FreeIPA to manage DNS, choose no when prompted for DNS configuration.

If the installation succeeds, you should see:

The ipa-server-install command was successful

Installing a FreeIPA Replica

In older versions of FreeIPA, adding replicas required generating a special replica file on the master and transferring it to the new system.

Modern FreeIPA (Domain Level 1+) simplified this process.

Now the workflow is:

Join the domain as a client
Promote the host to a replica

Enable the IdM module (RHEL / EL8)

RHEL 8 uses modular packages, however later versions switched back to the older method. The following steps are only required for version EL8.

Enable the IdM module:
```
dnf module enable idm:DL1
```
Then install the packages:
```
dnf install ipa-client freeipa-server
```

Join the domain

This is where most failures can occur, so you might have to return to this step on occasion to uninstall and then install it again.

ipa-client-install
--server=ipa1.example.com
--domain=example.com
--mkhomedir

Note: the –mkhomedir flag is not required, but it is useful to keep consistent across hosts.

Promote to replica

This will promote the IPA client to a master replica and optionally install the CA on it.

ipa-replica-install --setup-ca

If you omit --setup-ca, the replica will not run a Certificate Authority.

You can add it later with:

ipa-ca-install

Useful FreeIPA Administration Commands

While FreeIPA normally “just works” once it is setup and configured, there are times when you will need to perform some sort of maintenance on it or troubleshoot odd issues. Below is a list of the most common commands you might use:

Check IPA service status

This will provide an overall health status check of all IPA related services. This is usually the first command you will always run.

ipactl status

Control services

FreeIPA has its own services manager that operates outside of systemd or other init daemons.

ipactl stop
ipactl start
ipactl restart
ipactl restart --ignore-service-failures

Note: When restarting services, if one service fails, then all services will fail. If you add the –ignore-service-failures flag, then it will allow the other functional services to run when one fails. This is common when the tomcat service has issues.

Check replication status

This will provide information about the replication status of the domain and ca services.

ipa-replica-manage list -v $(hostname)
ipa-csreplica-manage list -v $(hostname)

List replication topology

This will list all replication topology segments in the domain. It is useful when determining which IPA masters are replicating with each other.

ipa topologysegment-find

For CA replication:

ipa topologysegment-find --suffix=ca

Show domain level

As of this writing, the current domain level is 1. Older IPA networks might still be running on level 0, which will require upgrading it before you can upgrade to newer FreeIPA packages. Determine your domain level with the following:

ipa domainlevel-get

Change domain level

This should only be performed when upgrading from a lower domain level to the current domain level. It is a one-time command with no rollback.

ipa domainlevel-set 1

⚠ Domain level upgrades apply to all servers and cannot be reversed.

Force replica resynchronization

When a FreeIPA server falls out-of-sync or the replication agreement stops working, you can force it to re-initialize itself from another FreeIPA host.

ipa-replica-manage re-initialize
--from ipa-replica.example.com
--verbose

Renew CA certificate manually

Certificates should automatically renew itself before they expire. However, if a CA was misbehaving, then you might have to force a renewal.

ipa-cacert-manage renew

⚠ Letting a CA certificate expire can be a pain to fix. Ideally, you should fix this before that happens.

View password policy

While this is also available in the web interface, the CLI command can be useful when troubleshooting issues.

ipa pwpolicy-show

Example output:

Max lifetime: 3650
Min lifetime: 1
Min length: 8
Max failures: 6

Modify password policy

If you would like to adjust the password policy from the CLI, you can do so with the following:

ipa pwpolicy-mod --minlife=0 global_policy

Update LDAP schema and configuration

Occasionally, upgrading to newer FreeIPA software will require updating the LDAP schema. While this process should be automatic, there are a number of things that can break it and require that you manually run it.

ipa-server-upgrade

Update local certificate store

This will refresh the certificates on the local IPA master to ensure it has all of the same certs as the other replicas. Sometimes replication errors can cause this to fall out of sync.

ipa-certupdate

Downloading the FreeIPA Certificate Authority

FreeIPA uses its own internal certificate authority. Since browsers do not trust it by default, you may see warnings when accessing the web interface. To fix this, you just need to install the CA certificate on all clients that will be connecting to it.

You can export the CA certificate with:

openssl s_client -connect ipa.example.com:443
-showcerts < /dev/null > ipa_ca.crt

Import this certificate into your:

browser
OS certificate store
keychain

This will help avoid trust warnings.

What’s Next?

This article covered:

Directory server fundamentals
The architecture of FreeIPA
Installation of masters and replicas
Common administrative commands

In the next part of the FreeIPA Master Class, we’ll dive deeper into:

Managing users and groups
Host enrollment
Kerberos authentication flows
Access control policies
Real-world deployment architecture