Use PowerCLI to manage users on an ESXi host

Starting with vSphere 6.0 VMware introduced a new set of ESXCLI commands to manage the life cycle of local accounts and permissions.

I have created ESXiAccountManagement.ps1 script that includes the following functions:

• Get-ESXiAccount: List all local accounts and their role
• Add-ESXiAccount: Create local accounts and assign one of the predefined roles
• Set-ESXiAccount: Updates user’s Description, permission (one of the predefined roles) and most popular reset the user password.
• Remove-ESXiAccount: Removes a local account
• Get-ESXiAccountSecurity: Get ESXi host local account security settings and can also assist in checking events for account locked and bad logon events (past 1, 2 or 24 hrs)

Running the script

Make sure to run the Get-Help (Example: Get-Help Get-ESXiAccount –ShowWindow) command to understand all the parameters and switches. All these functions make use of the new ESXCLI commands so the script will only run against ESXi 6.x hosts. The script also assumes that you already have a connection to a vCenter, let’s walk through a few examples to show the script in action.

Get-ESXiAccount

A script function to list all local accounts, can be run against a host, cluster, or datacenter

Syntax

Get-ESXiAccount [[-VMhost] <Object>] [[-Cluster] <Object>] [[-Datacenter] <Object>] [<CommonParameters>]

Add-ESXiAccount

A script function to add/create a new local user. The script will first check if a User ID with the same name already exists before creating it. You are prompted for the user’s password during the script execution, this uses Get-Credential object which stores and relays the password as a secure string.

The –Permission parameter will show you a list of options, which are the predefined roles supported (Admin, ReadOnly, NoAccess)  to grant a user.

Syntax

Add-ESXiAccount [-Name] <String> [[-Description] <String>] [[-Permission] <Object>] [[-VMhost] <Object>] [[-Cluster] <Object>] [[-Datacenter] <Object>] [<CommonParameters>]

Creating a user account

Let’s create a monitoring service account needed on the ESXi host, user ID: sysmonitoring

Note the following on this example:

• I’m specifying the User ID, Description and Permission for the new user (sysmonitoring)
• I was prompted for the password
• User creation failed because the password I used did not meet the password quality control policy
• The password policy in place is the default, and is displayed as part of the feedback on the error message

Let’s try that again using a stronger password

Set-ESXiAccount

A script function to reset a user’s password, update description, or update permission. Same as Add-ESXiAccount, you will be prompted for the new password when resetting a user’s password and the password strength must meet the policy requirements.

Syntax

Set-ESXiAccount [-Name] <String> [[-Description] <String>] [[-Permission] <Object>] [-ResetPassword ] [[-VMhost] <Object>] [[-Cluster] <Object>] [[-Datacenter] <Object>] [<CommonParameters>]

Recovering the root user on a ESXi host

The most popular use case for this is when you have forgotten the root user password on the ESXi host. You can stop using host profiles, SSH keys, etc, and just do it through PowerCLI!

Note the following on this example:

• I was able to recover/reset the root password using PowerCLI
• Password complexity applies, so keep that in mind or else you will get the error as the previous example when adding a new user

Changing user description and permissions

Now that I have created sysmonitoring user, I want to update the description and also found out that it needs admin privileges instead of ReadOnly (hypothetical example).

Remove-ESXiAccount

A script function to delete an ESXi local user, can be run against a host, cluster, or datacenter. This will remove user created accounts, not system accounts (root for example)

Syntax

Remove-ESXiAccount [-Name] <String> [[-VMhost] <Object>] [[-Cluster] <Object>] [[-Datacenter] <Object>] [<CommonParameters>]

Trying to remove a system account (root)

Note the following on this example:

• System accounts are protected against deletion
• Some of these scripts functions are powerful, use with caution

Removing sysmonitoring user ID (user created account)

Continuing with our example, I now don’t have the need to keep sysmonitoring any longer, so I shall remove him

Note the following on this example:

• Sysmonitoring user was successfully removed
• A listing of all local accounts on the ESXi host shows that sysmonitoring user is no longer present

Get-ESXiAccountSecurity

A script function to list account lockout policy, password quality control policy and to gather events for troubleshooting account lockouts and bad logons

Syntax

Get-ESXiAccountSecurity [[-EventsPastHrs] <Int32>] [[-VMhost] <Object>] [[-Cluster] <Object>] [[-Datacenter] <Object>] [<CommonParameters>]

-EventsPastHrs is the switch used to query for account lockout , and bad logon events. It has 3 predefined options (1, 2, 24) hours.

Troubleshooting account logon scenario

Let’s look at a hypothetical example:

• Dellomsa was created and given an admin role
• This account has stopped working, I cannot logon with it. Suspecting a bad password, I went ahead and did a password reset
• After resetting the password, I’m still not able to login

To troubleshot further I then looked for account events

Note the following on this example:

• System has the default settings for Lock Failures, Unlock Time, and complexity
• I cannot login with dellomsa because its locked out, so I need to wait for the Unlock time to expire or use SSH to unlock it
• I queried the events for the past hour and have identified the IP where the bad logons are coming from
• The failed logon attempts (50 failed login attempts) is a global counter on the ESXi host for all bad logon attempts. I have been playing with this host, validating the scripts and writing this blog. I in fact just tried to logon 6 times with a bad password to get dellomsa user locked out. 5 attempts is default policy before locking out and 15 minutes to unlock.
• If a local account is locked out, you will get a warning on the host in vCenter as well

As you can see using PowerCLI is a great way to manage and troubleshoot ESXi user accounts hope this has been helpful for you.