Skip to content

Break Glass (Emergency Data Retrieval)

The application offers a feature that allows users to access sensitive data from tenant backup files, even when the server is offline, the tenant database or web interface is inaccessible, or the original deployment is unavailable. This type of Emergency Data Retrieval operation is typically referred to as "Break Glass".

Requirements

To retrieve sensitive data, the Administrator must ensure the following are available:

  • Backup files from the original tenant: These backups are essential for data retrieval. To create or schedule periodic backups, refer to the backup section of the product manual: Backup Guide.

  • Break Glass Key from the Original Tenant: The Break Glass Key must be active from the time the backup was created. Space Administrators can obtain the Break Glass Key from the bottom of the tenant’s Home screen (dashboard) using the Break Glass Key controls. If the key was rotated and does not match the one from the backup file, the operation will fail. Be sure to safely store all previous and current keys.

  • Any 12Port Platform Deployment: This can be the original deployment on its original host or a new deployment on a new host. In the case of a new deployment, the Administrator should transfer the backup files to the new host before proceeding.

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. Search for Assets

To search for assets within the backup files, use the following command:

Linux: 

./bin/apptool backup-list backup-file break-glass-key search-criteria

Windows: 

.\bin\apptool backup-list backup-file break-glass-key search-criteria

The parameters in the above command are as follows:

  • backup-file: Path to the backup file (can be absolute or relative).
  • break-glass-key: Break Glass Key from the original tenant.
  • search-criteria: Search term used to find the asset in the backup file. The command will search the asset name or description based on the provided criteria.

Example: To search for assets that match the term "ubuntu" in the backup file backup/TenantEcho/20250711-101251-full-001.zip, use the following command:

.\bin\apptool backup-list backup/TenantEcho/20250711-101251-full-001.zip wdaxx0DgXuLSoKgMQppDkdJ_SLNVodrhuMZaXTKUV_k ubuntu

The command will return a list of matching assets. Each entry will include the asset ID, which can be used to access specific fields, including secret ones.

Below is the example of the command output. The GUID that starts the line is the asset ID.

Break Glass Asset Search Results

446e3774-b10e-40da-bb43-fc86c289dbb0 Prod Web Server Ubuntu - ubuntu web server - production
8f1256b1-f2a3-452f-a22c-8a89d4898469 Ubuntu 20.04
67d62c29-88cd-4591-b63b-945c71888d33 Ubuntu 22.04

Total 3 assets.
4. Print Field Value of Selected Asset

To output a specific field (whether secret or not) of a chosen asset, use the following command:

Linux: 

./bin/apptool backup-field backup-file break-glass-key asset-id field-name

Windows: 

.\bin\apptool backup-field backup-file break-glass-key asset-id field-name

In the command above parameters are:

  • backup-file: Path to the backup file (can be absolute or relative).
  • break-glass-key: Break Glass Key from the original tenant.
  • asset-id: Asset ID from the previous command.
  • field-name: Name of the field (e.g., Host, User, or Password).

Example: To retrieve the Password field for asset ID 8f1256b1-f2a3-452f-a22c-8a89d4898469 from the backup file backup/TenantEcho/20250711-101251-full-001.zip, use the following command:

.\bin\apptool backup-field backup/TenantEcho/20250711-101251-full-001.zip wdaxx0DgXuLSoKgMQppDkdJ_SLNVodrhuMZaXTKUV_k 8f1256b1-f2a3-452f-a22c-8a89d4898469 Password

Example output:

Break Glass Asset Password Retrieval

Asset [Ubuntu 20.04] field [Password] values 
y&j7$Sf1u90rkNC1W5$sR5G

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 backup-field 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 defining the backup file location:

.\bin\apptool backup-field backup/TenantEcho/20250711-101251-full-001.zip - 8f1256b1-f2a3-452f-a22c-8a89d4898469 Password

Example output:

Break Glass Key Prompt with Password Retrieval

Break glass key:

Asset [Ubuntu 20.04] field [Password] values
y&j7$Sf1u90rkNC1W5$sR5G