Resetting the admin@local Password on the VMware Cloud Foundation 9 Installer

During a VMware Cloud Foundation 9 deployment, the VCF Installer becomes one of the most important control points in the environment. It is not just a temporary wizard screen. It is the place where deployment state, validation, bring-up workflows, and local administrative access intersect.

That becomes a problem when the admin@local password is missing, mistyped, expired from operational handling, or simply not recorded in the right vault entry.

The confusion usually comes from the way the installer handles local credentials. Operators may remember setting the root password or using the vcf account for SSH, but the web login depends on the local admin@local identity.

This runbook focuses on one specific recovery case:

You still have authorized access to the VCF Installer appliance with the vcf account and can elevate to root, but you cannot log in to the VCF Installer UI as admin@local.

This is not a general password recovery article for every VCF account. If the vcf or root account is locked, expired, or unknown, use the separate Broadcom recovery process for those appliance accounts.

Why This Matters Operationally

The admin@local account is a recovery and access path for the installer and SDDC Manager API surface. When it is unavailable, you may still be able to SSH to the appliance, but you lose a clean way to work through the installer UI or generate local API tokens.

That matters during bring-up because this is usually when teams are under the most pressure. Hosts are being validated. Management networking is being checked. Certificates, DNS, NTP, passwords, and deployment JSON values are all being scrutinized. A local login failure at this stage can look like a product issue when it is really an identity recovery issue.

The goal is to avoid random file edits, avoid unnecessary redeployments, and recover the local account in a controlled way.

Symptoms and Risk

You are likely in scope for this runbook when:

• The VCF Installer appliance is reachable.
• SSH access with the vcf account still works.
• You can elevate to root.
• The VCF Installer UI rejects the admin@local password.
• Password vault entries do not match the working UI credential.
• There are no active installer workflows that would be disrupted by a service restart.

You are not in scope when:

• The appliance is not reachable.
• The vcf account is locked or unknown.
• The root account is locked, expired, or unknown.
• You are trying to recover vCenter SSO, NSX, ESXi, or VCF Operations credentials.
• You do not have authorization to administer the VCF Installer appliance.

One important detail: Broadcom notes that admin@local is not stored in lookup_passwords, so do not spend time expecting it to appear there during recovery.

Recovery Flow at a Glance

The workflow is simple, but the order matters. Take the snapshot first, confirm you are working on the correct appliance, then update the local password file with the expected ownership and permissions.

Notice that this is not a password lookup process. You are not retrieving the old password. You are replacing the local password material used by the appliance with a new compliant value.

Prerequisites and Safety Checks

Before making the change, confirm the following:

The new password must comply with the documented local account policy: 12 to 127 characters, at least one lowercase letter, uppercase letter, number, and allowed special character, at least two alphabetic characters, and no character repeated more than three times consecutively.

The allowed special characters listed by Broadcom are:

! % @ $ ^ # ? *

Preferred Path When You Still Know the Old Password

Before using a file-level reset, check whether this is actually a password change rather than a recovery.

If the old admin@local password is known, use the supported local account password update path instead. Broadcom’s VCF API documentation includes a PATCH /v1/users/local/admin operation for updating the local account password. It requires oldPassword and newPassword, and returns 204 No Content on success.

Example request shape:

{
  "oldPassword": "",
  "newPassword": ""
}

Use the reset procedure below only when the old password is not available or the UI/API change path is not viable.

Stage 1: Snapshot the Appliance

Take a snapshot of the VCF Installer appliance before changing the local password file.

This is not just a checkbox. The procedure changes files under /etc/security/local, and while the change is small, it is still touching local authentication material. A snapshot gives you a clean fallback if permissions are mistyped, the wrong VM is targeted, or the appliance behaves differently than expected after the change.

Recommended snapshot note:

Pre-admin-local-password-reset -  - 

Do not leave the snapshot in place indefinitely. Remove it after validation and after the new credential is stored in the approved vault.

Stage 2: Connect to the Appliance

SSH to the VCF Installer appliance using the vcf account, then elevate to root.

ssh vcf@
su -

Confirm you are on the expected appliance before continuing:

hostname -f
ip addr

This sounds basic, but in lab rebuilds and customer staging environments, it is common to have more than one installer or SDDC Manager-like appliance available. Do not assume the first SSH session is the correct target.

Stage 3: Create or Repair the Local Password Path

Broadcom’s reset procedure creates /etc/security/local, assigns it to root:vcf_services, and sets the documented directory and file permissions before writing the new password hash.

Run the following as root:

mkdir -p /etc/security/local
chown root:vcf_services /etc/security/local
chmod 650 /etc/security/local

echo -n "" > /etc/security/local/.localuserpasswd
chown root:vcf_services /etc/security/local/.localuserpasswd
chmod 660 /etc/security/local/.localuserpasswd

What this does:

• Ensures the local security directory exists.
• Sets the expected ownership for VCF services.
• Creates or truncates the .localuserpasswd file.
• Applies the expected file permissions before writing the new hash.

Do not improvise the ownership or mode values unless Broadcom Support tells you to. Authentication failures after this procedure are often caused by small permission differences, not by the password hashing command itself.

Stage 4: Write the New admin@local Password Hash

The documented reset command writes a SHA-512 digest encoded with base64 into /etc/security/local/.localuserpasswd.

The common one-line form works, but it places the password directly in the command text. In production, I prefer an interactive prompt so the password is not visible in shell history as part of the command.

read -s -p "New admin@local password: " ADMIN_LOCAL_PASSWORD
echo

printf '%s' "$ADMIN_LOCAL_PASSWORD" \
  | openssl dgst -sha512 -binary \
  | openssl enc -base64 \
  | tr -d '\n' \
  > /etc/security/local/.localuserpasswd

unset ADMIN_LOCAL_PASSWORD

Then verify the file exists and has content:

ls -l /etc/security/local/.localuserpasswd
wc -c /etc/security/local/.localuserpasswd

You are not looking for the password value. You are confirming that the file exists, is not empty, and still has the correct ownership and permissions.

Expected ownership and mode:

root vcf_services
-rw-rw----

Stage 5: Restart Services Only When It Is Safe

At this point, try the UI login first if no restart has occurred. In some situations, the new local credential may be accepted without a broad restart.

If the UI still rejects the new password, wait briefly and then consider a controlled service restart. The field-tested approach commonly used for the VCF Installer is to restart the SDDC Manager services with the operations manager restart script, but treat that as a disruptive action and avoid running it during active workflows.

/opt/vmware/vcf/operationsmanager/scripts/cli/sddcmanager_restart_services.sh

For a locked admin@local account on the VCF Installer, Broadcom documents a more targeted unlock path: SSH to the appliance with vcf, elevate to root, restart commonsvcs, and wait five minutes before trying the login again.

systemctl restart commonsvcs

Use the narrowest action that matches the problem:

Validation Steps

After the reset, validate the change in layers.

First, test the VCF Installer UI with:

Username: admin@local
Password: 

Second, confirm that the credential has been stored in the approved password vault. The reset is not complete until the new password is discoverable by the team that owns the platform.

Third, if API access is part of your operational model, validate token generation through the supported API flow instead of assuming the UI login is enough. Broadcom’s API documentation includes local admin account operations and token-related API behavior.

Finally, remove the snapshot after the change window closes and the appliance has been validated.

Troubleshooting

The Login Still Fails After the Reset

Re-check the basics before assuming the account is broken:

ls -ld /etc/security/local
ls -l /etc/security/local/.localuserpasswd
wc -c /etc/security/local/.localuserpasswd

Confirm:

• The directory exists.
• The .localuserpasswd file exists.
• The file is not empty.
• Ownership is root:vcf_services.
• Permissions match the documented values.
• The password meets the allowed character and complexity policy.

If the account may be locked rather than simply wrong, restart commonsvcs and wait five minutes as described in Broadcom’s unlock procedure.

The New Password Was Pasted Incorrectly

Run the hash-writing step again with the intended password. The procedure overwrites the local password file, so you do not need to delete the file manually.

Use an interactive prompt rather than pasting the password into the command line.

SSH No Longer Works

This runbook does not change the vcf account password. If SSH stops working, treat that as a separate issue. Use console access and the appropriate root or vcf account recovery guidance instead of repeatedly modifying .localuserpasswd.

The Password Works in the UI but Is Not in the Vault

Fix the vault entry immediately. A recovered credential that only exists in one engineer’s terminal session is an operational risk.

Record the new value according to your internal password management process, including change ticket, timestamp, and owner.

Rollback or Fallback

The clean rollback is the VM snapshot taken before the procedure.

Use rollback when:

• The wrong appliance was modified.
• Services do not start correctly after a restart.
• File ownership or permissions were changed beyond the documented procedure and cannot be confidently repaired.
• The deployment is in a sensitive state and you need to return to the previous appliance state.

Do not keep trying random combinations of permissions, hashes, or service restarts. The local account reset is a small change. If it does not behave predictably, return to the snapshot or open a Broadcom Support case with the exact commands run and the current file state.

Command Reference

Conclusion

The admin@local password reset for the VCF 9 Installer is not complicated, but it is easy to mishandle if you treat it like a generic Linux password reset.

The important distinction is that this account is not the same as root or vcf. It is local application access material used by the installer and SDDC Manager API layer. The safest path is to confirm scope, take a snapshot, preserve the expected ownership and permissions, write the new password hash carefully, and validate the UI or API login before closing the change.

For production environments, the real lesson is not just how to reset the password. It is how to avoid needing the reset twice: document which installer appliance was used, vault the admin@local credential correctly, and make sure the platform team understands the difference between appliance OS accounts and local application accounts.

External References

The following references are useful for validating the recovery workflow, separating admin@local recovery from appliance OS account recovery, and confirming supported API behavior.