Before we will deep dive into VMware SOO management, it is good to understand its architecture and discuss some design considerations. I highly recommend watching the following video
If you have not watched the video yet, do NOT continue and watch it.
The video is great but it is worth to mention that vSphere 6.7 and 6.7U1 come up with few significant improvements in terms of PSC. You can read more about it in the article "External Platform Services Controller, A Thing of the Past". The overall concept stays the same but following enhancements were released:
What is my SSO Domain Name?
It is good to know what is the SSO Domain Name. If I'm logged in PSC (or VCSA /w embedded PSC), following command will show me what is the SSO domain of this particular domain controller (aka PSC)
/usr/lib/vmware-vmafd/bin/vmafd-cli get-domain-name --server-name localhost
The output in my home lab is following
So my SSO domain is uw.cz
Where my Lookup Service is running?
VCSA command
/usr/lib/vmware-vmafd/bin/vmafd-cli get-ls-location --server-name localhost
show the location of lookup service.
The output in my home lab is following
So my lookup service is located at https://vc01.home.uw.cz/lookupservice/sdk
What is the SSO Site Name?
VCSA command
/usr/lib/vmware-vmafd/bin/vmafd-cli get-site-name --server-name localhost
show the site name where particular domain controller (aka PSC) is located.
The output in my home lab is following
So my PSC is on site ledcice which is the village name where my home lab is located.
Domain replication agreements
If I have more PSCs in SSO Domain, I can determine replication agreements and status by command vdcrepadmin as shown below.
cd /usr/lib/vmware-vmdir/bin
./vdcrepadmin
Examples:
./vdcrepadmin -f showservers -h PSC_FQDN -u administrator -w Administrator_Password
./vdcrepadmin -f showpartners -h PSC_FQDN -u administrator -w Administrator_Password
./vdcrepadmin -f showpartnerstatus -h localhost -u administrator -w Administrator_Password
./vdcrepadmin -f createagreement -2 -h Source_PSC_FQDN -H New_PSC_FQDN_to_Replicate -u ./administrator -w Administrator_Password
./vdcrepadmin -f removeagreement -2 -h Source_PSC_FQDN \
-H PSC_FQDN_to_Remove_from_Replication -u administrator -w Administrator_Password
These procedures are documented in VMware KB "Determining replication agreements and status with the Platform Services Controller 6.x (2127057)" available at https://kb.vmware.com/kb/2127057
Domain repoint
Domain repoint is a feature available since vSphere 6.5 using the cmsso-util CLI command. You can repoint an external vCenter Server from one PSC to another PSC within the same vSphere SSO domain. Data migration for such repointing is not necessary as all data are replicated across all PSC's within SSO domain. vSphere 6.7 U1 also supports repointing across different SSO domains along with data migrations.
With cmssso-util you can do the following operations
Command to unregister system vc02.home.uw.cz would look like
cmsso-util unregister --node-pnid vc02.home.uw.cz --username administrator --passwd VMware1!
How to decommission/remove a PSC from SSO domain?
You should use cmsso-util unregister command to unregister the Platform Services Controller, however sometimes you can get the error, therefore there is another way how to unregister failed PSCs from the SSO database. You can use the command
/usr/lib/vmware-vmdir/bin/vdcleavefed -h hostname -u administrator -w PASSWORD
where hostname is the hostname of the PSC that must be removed.
Usage: vdcleavefed [ -h ] -u [-w ]
implying offline mode if is provided, and the server must have been down.
implying online mode if is not provided
It actually alters SSO configuration and removes federation.
If you have not watched the video yet, do NOT continue and watch it.
The video is great but it is worth to mention that vSphere 6.7 and 6.7U1 come up with few significant improvements in terms of PSC. You can read more about it in the article "External Platform Services Controller, A Thing of the Past". The overall concept stays the same but following enhancements were released:
- vSphere 6.7 and vSphere 6.5 Update 2 introduced enhanced linked mode support for embedded PSC deployments.
- The converge utility in vSphere 6.7 Update 1 allows customers with an external PSC deployment to migrate to an embedded PSC deployment.
- In vSphere 6.7 is the repoint tool. A stand-alone embedded deployment can join or leave a vSphere SSO Domain. Domain repoint is a feature available in vSphere 6.7 using the cmsso-util CLI command. You can repoint an external vCenter Server across a vSphere SSO domain. New in vSphere 6.7 Update 1 is support for embedded deployment domain repoint.
What is my SSO Domain Name?
It is good to know what is the SSO Domain Name. If I'm logged in PSC (or VCSA /w embedded PSC), following command will show me what is the SSO domain of this particular domain controller (aka PSC)
/usr/lib/vmware-vmafd/bin/vmafd-cli get-domain-name --server-name localhost
The output in my home lab is following
root@vc01 [ ~ ]# /usr/lib/vmware-vmafd/bin/vmafd-cli get-domain-name --server-name localhost
uw.cz
So my SSO domain is uw.cz
Where my Lookup Service is running?
VCSA command
/usr/lib/vmware-vmafd/bin/vmafd-cli get-ls-location --server-name localhost
show the location of lookup service.
The output in my home lab is following
root@vc01 [ ~ ]# /usr/lib/vmware-vmafd/bin/vmafd-cli get-ls-location --server-name localhost
https://vc01.home.uw.cz/lookupservice/sdk
So my lookup service is located at https://vc01.home.uw.cz/lookupservice/sdk
What is the SSO Site Name?
VCSA command
/usr/lib/vmware-vmafd/bin/vmafd-cli get-site-name --server-name localhost
show the site name where particular domain controller (aka PSC) is located.
The output in my home lab is following
root@vc01 [ ~ ]# /usr/lib/vmware-vmafd/bin/vmafd-cli get-site-name --server-name localhost
ledcice
So my PSC is on site ledcice which is the village name where my home lab is located.
Domain replication agreements
If I have more PSCs in SSO Domain, I can determine replication agreements and status by command vdcrepadmin as shown below.
cd /usr/lib/vmware-vmdir/bin
./vdcrepadmin
Examples:
./vdcrepadmin -f showservers -h PSC_FQDN -u administrator -w Administrator_Password
./vdcrepadmin -f showpartners -h PSC_FQDN -u administrator -w Administrator_Password
./vdcrepadmin -f showpartnerstatus -h localhost -u administrator -w Administrator_Password
./vdcrepadmin -f createagreement -2 -h Source_PSC_FQDN -H New_PSC_FQDN_to_Replicate -u ./administrator -w Administrator_Password
./vdcrepadmin -f removeagreement -2 -h Source_PSC_FQDN \
-H PSC_FQDN_to_Remove_from_Replication -u administrator -w Administrator_Password
These procedures are documented in VMware KB "Determining replication agreements and status with the Platform Services Controller 6.x (2127057)" available at https://kb.vmware.com/kb/2127057
Domain repoint
Domain repoint is a feature available since vSphere 6.5 using the cmsso-util CLI command. You can repoint an external vCenter Server from one PSC to another PSC within the same vSphere SSO domain. Data migration for such repointing is not necessary as all data are replicated across all PSC's within SSO domain. vSphere 6.7 U1 also supports repointing across different SSO domains along with data migrations.
With cmssso-util you can do the following operations
- Repoint vCenter Server to Another External Platform Services Controller in the Same Domain
- Repoint vCenter Server to External Platform Services Controller in a Different Domain
- Repoint vCenter Server with Embedded Platform Services Controller to Another vCenter Server with Embedded Platform Services Controller in a Different Domain
root@vc01 [ ~ ]# cmsso-util
usage: cmsso-util [-h] {unregister,reconfigure,repoint,domain-repoint} ...
Tool for orchestrating unregister of a node from LS, reconfiguring a vCenter Server with embedded PSC and repointing a vCenter Server to an external
PSC in same as well as different domain.
positional arguments:
{unregister,reconfigure,repoint,domain-repoint}
unregister Unregister node. Passing --node-pnid will unregister solution users, computer account and service endpoints. Passing --hostId
will unregister only service endpoints and solution users.
reconfigure Reconfigure a vCenter with an embedded Platform Services Controller(PSC) to a vCenter Server. Then it repoints to the provided
external PSC node.
repoint Repoints a vCenter with an external Platform Services Controller(PSC) to the provided external PSC node.
domain-repoint Repoint Embedded vCenter Server from one vCenter Server to another given domain. The repoint operation will migrate Tags,
Authorization, License data to another Embedded node.
optional arguments:
-h, --help show this help message and exit
Command to unregister system vc02.home.uw.cz would look like
cmsso-util unregister --node-pnid vc02.home.uw.cz --username administrator --passwd VMware1!
How to decommission/remove a PSC from SSO domain?
You should use cmsso-util unregister command to unregister the Platform Services Controller, however sometimes you can get the error, therefore there is another way how to unregister failed PSCs from the SSO database. You can use the command
/usr/lib/vmware-vmdir/bin/vdcleavefed -h hostname -u administrator -w PASSWORD
where hostname is the hostname of the PSC that must be removed.
Usage: vdcleavefed [ -h
implying offline mode if
implying online mode if
How to List of Services Registered with Single Sign-On
For vSphere 6.x
/usr/lib/vmidentity/tools/scripts/lstool.py --list
For vSphere 7.x
/usr/lib/vmware-lookupsvc/tools/lstool.py list --url http://localhost:7090/lookupservice/sdk
How to converge VMware SSO domain topology?
Before vSphere 6.7 U1, there was no way how to converge existing SSO topology, however, vSphere 6.7 U1 allows such convergence. If you have deployed or installed a vCenter Server instance with an external Platform Services Controller, you can convert it to a vCenter Server instance with an embedded Platform Services Controller using the converge utility vcsa-util. You can locate the vcsa-util utility in the vcsa-converge-cli directory in vCenter installation media (DVD).
With vcsa-coverge-cli you can do the following operations
- Reconfiguring vCenter Server with an External Platform Services Controller to a vCenter Server with an Embedded Platform Services Controller
- Reconfigure a Standalone vCenter Server with an Embedded Platform Services Controller to a vCenter Server with an External Platform Services Controller
For further practical information and examples, you can read following blog posts
Conclusion
I prefer simplicity over complexity, therefore I personally like all improvements vSphere 6.7 U1 brings into the table. I'm always trying to keep SSO topology as simple as possible. However, in large environments with multiple sites across multiple regions, there can be requirements leading to more complex SSO topologies.
Update 2021/05/07: I have just been told about very useful tool (lsdoctor) to address potential issues with data stored in the PSC database. See. VMware KB "Using the 'lsdoctor' Tool" https://kb.vmware.com/s/article/80469
Hope this blog post is useful at least for one other person than me. If you know some other commands or ways how to manage VMware SSO domain, please leave the comment below this blog post.
Hope this blog post is useful at least for one other person than me. If you know some other commands or ways how to manage VMware SSO domain, please leave the comment below this blog post.
