Server Roles

Overview

Server roles represent critical services provided by IPA masters in a multi-master deployment. Each role corresponds to a specific service capability—DNS server, Certificate Authority (CA), Key Recovery Authority (KRA), Active Directory trust controller—that can be enabled or disabled on individual servers. Understanding role distribution is essential for ensuring high availability, planning capacity, and maintaining operational redundancy.

Role Status Values

Each server role can have one of three statuses:

enabled: The role is configured and actively running on the server. Services associated with this role are operational and the server can handle requests for this capability.

configured: The role is configured on the server but not currently active. This typically occurs during installation, after intentional service shutdown, or when dependencies are missing.

absent: The role is not configured on the server. The server does not have the capability to provide this service and was never configured for this role.

Common Server Roles

IPA master: The fundamental role for all IPA servers. Every server in the topology has this role (though it’s implicit and only shown with --include-master).

DNS server: Provides integrated DNS services including forward zones, reverse zones, and DNS-based service discovery (SRV records). Critical for client auto-configuration and service location.

CA (Certificate Authority): Issues and manages X.509 certificates for users, hosts, and services. Renewal server capability for automatic certificate renewal. Essential for SSL/TLS, smart card authentication, and PKINIT.

KRA (Key Recovery Authority): Provides key escrow and recovery services for encrypted data. Enables vault functionality and backup encryption key recovery.

AD trust controller: Manages Active Directory trust relationships, enabling cross-realm authentication between IPA and AD domains. Includes SSSD integration and ID mapping.

DNSSec key master: Manages DNSSEC zone signing keys for secure DNS. Only one server per deployment should have this role to avoid key conflicts.

Role Distribution Planning

High availability requires multiple servers providing critical roles:

CA redundancy: Deploy at least two CA servers to ensure certificate operations continue if one server fails. Three CA servers recommended for production.

DNS redundancy: Deploy DNS servers in each datacenter or geographic location to ensure local DNS resolution and reduce WAN dependencies.

Trust controller redundancy: If using AD trusts, deploy multiple trust controllers for failover and load distribution.

KRA deployment: KRA is optional but should be deployed on multiple servers if vault functionality is required.

Server role commands help verify this redundancy and identify single points of failure before they cause outages.

EXAMPLES

Show status of ‘DNS server’ role on a server:

ipa server-role-show ipa.example.com "DNS server"

Show status of all roles containing ‘AD’ on a server:

ipa server-role-find --server ipa.example.com --role="AD trust controller"

Show status of all configured roles on a server:

ipa server-role-find ipa.example.com

Show implicit IPA master role:

ipa server-role-find --include-master

Use Cases

Verifying CA Redundancy for Certificate Operations

Before decommissioning a CA server, verify that other CA servers exist to maintain certificate issuance capability.

# Check how many CA servers are enabled
ipa server-role-find --role="CA server" --status=enabled
  Server name: ipa01.example.com
  Role name: CA server
  Role status: enabled

  Server name: ipa02.example.com
  Role name: CA server
  Role status: enabled

  Server name: ipa03.example.com
  Role name: CA server
  Role status: enabled

# Three CA servers present - safe to remove one without losing CA capability
# If only one CA server, must install CA on another server first

Planning DNS Server Deployment

When adding a new datacenter, determine which existing servers have DNS roles to inform where DNS should be deployed for redundancy.

# List all DNS servers in infrastructure
ipa server-role-find --role="DNS server" --status=enabled
  Server name: ipa-us-east.example.com
  Role name: DNS server
  Role status: enabled

  Server name: ipa-us-west.example.com
  Role name: DNS server
  Role status: enabled

# Only US datacenters have DNS
# New EMEA datacenter needs DNS server for local resolution
# Install DNS on new ipa-emea.example.com server
ssh ipa-emea.example.com
ipa-dns-install

Troubleshooting AD Trust Authentication Failures

When AD trust authentication fails, verify that trust controller services are running on available servers.

# Check AD trust controller status
ipa server-role-find --role="AD trust controller"
  Server name: ipa01.example.com
  Role name: AD trust controller
  Role status: configured

# Status is "configured" not "enabled" - trust services not running
# Check trust controller services on ipa01
ssh ipa01.example.com
ipactl status
  ipa: INFO: The ipactl command was successful
# Services appear running but role shows "configured"

# Restart IPA services to transition role to "enabled"
ipactl restart

# Verify role now enabled
ipa server-role-show ipa01.example.com "AD trust controller"
  Role status: enabled

Auditing Infrastructure Capabilities

Generate infrastructure capability report showing which services are available and where they run.

# Show all roles across all servers
ipa server-role-find --all

# Generate capability matrix
echo "# IPA Infrastructure Capability Matrix"
for server in $(ipa server-find --pkey-only | grep "Server name" | awk '{print $3}'); do
  echo ""
  echo "## $server"
  ipa server-role-find --server="$server" | grep -E "(Role name|Role status)"
done > infrastructure-capabilities.md

# Result shows which servers provide which services
# Identifies single points of failure and redundancy gaps

Verifying KRA Deployment Before Enabling Vaults

Before deploying vault features to users, verify KRA is installed and operational on sufficient servers.

# Check KRA role status
ipa server-role-find --role="KRA server"
  Server name: ipa01.example.com
  Role name: KRA server
  Role status: enabled

  Server name: ipa02.example.com
  Role name: KRA server
  Role status: enabled

# Two KRA servers present - sufficient for vault deployment
# Users can now create and manage vaults
ipa vault-add user-vault --type=symmetric

Identifying Servers for Decommissioning

Before removing a server, verify it doesn’t provide critical roles that lack redundancy.

# Check what roles ipa03 provides
ipa server-role-find --server=ipa03.example.com --status=enabled
  Server name: ipa03.example.com
  Role name: CA server
  Role status: enabled

  Server name: ipa03.example.com
  Role name: DNS server
  Role status: enabled

  Server name: ipa03.example.com
  Role name: DNSSec key master
  Role status: enabled

# ipa03 is DNSSec key master - unique role
# Must migrate DNSSec key master before decommissioning
ssh ipa01.example.com
ipa-dns-install --dnssec-master

# Now safe to decommission ipa03
ipa server-del ipa03.example.com

Validating Multi-Datacenter Deployment

Ensure each datacenter has critical roles for local service availability and reduced WAN dependencies.

# Check role distribution by datacenter
for dc in us-east us-west emea apac; do
  echo "=== Datacenter: $dc ==="
  for server in $(ipa server-find --pkey-only | grep "ipa-$dc" | awk '{print $3}'); do
    echo "Server: $server"
    ipa server-role-find --server="$server" --status=enabled | grep "Role name" | awk '{print "  - " $3 " " $4}'
  done
done

# Verify each datacenter has:
# - DNS server (local DNS resolution)
# - CA server (local certificate operations)
# If missing, deploy additional role servers in that datacenter

Investigating Certificate Renewal Failures

When automatic certificate renewal fails, verify CA servers are operational and identify renewal servers.

# Check CA server status
ipa server-role-find --role="CA server" --status=enabled
  Server name: ipa01.example.com
  Role name: CA server
  Role status: enabled

# Only one CA server enabled - if it's down, renewals fail
# Check if other servers have CA configured but not enabled
ipa server-role-find --role="CA server" --status=configured
  Server name: ipa02.example.com
  Role name: CA server
  Role status: configured

# ipa02 has CA configured - investigate why not enabled
ssh ipa02.example.com
ipactl status | grep CA
  pki-tomcatd@pki-tomcat: STOPPED

# CA service stopped on ipa02 - start it
systemctl start pki-tomcatd@pki-tomcat

# Verify CA role now enabled
ipa server-role-show ipa02.example.com "CA server"
  Role status: enabled

Planning Server Upgrades

Before upgrading IPA servers, understand role distribution to plan upgrade order that maintains service availability.

# Generate role distribution report
ipa server-role-find > /tmp/roles-before-upgrade.txt

# Upgrade strategy:
# 1. Upgrade non-critical servers first (no unique roles)
# 2. Upgrade redundant role servers (multiple CA/DNS servers)
# 3. Upgrade unique role servers last (DNSSec key master)

# Check for unique roles
for role in "CA server" "DNS server" "KRA server" "AD trust controller"; do
  count=$(ipa server-role-find --role="$role" --status=enabled | grep -c "Server name")
  echo "$role: $count servers"
  if [ $count -eq 1 ]; then
    echo "  WARNING: Only 1 server for $role - high priority for redundancy"
  fi
done

Verifying Role Status After Server Restart

After server maintenance or restart, verify that all previously enabled roles are operational again.

# Before maintenance, record role status
ipa server-role-find --server=ipa01.example.com --status=enabled > /tmp/ipa01-roles-before.txt

# Perform maintenance (server restart, package updates, etc.)
ssh ipa01.example.com
systemctl reboot

# After server returns, verify roles restored
ipa server-role-find --server=ipa01.example.com --status=enabled > /tmp/ipa01-roles-after.txt

# Compare before and after
diff /tmp/ipa01-roles-before.txt /tmp/ipa01-roles-after.txt
  # If differences exist, some roles didn't restart properly
  # Investigate and restart affected services

Security Considerations

Role concentration creates single points of failure: If only one server provides a critical role (CA, DNS, DNSSec key master), that server’s compromise or failure causes service-wide outages. Distribute critical roles across multiple servers to reduce impact of server compromise.

DNSSec key master is high-value target: The DNSSec key master holds zone signing keys for all DNS zones. Compromise of this server enables DNS spoofing across the entire domain. This role should run on highly secured servers with strict access controls.

CA server compromise enables certificate issuance: Servers with CA role can issue certificates for any principal in the realm. Compromised CA servers enable attackers to issue certificates for impersonation, man-in-the-middle attacks, or persistent access. CA servers warrant extra security hardening.

Trust controller access enables AD impersonation: AD trust controller servers hold trust credentials and can authenticate as trusted domain users. Compromise enables attackers to impersonate AD users in the IPA environment. Strict access control and monitoring for trust controllers is critical.

KRA server stores encryption keys: KRA servers hold key escrow data enabling recovery of encrypted information. KRA compromise exposes all escrowed keys and enables decryption of protected data. KRA servers require strong physical and logical security.

Role information aids attack planning: Server role information reveals infrastructure capabilities and potential targets. Attackers knowing which servers run CA can focus attacks on those servers. Limit role information disclosure to authenticated, authorized administrators.

Absent roles indicate incomplete deployments: Servers without expected roles may indicate incomplete installation, configuration drift, or previous security incidents. Regular role audits help detect unauthorized changes or security policy violations.

Role status changes indicate service disruption or compromise: Roles transitioning from “enabled” to “configured” or “absent” may indicate service failures, security incidents, or unauthorized changes. Monitor role status changes and alert on unexpected transitions.

Multiple CA servers complicate revocation: With multiple CA servers, certificate revocation must propagate to all CA replicas. Replication delays create windows where revoked certificates remain trusted by some servers, enabling continued access for compromised certificates.

DNS role enables DNS-based attacks: Servers with DNS role control DNS responses for the IPA domain. Compromised DNS servers enable DNS spoofing, service discovery manipulation, or denial of service by returning incorrect DNS data.

Troubleshooting

server-role-find Returns No Results

Symptom: ipa server-role-find returns “0 results” or no role information.

Diagnosis: No servers have configured roles, connectivity issue, or insufficient permissions.

Resolution: Verify servers exist and check permissions:

# Verify IPA servers exist
ipa server-find
  # Should list servers

# If servers exist but no roles shown, check specific server
ipa server-show ipa01.example.com
  # Shows server details

# Verify user has permission to view server roles
ipa user-show $(whoami) | grep -i role
  # Check role membership

# Try as admin user
kinit admin
ipa server-role-find

Role Shows “configured” Instead of “enabled”

Symptom: Server role status is “configured” but should be “enabled” (service is running).

Diagnosis: Service recently restarted, service unhealthy, or IPA state not refreshed.

Resolution: Restart IPA services and verify:

# Check service status on the server
ssh ipa01.example.com
ipactl status
  # Look for stopped services

# Restart IPA services
ipactl restart

# Wait for services to fully start (30-60 seconds)
sleep 60

# Check role status again
ipa server-role-show ipa01.example.com "CA server"
  Role status: enabled
  # Should transition to enabled if services healthy

Cannot Find Specific Role by Name

Symptom: ipa server-role-show or server-role-find --role fails with “role not found”.

Diagnosis: Role name incorrect or misspelled.

Resolution: List all available roles and use exact name:

# List all role types
ipa server-role-find --all | grep "Role name" | sort -u
  Role name: AD trust controller
  Role name: CA server
  Role name: DNS server
  Role name: DNSSec key master
  Role name: IPA master
  Role name: KRA server

# Use exact role name (case-sensitive)
ipa server-role-find --role="CA server"
  # Succeeds with exact name

# Wrong: case mismatch
ipa server-role-find --role="ca server"
  # Fails - wrong case

Role Status Inconsistent Across Servers

Symptom: Different servers report different status for the same role type.

Diagnosis: This is expected - role status is per-server. Each server can have different roles enabled.

Resolution: This is normal behavior, not an error:

# ipa01 has CA enabled
ipa server-role-show ipa01.example.com "CA server"
  Role status: enabled

# ipa02 doesn't have CA
ipa server-role-show ipa02.example.com "CA server"
  Role status: absent

# This is correct - CA role varies by server
# To see overall CA distribution:
ipa server-role-find --role="CA server" --status=enabled

Cannot See “IPA master” Role

Symptom: ipa server-role-find doesn’t show “IPA master” role.

Diagnosis: IPA master role is implicit and hidden by default.

Resolution: Use --include-master flag:

# Without flag - no IPA master shown
ipa server-role-find --server=ipa01.example.com
  # Shows only explicit roles (CA, DNS, etc.)

# With flag - IPA master shown
ipa server-role-find --server=ipa01.example.com --include-master
  Server name: ipa01.example.com
  Role name: IPA master
  Role status: enabled
  # All IPA servers have this role

Role Shows “absent” After Installation

Symptom: Installed a role (e.g., DNS) but status shows “absent”.

Diagnosis: Installation failed, incomplete, or server entry not updated.

Resolution: Verify installation and re-run installer if needed:

# Check if DNS service is actually running
ssh ipa01.example.com
systemctl status named
  # If stopped - installation failed

# Re-run DNS installation
ipa-dns-install
  # Complete installation

# Verify role now present
ipa server-role-show ipa01.example.com "DNS server"
  Role status: enabled

Role Status Doesn’t Update After Service Stop

Symptom: Stopped a service but role still shows “enabled”.

Diagnosis: Role status may not update immediately; status reflects configuration, not real-time service state.

Resolution: Role status indicates configuration, use service checks for real-time state:

# Role status shows configuration state
ipa server-role-show ipa01.example.com "CA server"
  Role status: enabled
  # Means CA is configured to run

# Check actual service status for real-time state
ssh ipa01.example.com
systemctl status pki-tomcatd@pki-tomcat
  Active: inactive (dead)
  # Service actually stopped despite "enabled" role

Multiple Servers Show Same Unique Role

Symptom: Multiple servers show “DNSSec key master” role, which should be unique.

Diagnosis: Configuration error - only one server should be DNSSec key master.

Resolution: Disable DNSSec key master on extra servers:

# Find all DNSSec key master servers
ipa server-role-find --role="DNSSec key master" --status=enabled
  Server name: ipa01.example.com
  Server name: ipa02.example.com
  # Two servers - should be only one

# Disable on secondary server
ssh ipa02.example.com
ipa-dns-install --disable-dnssec-master

# Verify only one remains
ipa server-role-find --role="DNSSec key master" --status=enabled
  Server name: ipa01.example.com
  # Only one DNSSec key master now

server-role-show Fails with Server Not Found

Symptom: ipa server-role-show server-name "role" fails with “server not found”.

Diagnosis: Server name incorrect or server deleted from topology.

Resolution: Verify server exists and use correct hostname:

# List all servers to get exact names
ipa server-find --pkey-only
  Server name: ipa01.example.com
  Server name: ipa02.example.com

# Use exact server name
ipa server-role-show ipa01.example.com "CA server"

# If server truly doesn't exist, cannot query its roles
# Server must be in topology to query roles

Filter by —status Returns Unexpected Results

Symptom: Filtering by role status returns servers that should be excluded.

Diagnosis: Status filter may be applied incorrectly or cached results.

Resolution: Clear cache and use correct status values:

# Valid status values: enabled, configured, absent
ipa server-role-find --role="CA server" --status=enabled
  # Shows only enabled CA servers

# Invalid status value
ipa server-role-find --role="CA server" --status=running
  # Fails - "running" not valid status

# Clear cache if results seem stale
rm -rf ~/.cache/ipa/
ipa server-role-find --role="CA server" --status=enabled

Role Information Missing After Upgrade

Symptom: After IPA upgrade, server roles not showing or showing “absent” incorrectly.

Diagnosis: Upgrade may not have refreshed server role information.

Resolution: Restart services and wait for role state refresh:

# Restart IPA services on all servers
for server in $(ipa server-find --pkey-only | awk '/Server name/{print $3}'); do
  ssh "$server" "ipactl restart"
done

# Wait for state to stabilize (5 minutes)
sleep 300

# Check role status again
ipa server-role-find
  # Roles should populate correctly

Cannot Determine Which Server Handles Requests

Symptom: Multiple servers have CA role enabled; need to know which server will handle CA requests.

Diagnosis: Role information shows capability, not request routing.

Resolution: Request routing depends on client configuration and load balancing:

# Show all CA servers (any can handle requests)
ipa server-role-find --role="CA server" --status=enabled

# Client uses server from /etc/ipa/default.conf or DNS SRV
grep xmlrpc_uri /etc/ipa/default.conf
  xmlrpc_uri = https://ipa01.example.com/ipa/xml

# Client will use ipa01 for CA requests
# With load balancer, requests distributed across all CA servers

Commands

server-role-find

Usage: ipa [global-options] server-role-find [CRITERIA] [options]

Find a server role on a server(s)

Arguments

Argument Required Description

---

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
--server SERVER	IPA server hostname
--role ROLE	IPA server role name
--status STATUS	Status of the role
--timelimit TIMELIMIT	Time limit of search in seconds (0 is unlimited)
--sizelimit SIZELIMIT	Maximum number of entries returned (0 is unlimited)
--include-master	Include IPA master entries
--all	Retrieve and print all attributes from the server. Affects command output.
--raw	Print entries as stored on the server. Only affects output format.

server-role-show

Usage: ipa [global-options] server-role-show SERVER ROLE [options]

Show role status on a server

Arguments

Argument	Required	Description
SERVER	yes	IPA server hostname

ROLE yes IPA server role name

Options

Option	Description
--all	Retrieve and print all attributes from the server. Affects command output.
--raw	Print entries as stored on the server. Only affects output format.