IPA Servers

Overview

IPA server entries represent individual masters in a multi-master replication topology. Each server entry contains configuration metadata including server roles (CA, DNS, KRA), location assignments, service weights, and replication relationships. Server management commands enable administrators to query server information, modify server configuration, manage server state, and remove decommissioned servers from the topology.

Server Lifecycle

Installation: New servers are added to the topology via ipa-replica-install, which creates the server entry automatically.

Configuration: Server location, service weight, and other attributes can be modified via server-mod after installation.

State Management: Servers can be set to enabled or hidden state to control service discovery and load balancing.

Decommissioning: Servers are removed from topology via server-del, which cleans up replication agreements and removes the server entry.

Hidden Replicas

TECH PREVIEW: Hidden replicas are IPA master servers that are not advertised to clients or other masters for service discovery.

Purpose: Hidden replicas have all services running and available, but none of their services have DNS SRV records or enabled LDAP server roles. This makes them invisible to automatic service discovery mechanisms while remaining fully functional.

Behavior:

IPA clients and SSSD ignore hidden replicas during installation and daily operations
Kerberos clients with dns_lookup_kdc = true do not auto-discover them
Certmonger does not use them for certificate renewal
Masters without CA/KRA never use CA/KRA services on hidden replicas
Services on a hidden replica primarily use local services (local LDAP, Kerberos)

Critical Limitations:

Not isolated: Hidden replicas are concealed but not firewalled or secured. All IPA TCP/UDP ports must remain open for other IPA servers.
Minimum availability: At least one regular (non-hidden) server must be available for each service type (IPA master, DNS, CA, KRA). For DNS locations, each location needs at least one regular replica.
Role restrictions: Hidden replicas cannot be CA renewal masters or DNSSEC key masters.
Explicit configuration overrides discovery: Hard-coded server names (e.g., ipa-client-install --server=hidden.example.com, SSSD config, ca_host in /etc/ipa/default.conf) bypass auto-discovery and can use hidden replicas.
State change propagation delay: Demoting to hidden or promoting to enabled is not instantaneous. Changes require replication and cache refresh time.

Use Cases:

Dedicated backup servers: Shutdown for full backup without affecting clients
High-load operations: Mass imports, extensive queries, or operations that stress IPA API/LDAP
Staging/testing: Operations requiring isolated IPA instance that won’t disrupt production clients

Installation: Create hidden replica with ipa-replica-install --hidden-replica

State management: Use server-state command:

Demote to hidden: ipa server-state <hostname> --state=hidden
Promote to enabled: ipa server-state <hostname> --state=enabled
CA renewal master or DNSSEC key master must be moved to another server before demotion

Implementation details: Status stored in cn=masters,cn=ipa,cn=etc,$SUFFIX as ipaConfigString attribute with values enabledService (visible) or hiddenService (hidden). Auto-discovery mechanisms ignore hiddenService entries.

Server Attributes

Server Name: The fully qualified domain name (FQDN) of the IPA master. This is the primary identifier.

Location: Optional assignment to an IPA location for DNS-based service discovery and client affinity.

Service Weight: Controls load balancing priority for client requests. Lower weight = higher priority.

Minimum/Maximum Domain Level: Indicates supported domain functional levels for upgrade compatibility.

Server Roles: Which services (CA, DNS, KRA, AD Trust) are enabled on the server (managed separately via server-role commands).

Multi-Master Topology

IPA deployments typically include multiple servers for high availability and load distribution. Server commands help understand and manage this distributed architecture:

Query all servers: ipa server-find lists all masters in the topology.

Server details: ipa server-show displays configuration and role information for a specific server.

Location-based filtering: Find servers in specific geographic locations for maintenance planning.

Role-based filtering: Identify which servers provide specific services (CA, DNS).

Understanding the complete server topology is essential for capacity planning, maintenance scheduling, and troubleshooting replication issues.

Get information about installed IPA servers.

EXAMPLES

Find all servers:
ipa server-find
Show specific server:
ipa server-show ipa.example.com

Use Cases

Listing All IPA Masters in Deployment

Administrators need to understand the complete IPA infrastructure for capacity planning and maintenance.

# List all IPA servers
ipa server-find
  Server name: ipa01.example.com
  Minimum domain level: 0
  Maximum domain level: 1

  Server name: ipa02.example.com
  Minimum domain level: 0
  Maximum domain level: 1

  Server name: ipa03.example.com
  Minimum domain level: 0
  Maximum domain level: 1

# Count total servers
ipa server-find --pkey-only | grep -c "Server name"
  3
# Three IPA masters in deployment

Finding Servers by Location

When planning datacenter maintenance, identify which IPA servers are in the affected location.

# Find servers in specific location
ipa server-find --in-locations=datacenter-east
  Server name: ipa-east-01.example.com
  Location: datacenter-east

  Server name: ipa-east-02.example.com
  Location: datacenter-east

# Plan maintenance window for datacenter-east
# Ensure at least one server in other locations remains operational
ipa server-find --not-in-locations=datacenter-east
  Server name: ipa-west-01.example.com
  Location: datacenter-west
  # West datacenter server available during east maintenance

Checking Server Configuration Before Decommissioning

Before removing a server, verify its roles and ensure redundancy exists.

# Show complete server configuration
ipa server-show ipa03.example.com --all
  Server name: ipa03.example.com
  Location: datacenter-east
  Enabled server roles: CA server, DNS server, DNSSec key master
  Min domain level: 0
  Max domain level: 1

# ipa03 is DNSSec key master - unique role
# Must migrate DNSSec key master before deletion

# Check if other servers have CA and DNS for redundancy
ipa server-role-find --role="CA server" --status=enabled
  # Verify multiple CA servers

# Safe to proceed with decommission after role migration

Modifying Server Location for Client Affinity

Reassign server to different location after datacenter migration or infrastructure changes.

# Show current server location
ipa server-show ipa02.example.com
  Server name: ipa02.example.com
  Location: datacenter-east

# Server physically moved to west datacenter
# Update location in IPA
ipa server-mod ipa02.example.com --location=datacenter-west

# Verify update
ipa server-show ipa02.example.com
  Server name: ipa02.example.com
  Location: datacenter-west

# Clients will now discover ipa02 as west datacenter server

Setting Service Weight for Load Balancing

Control which servers clients prefer by adjusting service weights.

# Default weight is typically 100
ipa server-show ipa01.example.com
  Server name: ipa01.example.com
  Service weight: 100

# Lower weight to prioritize ipa01 for client connections
ipa server-mod ipa01.example.com --service-weight=50

# Increase weight on ipa02 to deprioritize
ipa server-mod ipa02.example.com --service-weight=200

# Clients will prefer ipa01 (weight 50) over ipa02 (weight 200)
# Useful for draining servers before maintenance

Removing Decommissioned Server from Topology

After server hardware failure or planned retirement, remove server entry from IPA.

# Verify server is truly offline/decommissioned
ping ipa-old.example.com
  # No response

# Remove server from topology
ipa server-del ipa-old.example.com

# Warning appears if server has unique roles or creates topology disconnect
# Review warnings carefully

# Force removal if server physically destroyed
ipa server-del ipa-old.example.com --force

# Ignore topology disconnect warnings (use carefully)
ipa server-del ipa-old.example.com \
  --ignore-topology-disconnect \
  --ignore-last-of-role

# Verify removal
ipa server-find | grep ipa-old
  # No results - server removed

Finding Servers with Specific Roles

Identify which servers provide CA services for certificate operations planning.

# Find servers with CA role enabled
ipa server-find --servroles="CA server"
  Server name: ipa01.example.com
  Enabled server roles: CA server, DNS server

  Server name: ipa02.example.com
  Enabled server roles: CA server, KRA server

# Two CA servers available
# Certificate operations can use either server

Changing Server State for Maintenance

Hide server from DNS service discovery during maintenance without removing it from topology.

# Check current server state
ipa server-show ipa01.example.com
  Server name: ipa01.example.com
  Enabled: TRUE

# Hide server for maintenance (prevents new client connections)
ipa server-state ipa01.example.com --state=hidden

# Verify state change
ipa server-show ipa01.example.com
  Enabled: FALSE

# Perform maintenance
# Server still in topology but not advertised via DNS SRV

# Re-enable after maintenance
ipa server-state ipa01.example.com --state=enabled

# Verify re-enabled
ipa server-show ipa01.example.com
  Enabled: TRUE

Auditing Server Configuration Across Deployment

Generate comprehensive report of all server configurations for documentation.

# Generate server configuration report
for server in $(ipa server-find --pkey-only | grep "Server name" | awk '{print $3}'); do
  echo "=== $server ==="
  ipa server-show "$server" --all
  echo ""
done > server-configuration-report.txt

# Report includes:
# - All server names
# - Locations
# - Service weights
# - Enabled roles
# - Domain level support
# Useful for capacity planning and compliance

Filtering Servers by Managed Suffix

Find servers managing specific replication suffixes (domain, ca, pki-tomcat).

# Find servers managing domain suffix
ipa server-find --topologysuffixes=domain
  Server name: ipa01.example.com
  Server name: ipa02.example.com
  Server name: ipa03.example.com
  # All servers manage domain suffix

# Find servers managing CA suffix (only servers with CA role)
ipa server-find --topologysuffixes=ca
  Server name: ipa01.example.com
  Server name: ipa02.example.com
  # Only CA servers manage ca suffix

Security Considerations

Server deletion is irreversible: Removing a server from the topology permanently deletes its entry and removes replication agreements. If removed accidentally, the server must be reinstalled as a new replica. Verify server name carefully before deletion.

Force deletion bypasses safety checks: Using --force, --ignore-topology-disconnect, or --ignore-last-of-role flags disables critical safety validations. This can break CA functionality (if last CA deleted), create topology disconnects (if server provides only replication path), or cause service outages. Use force options only for destroyed servers.

Hidden servers still accept direct connections: Setting server state to hidden prevents DNS SRV record advertisement but doesn’t prevent clients from directly connecting if they know the hostname. Hidden state is not a security control—use firewall rules to truly block access.

Server information aids reconnaissance: Listing all IPA servers reveals infrastructure details (how many servers, geographic distribution, naming conventions). Limit server query permissions to authorized administrators to prevent reconnaissance.

Location changes affect client routing: Modifying server locations changes which clients discover which servers via DNS SRV records. Incorrect location assignments can route clients to distant servers, causing performance degradation or failover to wrong datacenters.

Service weight manipulation can cause DoS: Setting extremely low service weights on weak servers causes clients to overload those servers, creating denial of service. Setting extremely high weights on all servers prevents client connections. Validate weight changes don’t break client distribution.

Last role server deletion breaks functionality: Deleting the last server providing a critical role (last CA server, last DNSSec key master) breaks that functionality for the entire deployment. --ignore-last-of-role disables this safety check but should only be used when truly decommissioning the feature.

Topology disconnect isolates servers: Deleting servers that provide the only replication path between server groups creates topology disconnects, preventing changes from replicating. Isolated servers diverge, causing split-brain scenarios. Verify topology connectivity before server removal.

Server entries persist after physical destruction: If a server is physically destroyed without proper decommissioning, its IPA entry remains. Stale entries cause replication attempts to failed servers, generating errors. Clean up destroyed server entries promptly.

Domain level mismatches prevent upgrades: Servers with different minimum/maximum domain levels can cause upgrade issues. Before upgrading domain level, verify all servers support the target level to prevent upgrade failures or server isolation.

Troubleshooting

Cannot Delete Server: Topology Disconnect Warning

Symptom: ipa server-del fails with “Removal of server results in topology disconnect”.

Diagnosis: Server provides the only replication path between other servers.

Resolution: Create alternative replication agreements before removal:

# Identify topology
ipa topologysegment-find domain

# Create new replication agreements to preserve connectivity
ipa topologysegment-add domain ipa01-to-ipa03 \
  --left=ipa01.example.com \
  --right=ipa03.example.com

# Verify topology remains connected without ipa02
# Now safe to delete ipa02
ipa server-del ipa02.example.com

Cannot Delete Last CA Server

Symptom: ipa server-del fails with “removal of last CA master is not allowed”.

Diagnosis: Attempting to delete the only server providing CA services.

Resolution: Install CA on another server first, or use --ignore-last-of-role if truly removing CA:

# Install CA on another server
ssh ipa02.example.com
ipa-ca-install

# Verify CA now on multiple servers
ipa server-role-find --role="CA server" --status=enabled
  # Shows ipa01 and ipa02

# Now safe to delete ipa01
ipa server-del ipa01.example.com

# Or, if truly decommissioning CA entirely (rare):
ipa server-del ipa01.example.com --ignore-last-of-role

Server-find Returns Empty Results

Symptom: ipa server-find returns no servers even though IPA is operational.

Diagnosis: Connectivity issue, insufficient permissions, or topology data missing.

Resolution: Verify connectivity and permissions:

# Test IPA connectivity
ipa ping

# Verify user permissions
ipa user-show $(whoami) | grep -i role

# Try as admin
kinit admin
ipa server-find

# Check LDAP for server entries
ldapsearch -Y GSSAPI -b "cn=masters,cn=ipa,cn=etc,dc=example,dc=com" cn
  # Should show server entries

Server Location Cannot Be Removed

Symptom: Want to remove server from location assignment but --location="" fails.

Diagnosis: Location cannot be unset directly; must be changed to different location.

Resolution: Create a default/unassigned location or use workaround:

# Cannot unset location directly
ipa server-mod ipa01.example.com --location=""
  # May fail

# Change to default or "none" location
ipa location-add default --desc="No specific location"
ipa server-mod ipa01.example.com --location=default

# Or use LDAP modify to remove attribute
ldapmodify -Y GSSAPI <<EOF
dn: cn=ipa01.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
changetype: modify
delete: ipalocation
EOF

Server-del Hangs or Times Out

Symptom: ipa server-del command runs indefinitely without completing.

Diagnosis: Network connectivity issue to the server being deleted, or replication agreements stuck.

Resolution: Use force deletion if server is truly offline:

# Verify server is offline
ping ipa-old.example.com
  # Times out

# Force deletion without waiting for server response
ipa server-del ipa-old.example.com --force

# Manually clean up replication agreements if force fails
ipa topologysegment-find domain
# Delete segments involving the old server
ipa topologysegment-del domain ipa01-to-ipaold

Service Weight Not Affecting Client Behavior

Symptom: Changed service weight but clients still prefer wrong server.

Diagnosis: Client DNS caching, service weight changes not propagated to DNS SRV records, or client configuration overrides.

Resolution: Verify DNS SRV records and clear client cache:

# Check DNS SRV records for weight changes
dig _ldap._tcp.example.com SRV
  # Verify weights match server-show output

# On client, clear DNS cache
systemd-resolve --flush-caches

# Verify client IPA configuration
grep -i server /etc/ipa/default.conf
  # If xmlrpc_uri explicitly set, client always uses that server
  # regardless of weights

Cannot Modify Server: Not Found

Symptom: ipa server-mod ipa01.example.com fails with “server not found”.

Diagnosis: Server name incorrect (typo, case mismatch, incomplete FQDN).

Resolution: Use exact server name from server-find:

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

# Use exact name (including domain)
ipa server-mod ipa01.example.com --location=datacenter-east

# Won't work: short hostname
ipa server-mod ipa01 --location=datacenter-east
  # Fails - must use FQDN

Server State Change Not Taking Effect

Symptom: Set server to hidden but still appearing in DNS SRV records.

Diagnosis: DNS caching or DNS zone not updated yet.

Resolution: Verify DNS zone update and wait for TTL expiration:

# Change state to hidden
ipa server-state ipa01.example.com --state=hidden

# Verify state changed in IPA
ipa server-show ipa01.example.com
  Enabled: FALSE

# Check DNS SRV records (may take minutes for update)
dig _ldap._tcp.example.com SRV
  # Wait for DNS TTL to expire and zone to update

# Force BIND reload if using IPA integrated DNS
ssh ipa-dns-server.example.com
rndc reload

Deleted Server Still Appearing in Commands

Symptom: Deleted server still appears in some IPA queries or replication commands.

Diagnosis: Replication lag, stale cache, or incomplete deletion.

Resolution: Force replication and clear caches:

# Force replication
ipa-replica-manage re-initialize --from=ipa01.example.com

# Clear local cache
rm -rf ~/.cache/ipa/

# Verify deletion propagated
ipa server-find | grep old-server
  # Should return no results

# Check topology segments
ipa topologysegment-find domain | grep old-server
  # Should return no results
# If segments remain, manually delete them

Server Shows Wrong Domain Level

Symptom: Server shows minimum domain level 0 but deployment is at level 1.

Diagnosis: Server not upgraded or domain level query cache stale.

Resolution: Upgrade server and refresh:

# On the server, run upgrade
ssh ipa01.example.com
ipa-server-upgrade

# Restart IPA services
ipactl restart

# Clear cache and check again
rm -rf ~/.cache/ipa/
ipa server-show ipa01.example.com
  Min domain level: 1
  Max domain level: 1

Cannot Filter Servers by Role

Symptom: ipa server-find --servroles doesn’t return expected results.

Diagnosis: Role name incorrect or role status filtering needed.

Resolution: Use exact role names from server-role-find:

# Find exact role names
ipa server-role-find --all | grep "Role name" | sort -u
  Role name: AD trust controller
  Role name: CA server
  Role name: DNS server

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

# Wrong: case mismatch
ipa server-find --servroles="ca server"
  # May return no results

Force Deletion Removes Server But Leaves Stale Agreements

Symptom: Used --force to delete server but replication segments still reference it.

Diagnosis: Force deletion bypasses cleanup of replication agreements.

Resolution: Manually clean up stale topology segments:

# Find segments referencing deleted server
ipa topologysegment-find domain | grep deleted-server

# Delete stale segments manually
ipa topologysegment-del domain ipa01-to-deletedserver
ipa topologysegment-del domain deletedserver-to-ipa02

# Verify cleanup
ipa topologysegment-find domain | grep deleted-server
  # Should return no results

Commands

server-del

Usage: ipa [global-options] server-del NAME [options]

Delete IPA server.

Arguments

Argument	Required	Description
`NAME`	yes	IPA server hostname

Options

Option	Description
`--continue`	Continuous mode: Don’t stop on errors.
`--ignore-topology-disconnect`	Ignore topology connectivity problems after removal
`--ignore-last-of-role`	Skip a check whether the last CA master or DNS server is removed
`--force`	Force server removal even if it does not exist

server-find

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

Search for IPA servers.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--name NAME`	IPA server hostname
`--minlevel MINLEVEL`	Minimum domain level
`--maxlevel MAXLEVEL`	Maximum domain level
`--timelimit TIMELIMIT`	Time limit of search in seconds (0 is unlimited)
`--sizelimit SIZELIMIT`	Maximum number of entries returned (0 is unlimited)
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)
`--topologysuffixes TOPOLOGYSUFFIXES`	Search for servers with these managed suffixes.
`--no-topologysuffixes NO-TOPOLOGYSUFFIXES`	Search for servers without these managed suffixes.
`--in-locations IN-LOCATIONS`	Search for servers with these ipa locations.
`--not-in-locations NOT-IN-LOCATIONS`	Search for servers without these ipa locations.
`--servroles SERVROLES`	Search for servers with these enabled roles.

server-mod

Usage: ipa [global-options] server-mod NAME [options]

Modify information about an IPA server.

Arguments

Argument	Required	Description
`NAME`	yes	IPA server hostname

Options

Option	Description
`--location LOCATION`	Server DNS location
`--service-weight SERVICE-WEIGHT`	Weight for server services
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--delattr DELATTR`	Delete an attribute/value pair. The option will be evaluated
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--no-members`	Suppress processing of membership attributes.

server-show

Usage: ipa [global-options] server-show NAME [options]

Show IPA server.

Arguments

Argument	Required	Description
`NAME`	yes	IPA server hostname

Options

Option	Description
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--no-members`	Suppress processing of membership attributes.

server-state

Usage: ipa [global-options] server-state NAME [options]

Set enabled/hidden state of a server.

Arguments

Argument	Required	Description
`NAME`	yes	IPA server hostname

Options

Option	Description
`--state STATE`	Server state

Overview

Server Lifecycle

Hidden Replicas

Server Attributes

Multi-Master Topology

Use Cases

Listing All IPA Masters in Deployment

Finding Servers by Location

Checking Server Configuration Before Decommissioning

Modifying Server Location for Client Affinity

Setting Service Weight for Load Balancing

Removing Decommissioned Server from Topology

Finding Servers with Specific Roles

Changing Server State for Maintenance

Auditing Server Configuration Across Deployment

Filtering Servers by Managed Suffix

Security Considerations

Troubleshooting

Cannot Delete Server: Topology Disconnect Warning

Cannot Delete Last CA Server

Server-find Returns Empty Results

Server Location Cannot Be Removed

Server-del Hangs or Times Out

Service Weight Not Affecting Client Behavior

Cannot Modify Server: Not Found

Server State Change Not Taking Effect

Deleted Server Still Appearing in Commands

Server Shows Wrong Domain Level

Cannot Filter Servers by Role

Force Deletion Removes Server But Leaves Stale Agreements

Commands

server-del

Arguments

Options

server-find

Arguments

Options

server-mod

Arguments

Options

server-show

Arguments

Options

server-state

Arguments

Options

Related Topics