Why renaming a FreeIPA server means replacing it
FreeIPA cannot rename a server in place, so changing a server's host name means replacing it. You install a new replica under the new name, move the roles the old server carries onto it, and then retire the old server. This matters most when a server name no longer fits a new naming standard, when a site moves to a new data center, or when hostnames have drifted from what the team documents. Start by treating the rename as a replacement project with its own plan, not as a configuration edit. The work sits between installing a replica and decommissioning a server, and each step depends on the one before it being verified.
The reason is that a FreeIPA server's identity is bound to its host name in several places at once. The name appears in DNS records, including the SRV records clients use to find servers, in the certificates issued to the server, in the replication agreements that link it to its peers, and in the client configuration that points machines at it. FreeIPA runs as a replicated, multi-master directory built on 389 Directory Server, as described on the FreeIPA About page, so every replica must agree on the topology. Changing the name of a live member would leave these references pointing at a host that no longer answers to them. Replacement gives each new name a clean identity from the start.
Before you begin, confirm three things with your own environment rather than assuming them. List every place the old name is referenced, including DNS zones, certificate subjects, monitoring and any hard-coded client or script settings. Identify which roles the old server holds, such as CA, DNS, KRA or the CA renewal server, because each one needs a new home before the old server is removed. Finally, check that the replacement host has forward and reverse DNS resolution for its new name. The order of operations matters: the new replica must be healthy and replicating before the old one is taken out of service, or you risk losing the only copy of a role.
Which parts of the server identity you must change
The old server's host name is recorded in several places: its own system configuration, the forward A or AAAA record, the reverse PTR record, and the service records that FreeIPA publishes for the server. Because the host name cannot be changed in place, the new server gets a new name and a new DNS entry, and the old entry is removed only after the old server has been deleted from the topology. Keeping both names resolvable for a while is normal, but the reader should not treat the old name as a rename target.
- Forward and reverse records: Confirm the new name resolves forward and back before any install begins.
- Old records: Remove the old A or AAAA and PTR records after server deletion, not before, so replication and clients do not lose a working path mid-change.
- Service records: Check that the SRV records for the old name are gone once the server is deleted.
- Hostname on the machine: Set the new fully qualified name on the new host, not on the old one.
Before you start, check that every record for the old name is accounted for in your DNS zones, including any external copies.
The server certificate is issued to the host name, so a replica with a new name needs its own certificate. The roles the old server holds are the other half of this tab. A server may carry the certificate authority, integrated DNS, and the key recovery authority (KRA). Each role must be confirmed on another server or moved before the old server is removed, because removing a server that holds a role can leave that service without a working copy. The renewal server and CRL publisher role is held by the first server by default, so check whether the old server holds it and plan the move explicitly.
- Host certificate: The new replica receives its own certificate during installation, tied to the new name.
- CA role: Confirm that another server carries the certificate authority before deleting the old server.
- DNS role: Make sure remaining servers serve the zones the old server served.
- KRA role: If the KRA is in use, confirm where key archival runs afterward.
- Renewal and CRL role: Check which server holds it and move it deliberately.
Confirm the role list on the old server against your inventory before deletion.
Replication is where the rename is most likely to cause outages. Each replica keeps agreements with its peers, and those agreements name specific hosts. A new replica must be joined to the topology with agreements to the servers it will replicate with, and the old server's agreements must be removed when it is retired. The deployment guidance limits each replica to a set number of replication agreements, so the new server should not be added without checking how its agreements fit the existing layout. Removing the old server cleanly means confirming that every remaining server still has a path to the rest of the topology.
- New agreements: Create agreements from the new replica to the servers that will carry its traffic.
- Agreement limits: Check the per-replica agreement count against the deployment recommendations before adding links.
- Connectivity after removal: Verify that the remaining servers still form a connected topology without the old server.
- Stale data: Do not restore an old backup into the active topology, because this can break replication.
- Replication status: Check replication health on every server before and after each step.
Run the replication health check on every server before you delete the old one.
Clients and network devices refer to servers by name. Enrolled Linux machines hold configuration that points at specific FreeIPA servers, and SSSD on those machines may cache or prefer a server it has used before. Any load balancer, virtual IP, or service entry that lists the old host name must be updated to the new one. The deployment recommendations also ask for at least two DNS servers in each client's resolver configuration, so a client that lists only the old server may lose DNS once that server is removed.
- Resolver configuration: Check each client's resolv.conf and make sure at least two DNS servers remain in it.
- Load balancers: Update pool members and health checks that name the old server.
- Application configuration: Find applications and scripts that point at the old host name for LDAP, Kerberos, or the web UI.
- Client caches: Expect SSSD on clients to rediscover servers over time, and test a sample of clients after the change.
- Hard-coded entries: Search configuration management for the old name.
Build an inventory of every client and service that names the old server before you delete it.
Sites that use DNS locations let clients prefer nearby servers. Each server is assigned to a location, and location-aware SRV records steer clients toward servers in their own site. Retiring a server removes it from its location, so the new server must be assigned to the same location before the old one is deleted. If the location assignment is missed, clients in that site may fall back to servers in another site and generate cross-site authentication traffic. Confirm the location assignment and SRV results for each site as part of the change.
- Location assignment: Assign the new replica to the same location as the server it replaces.
- SRV results: Query the location-aware SRV records for each site and confirm the new name appears.
- Cross-site traffic: Watch for clients that begin to authenticate against distant servers after the change.
- Removed entries: Confirm that deleting the old server removes its location membership.
Query the SRV records from a client in each site before you call the change complete.
Replacement options and when each fits
This table compares the three ways to get a FreeIPA server under a new name: adding a replica with the new name, migrating to a fresh deployment, or relabeling the old server. Read each row for the situation it suits and the cost or risk it carries, then check the migration row against your own topology before choosing.
| Option | When it fits | Main cost or risk |
|---|---|---|
| Replica with the new name, then retire the old server | The deployment stays in the same realm and domain, and the server name is what must change. Most teams with a working multi-server topology choose this. | Requires a new replica install, moving CA renewal, DNS, and CRL roles, then decommissioning the old server. Confirm role holders before removal. |
| Migrate to a fresh deployment with ipa-migrate | A new realm or domain is acceptable, or the existing deployment is being rebuilt anyway. Users, groups, certificates, sudo and HBAC rules, hosts, DNS, OTP tokens and policies can move over LDAP. | Clients, Kerberos principals, and certificates must be re-pointed to the new deployment, which affects every enrolled machine. Confirm how each object type migrates in your version before planning. |
| Keep the old name and change only the display label | The name is cosmetic only, such as a label shown in documentation or inventory, and clients and certificates already depend on the hostname. | Does not change the server's actual host name. Any name-based mismatch in DNS, certificates or Kerberos remains in place. |
| Restore from backup into a new server | Useful as a rollback point before any of the other options, not as a rename method on its own. | Restoring an outdated backup into an active replica topology can break replication, so restore only into an isolated test environment. |
| Downtime and client impact | Replica replacement can usually be staged with clients still pointing at the old server until roles move. | Clients may cache old server names. Ask for a client re-test plan before cutover. |
| Effort driver | Number of clients, certificates, custom policies and integrations affects the work in every option. | Ask any partner for a written inventory of these items before agreeing a fixed scope. |
Replacing a FreeIPA server step by step
This sequence moves every role and replication agreement from the old server to a new replica with the target host name, then removes the old server without breaking authentication for clients.
Record current roles and replication agreements
Before changing anything, the administrator records the old server's roles (CA, DNS, KRA, NTP, and any CA renewal or CRL publisher role), its replication agreements with every other server, its DNS locations, and the clients that use it as their preferred server. Run ipa server-role-find and ipa topologysegment-find to capture this state, and save the output outside the servers being changed. The step is done when the list is stored and every role holder and agreement is written down against the old host name.
Confirm other servers cover critical roles
The administrator checks that at least one other server holds each role the old server carries, especially the CA renewal server and CRL publisher role, which the first server holds by default. If the old server holds that role, the plan must move it to a surviving server before removal. The check is complete when each role has a named holder other than the old server and the team has confirmed that holder is healthy and reachable from every site.
Verify a current backup exists
The team runs a fresh ipa-backup on a healthy server, confirms the backup files are present and readable, and records where they are stored. The FreeIPA backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so the backup must be taken at this point in the process and not reused from an earlier date. The step is done when the backup location and timestamp are recorded and a restore path has been identified.
Install and verify the new replica
The administrator installs a replica with the new host name, checking forward and reverse DNS resolution first, and selects the same CA, DNS and KRA roles the old server carried. Replication agreements are created to the surviving servers, following the deployment recommendations on replica count and agreements per replica. The step is verified when replication status shows no errors, the new host appears in ipa server-find, and a test login and certificate request succeed against it.
Move roles and repoint clients
The administrator moves the CA renewal, CRL publisher and any other roles to the new replica where the plan requires it, and updates DNS SRV records, DNS locations and any client or service configuration that names the old host. Clients using the old server as a fixed target are pointed at the new one or at DNS discovery. The step is complete when a sample of enrolled Linux clients resolve and authenticate through the new server and the role-find output matches the plan.
Remove the old server from the topology
With roles moved and clients confirmed, the administrator runs ipa server-del against the old host from a surviving server. This removes its replication agreements and directory entries from the topology. The step is verified when ipa server-find no longer lists the old host and replication status on the remaining servers shows no references to it.
Uninstall the old server and clean its records
The administrator uninstalls FreeIPA on the old host, then removes its A and reverse records and its NS entries from the DNS zones, along with any SRV or location records that still name it. Any HSM-held keys the server used are handled according to the decommissioning procedure. The step is done when DNS queries for the old host name return no answer, the NS records list only live servers, and a final replication and authentication check passes across the remaining topology.
Moving the CA renewal server and CRL role before retirement
Before a FreeIPA server is retired under a new name, you must confirm which server holds the CA renewal server and CRL publisher role and move it to a surviving server. FreeIPA's backup documentation notes that the first server in a deployment handles certificate renewal and CRL publication by default. If that server is removed or replaced without a handover, renewal of shared certificates and publication of certificate revocation lists stop being handled, and the failure may only surface when certificates approach expiry or when a revocation check fails for clients.
Run the check on the current server before building the replacement, and again after the new replica is in place. Ask the directory administrator to confirm the renewal and CRL role holder with the FreeIPA tooling for your installed release, and record the result alongside the DNS and CA role assignments. Plan the role move as a separate, reversible step with a named owner and a rollback point. Do not treat a backup as a shortcut for this step: the backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so a backup taken before the handover is not a safe fallback if the topology has changed since.
The deployment recommendations advise at least one replica per datacenter running PKI or DNS where those services are used. That guidance matters for renaming because the replacement server should take over the CA and DNS roles in the same site as the server it replaces, so no datacenter is left without a PKI-capable replica during the transition. Confirm the replication agreements and the surviving replicas per site before the old server is stopped. The detailed steps for moving roles and retiring the old host are covered in the sibling sections on replica installation and decommissioning, so use this step as a gate: the rename proceeds only once the renewal and CRL role is confirmed on a server that will remain in service.
Security and operational risks during a server swap
Replacing a FreeIPA server touches backups, certificates, roles, DNS and admin access at the same time. The cards below cover the failure points that matter most during a rename, and each one names a check to run before the old server is retired.
Stale backups restored into a live topology
An ipa-backup taken before the swap can break replication if it is restored into an active topology. During a rename, teams sometimes restore an old backup to recover from a failed step. Take a fresh backup before each stage, record which server it came from, and confirm replication is healthy before any restore is considered. Ask your team to document who may authorize a restore.
Losing the CA renewal role
The first server holds the CA renewal and CRL publishing role by default. If the server being retired still holds it, certificate renewal and CRL publication stop once it is removed. Confirm which server holds the role before the swap, move it to the replacement, and verify renewal on the new host. Treat this as a gate, not a cleanup step.
Certificates issued to the old host name
Service certificates and the server's own certificates carry the old host name in their subject or subject alternative names. Clients that validate the new name will reject them. List every certificate that references the old name, reissue them for the new host, and plan how services will pick up the replacement. Check expiry dates as part of the inventory.
Clients still resolving the old name
Clients, SSSD configurations, resolv.conf entries and DNS SRV records may still point at the retired server. Stale entries cause timeouts and failed logins after the old server is gone. Confirm that at least two DNS servers remain in each client's resolv.conf, update SRV records and any location assignments, and test authentication from clients in each site.
Admin credentials during the change
A swap involves privileged accounts on several servers, the Directory Manager and admin credentials, and sometimes ticket-granting access for remote installs. Limit who holds these during the change, use named administrator accounts where your policy allows, rotate credentials that were shared, and record each privileged action so the change can be audited afterward.
Keeping a rollback path until verification ends
Do not power down or uninstall the old server until the replacement has passed checks for replication, DNS, CA operations, Kerberos logins and client enrollment. Keep the old server available in a known state until those checks pass and the sign-off is recorded. Write the rollback steps before the change starts, and name the person who decides when to use them.
Questions teams ask before renaming a FreeIPA server
Can FreeIPA rename a server in place?
No. A FreeIPA server cannot be renamed in place, so the practical route is to replace it: install a new replica under the new host name, move the roles the old server carries, and then retire the old server. The old and new names both exist during the transition, which is why the work is planned as a migration of roles and records rather than a single configuration change. Confirm the exact sequence for your FreeIPA version against the official documentation before you schedule anything, because the steps depend on which roles the server holds.
How long does a server rename take, and what drives the duration?
The duration depends less on the install itself than on how much the old server does. The main drivers are the number of roles it holds (DNS, CA, key recovery, certificate renewal and CRL publication), how many clients and services point at it by name, the number of replication agreements that must be rebuilt, and how many sites are involved. Checking DNS records, client configuration, load balancers, monitoring, backups and any hard-coded host names often takes longer than the FreeIPA steps. Ask any partner to show a written step list with checkpoints, and confirm the change window with your own operations team before quoting a date.
What does the work need from our team?
The work needs several inputs before the first command runs. You need administrative access to the FreeIPA domain and to every server involved, control of the DNS zones that hold the host records, and a list of systems that refer to the old name. Your team also needs an agreed change window with a rollback point, and an owner who can approve changes to DNS, certificates and client configuration. A written inventory of roles and dependencies is the most useful artifact to prepare first, because it shapes every later step.
Can our own team rename a FreeIPA server without a partner?
Yes, if your engineers have run FreeIPA replicas before and can test each step in a non-production environment first. The risk is concentrated in the role moves and in the verification between steps, because an error in certificate renewal, CRL publication or DNS can affect many clients at once. A partner is most useful when the environment is large, spans several sites, uses integrated DNS or a CA, or when the team has no recent replica experience. Whichever route you choose, a rehearsal on a copy of the topology is the best predictor of a clean cutover.
What should a partner quote include for a rename?
A quote should follow from a written scope and list the work in terms you can check. Ask for the discovery of current roles and dependencies, the design of the new server and its replication agreements, the rehearsal plan, the cutover runbook, verification steps after each change, the cleanup of DNS records and old server entries, and the handover documentation. Ask which items are one-time and which recur, such as post-change monitoring or later support. DeployOpen does not publish prices. Its engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Do clients need to re-enroll after the server is renamed?
Usually not, if the new server is added as a replica of the same domain and the clients can still resolve and reach the realm. Clients locate FreeIPA servers through DNS and their SSSD configuration, so the important checks are whether the new name appears in DNS and whether clients that name the old server directly are updated. Re-enrollment is typically a fallback rather than the plan. Confirm how your clients discover servers, and test a sample of Linux hosts in each site before and after the cutover.
What happens to certificates the old server issued?
Certificates the old server issued remain valid until they expire or are revoked, and they do not change simply because the server's host name changes. The larger concern is the CA and the certificate renewal and CRL publication role, which must move to another server before the old one is removed. If the old server is removed without that move, renewals and CRL updates can stop. Inventory every certificate that names the old host, such as service certificates on web or LDAP endpoints, and plan their reissue. Confirm the CA details in the FreeIPA certificate documentation for your version.
How DeployOpen scopes and delivers a server replacement
DeployOpen starts a server replacement with a review of the current topology before anything is changed. The review lists every FreeIPA server, its replication agreements, and which roles it holds, including CA renewal server and CRL publisher, DNS, CA and KRA. It also checks each client's resolv.conf and the DNS locations in use, because a rename touches all of them. The output is a written inventory that the client confirms, so that the scope reflects their environment rather than a template.
From that inventory DeployOpen writes a fixed scope. The document names the new host name, the replica that will be installed, the order in which roles move, and the point at which the old server is retired. It also sets out a rollback plan that defines how to stop and return to the previous topology if a replica fails to join or replication breaks. Verification checks are written into the scope as well, covering replication status, DNS resolution in both directions, certificate issuance, and a test login from representative clients. Your team reviews the document and approves it before work begins, and any change to the scope is made in writing.
DeployOpen then carries out the change inside your infrastructure, using your accounts, networks and change windows. Your staff keep control of access, and the work is documented as it proceeds so that your records match what was done. Once the old server is removed, DeployOpen can continue under a retainer that covers monitoring, upgrades and support for the new layout. Confirm with DeployOpen which of these items are included in the fixed scope and which fall under the retainer, and ask for the rollback and verification steps to be stated in the quote.
