Skip to content

Break Glass (Administrator Password Reset)

The application includes a feature that allows administrators to reset the password of a local user in the base tenant in emergency situations, such as when the password is lost. This local user account is typically an administrator with full access to manage all other tenants. Losing access to this account can prevent administrators from managing the entire deployment, making this recovery option critical for restoring control.

Requirements

To perform a password reset for a local user in the base tenant, the administrator must have access to the following:

  • Active Break Glass Key from the Base Tenant: This key must be current and can be retrieved by base tenant administrators from the base tenant home screen (dashboard) via the Break Glass Key section.

  • Command Line Access to the Active 12Port Deployment: Direct access to the command line of the active system where 12Port is installed is required.

  • Maintenance Mode: The password reset can be performed while the 12Port deployment is shut down for maintenance. Service shutdown is required for this Break Glass operation, plan accordingly.

Recovery Procedure

1. Locate the Deployment Folder

In the steps outlined below, we assume that 12Port is installed in the $HOME directory on the host machine. As an example, $HOME might be C:\12Port on Windows or /opt/12port on Linux.

2. Open Command Prompt

Launch the command line interface (shell on Linux or PowerShell on Windows) and navigate to the $HOME directory.

3. Stop the 12Port Server

To stop 12port server on a Linux host, execute the following command:

sudo systemctl stop 12port

To stop 12port server on a Windows host, execute the following command:

net stop 12port
4. List Local Users in the Base Tenant

Skip this step if you already know the username (e.g., default admin user ztnadmin).

To list local base tenant users, run the following command:

Linux: 

./bin/apptool list-base-users break-glass-key

Windows: 

.\bin\apptool list-base-users break-glass-key

The parameters in the above command are as follows:

  • break-glass-key: The active Break Glass Key from the base tenant.

Example: To print the local users of the base tenant.

List Base Tenant Local Users

.\bin\apptool list-base-users vuS9RQsBjQkbmg3hdcHJdFvuDMeRFAEhrJBNgR9CpM8

The command will produce the list of local users found in the base tenant.

Example Output:

ztnadmin
jwalker
bwilliams

Total: 3.

If the command hangs, it likely indicates the 12Port server is still running. Stop or terminate it before retrying.

In some configurations, diagnostic database messages may appear; these can help support teams troubleshoot any issues.

5. Reset the Password of the Selected Local User.

To reset the selected user's password, use the command:

.\bin\apptool reset-base-user-password break-glass-key account password

In the command above parameters are:

  • break-glass-key: The active Break Glass Key from the base tenant.
  • account: Login name of the account to reset. This name could be visible using the previous command list-base-users.
  • password: New password to set. Use the dash (-) to enter it interactively and avoid exposing it in command history.

Example: The command that resets the password for the deployment administrator user ztnadmin.

.\bin\apptool reset-base-user-password vuS9RQsBjQkbmg3hdcHJdFvuDMeRFAEhrJBNgR9CpM8 ztnadmin -

Example Output:

Reset Selected Local User Password

Password reset

If the command hangs, it likely indicates the 12Port server is still running. Stop or terminate it before retrying.

In some configurations, diagnostic database messages may appear; these can help support teams troubleshoot any issues.

Note

The new password must be at least 12 characters long and can contain any combination of letters and numbers.

6. Restart 12Port Server

To start 12port server on a Linux host, execute the following command:

sudo systemctl start 12port

To start 12port server on a Windows host, execute the following command:

net start 12port

Notes

Any parameter in the command line can be substituted with a dash (-) character. When this is done, the command line tool will prompt the user to input the parameter interactively. For security reasons, sensitive parameters, such as the Break Glass Key, will be masked to prevent them from being displayed on the screen. This is particularly useful for preventing sensitive data from being stored in shell history files.

For example, the list-base-users command below will prompt for the Break Glass Key because the actual Break Glass Key value is not included, but rather is replaced with a dash (-) character after command is defined:

.\bin\apptool list-base-users -

List Based Users with Key Prompt