As an IT administrator and consultant, you must be prepared for changes in your IT environment. Acquisitions, migrations to another company, changing naming conventions, or renaming a whole system to match the new environment are daily facts. A VMware vSphere Single Sign-On (SSO) domain used for authentications can be changed and repointed to another domain.

SSO Domain Repointing was introduced in vSphere 6.7 to allow the repointing of a vCenter Server from one SSO Domain to another. Let's say you have an environment with a couple of vCenter Servers, each within one site. One day, your boss tells you that your company just bought another company and that you need to manage the new environment. By repointing the other company’s SSO domain to your company's SSO domain, you'll be able to "join" that other vCenter Server to your organization and manage all the vCenter Servers with Enhanced Linked Mode (ELM). You can also use repointing to separate SSO domains if your company sells one part of the business to another company.

This post is quite technical, but don't worry—we explain all the necessary operations and the tools you'll need in detail.

Note this is not supported with vCenter installed on Windows. It works only with vCenter Server Appliance (VCSA).

In our example below, you can see we have a vCenter Server with an SSO domain called "," and we'll be migrating it into an existing domain called "vsphere.local."

How to repoint a vSphere SSO Domain

How to repoint a vSphere SSO Domain

We must first enable SSH and the BASH shell to be able to log in to our VCSA appliance via the SSH client. To do so, connect to the administration interface of the VCSA via https://ip_of_vcsa:5480 and log in with the root account and password.

Then go to Access > Edit

Enable SSH access on vCenter Server Appliance

Enable SSH access on vCenter Server Appliance

Click the SSH login and BASH shell by entering some value greater than 0 for the BASH shell.

Click to enable SSH access

Click to enable SSH access

Now log in to the VCSA appliance via a Putty client. Putty is one of the free SSH clients I use in my lab. There are many other SSH clients; it is easy to find them on the Internet.

Let's log in to our source VCSA appliance now. After providing root credentials at login, type "shell" to access the BASH shell.

Log in to the VCSA appliance with the Putty client

Log in to the VCSA appliance with the Putty client

We can then issue a command that will show us the various options that are available for repointing or reconfiguring the SSO domain.

Many architectural options are possible, since VMware Platform Services Controller (PSC) can also be installed as a separate virtual appliance. But in our case, we have PSC running on the same virtual machine (VM) as the vCenter Server.

Type the "cmsso-util" command and press Enter.

Use cmsso util to see the options

Use cmsso util to see the options

We will be migrating this vCenter Server into an existing SSO domain, so we need to do a "precheck" operation and review any conflicts. After the precheck, we can use the "execute" option, which will, as its name suggests, execute the actual operations.

Note: You might also need to merge two domains to create a third (new) SSO domain, rather than migrating anything to an existing domain. In this case, you don't need to perform the precheck since you don't expect any conflicts.

The default resolution mode for Tags and Authorization conflicts is Copy, so even if you don't verify whether there are conflicts, you might end up with some doubles at the destination.

We'll launch the precheck command now.

The syntax:

cmsso-util domain-repoint -m pre-check --src-emb-admin Administrator --replication-partner-fqdn FQDN_of_destination_node --replication-partner-admin PSC_Admin_of_destination_node --dest-domain-name destination_PSC_domain

In my case, the command looks like this:

cmsso-util domain-repoint -m pre-check --src-emb-admin Administrator --replication-partner-fqdn vcsaphoton.lab.local --replication-partner-admin Administrator --dest-domain-name vsphere.local

where my destination domain name is "vsphere.local" and my destination VCSA fully qualified domain name (FQDN) is "vcsaphoton.lab.local."

Note: I recently wrote an article entitled Change a VMware vCenter Server Appliance (VCSA) system name (FQDN). You might find it useful.

You are prompted for the Administrator's password twice, once for the source vCenter Server and once for the destination vCenter Server.

Domain repoint precheck

Domain repoint precheck

Validate by typing "Y." After few minutes, you'll get a recap screen that looks like this:

Location of registered conflicts are registered

Location of registered conflicts are registered

You should now go and check the "conflicts.json" file, as you see on the screen. For our lab article, we know we do not have any tags or authorizations that would conflict with the destination system, so we can skip that.

After the precheck, we can now finally use the "execute" option, which has replaced the "pre-check" option. This time, the operation takes more time as the system must not only copy all files over to the destination, but also uninstall the platform services controller and reinstall it.

cmsso-util domain-repoint -m execute --src-emb-admin Administrator --replication-partner-fqdn vcsaphoton.lab.local --replication-partner-admin Administrator --dest-domain-name vsphere.local

Here is the screenshot.

SSO repointing was successful

SSO repointing was successful

To check out the changes, let's have a look at the VCSA management user interface.

After repointing, you can verify the VCSA management interface

Then connect to your vCenter Server as usual and select Menu > Global Inventory list.

Check the global inventory list

Check the global inventory list

The second vCenter Server is displayed here.

After repointing you will see both vCenter servers

After repointing you will see both vCenter servers

If your architecture has some external PSCs, you should consult VMware online documentation and search "syntax of the domain repoint command" because you would need to use different options for external PSCs. It's a shame this command is only available via the command line and is not integrated into the VCSA user interface. It might just be a simple question of time and we will see it in the next major version, though.

This is usually case with VMware, as we could see it with a conversion tool used to convert external PSCs into embedded ones. Starting with vSphere 6.7 Update 2, VMware has provided this utility integrated into the vSphere management user interface, where it was previously available only via a command line.

  1. Avatar
    vmjoe 4 years ago

    I've once used cmsso-util domain-repoint to consolidate two vCenter appliances into one (then migrated stuff and eventually got rid of one instance).

    But now I have a situation, where the instance to domain-repoint is on Windows (6.7 U3), which means the command cmsso-util domain-repoint is not available.

    I wanted to convert/migrate it into an appliance then, but that's also not possible, as the wizard only supports migrations that are also a version upgrade! "Horizontal" conversions from Windows to VCSA are not supported! As there's no 6.7 U4 or vSphere 7.0 yet, it seems I can't get rid of the Windows vCenter now?

    Then I had the idea to repoint the Windows instance first to an external PSC (appliance), and in a second step domain-repoint it to the existing target vCenter (appliance 6.7 U3).

    But I'm not sure if this is possible – would the cmsso-util command be still issued on vCenter, or on the PSC?

    • Avatar Author

      Oh, I missed this one it seems. I guess my answer is no longer necessary -:). Sorry about that Joye.

  2. Avatar
    George 2 years ago

    Does vCenter admin passwords also get reverted to the target replication partner’s admin password once the repointing is done. Our source admin password is no longer working for us for the the source vCenter FQDN. Appreciate your input on this?

  3. Avatar Author

    Migration finished you login with the destination’s SSO password. Is that what you’re looking for?

  4. Avatar
    Jarrett Kaufman 3 months ago

    We’re stuck in a scenario with a single VCSA that was named to match our AD domain due to an original misunderstanding. We’d like to rename it to something more appropriate, such as the default vsphere.local, but these instructions rely on us repointing it to an existing SSO domain already used by another VCSA. When I attempt to use them, I receive an error that repointing to the same VCSA is not supported. Is there a known way to rename within a single VCSA? We’re on 7.x, FYI.

  5. Avatar Author
    Vladan SEGET 3 months ago

    It seems that you’re running a single node only. If that’s the case, simply rename the node via VAMI UI > Networking > Hostname > Edit. And change DNS records accordingly.

    However, bear in mind thad:
    – Products which are registered with vCenter Server will first need to be unregistered prior to an FQDN change. Once the FQDN change is complete they can then be reregistered.
    vCenter HA (VCHA) should be destroyed prior to an FQDN change and reconfigured after changes
    – All custom certificates will need to be regenerated
    – Hybrid Linked Mode with Cloud vCenter Server must be recreated
    – vCenter Server that has been renamed will need to be rejoined back to Active Directory
    – Make sure that the new FQDN/Hostname is resolvable to the provided IP address (DNS A records).

    After done, you’ll need to:
    – Products registered with vCenter Server will need to be reregistered
    – All custom certificates will need to be regenerated
    – vCenter HA (VCHA) will need to be reconfigured
    – Hybrid Linked Mode (HLM) with Cloud vCenter Server has to be recreated
    – Active Directory will need to be rejoined

    • Avatar
      Jarrett Kaufman 3 months ago

      For clarity though, the hostname doesn’t necessarily correlate to SSO domain though. We have a different VCSA for an unrelated cluster that has a hostname of vcenter.ourlocaldomain.local which is not the same as the SSO domain we gave it, which we left as vsphere.local. So at a glance, it doesn’t look as though the hostname’s domain and the SSO domain are related. Are you certain that renaming it in networking will trigger a change of the SSO domain?

  6. Avatar Author
    Vladan SEGET 3 months ago

    “Are you certain that renaming it in networking will trigger a change of the SSO domain?” I never said that. The utility can be used when you’re running Enhanced Linked Mode (ELM) only.

    To my understanding, It seems, that you only need to change the FQDN as I suggested. You do not run ELM, do you? If you just want to “harmonize” the FQDN name and the SSO domain. (vsphere.local) simply change the FQDN.

Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account