Skip to content
You're viewing documentation for v2026.11.7-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview
On this page

Restore the console

Restore the console from a console backup, on a new host after the loss of the console host or in place, and check the servers and services.

A restore returns the console to the state of a console backup. Servers keep their mesh identities and overlay addresses. Database services do not roll back.

Case How
The console host is lost, or the console does not start Restore on a new host with the installer. The same steps restore over a damaged console on the same host.
The console runs, and you want an earlier state Restore in place in the console

While the console is down, a server that restarts cannot join the mesh (see Console outage). Restore the console soon.

Be ready before a failure

  • Set up console backups with an S3 target off the console host. Keep the recovery key file off the console host too. Without it, nobody can open a backup.
  • Use a DNS name in TSE_PUBLIC_URL. A restore on a new host is then a DNS change.
  • Keep a standby Linux host with Docker outside the failure domain of your services (see Requirements). On an airgapped site, keep the airgapped package of the console release on it.

What you need

  • The backup: the newest .tse file of this console (tse-console-<console>-<time>-<release>.tse), as a local file. While the console runs, select Download on it in Administration → Console backups. Else get it from the backup directory (TSE_BACKUP_DIR) or from the S3 bucket.
  • The recovery key file of the backup (tse-recovery-key-<console>-<date>.txt). After a key rotation, an older backup needs the older key file.
  • The installer of the release of the backup, or of a newer release.

Restore on a new host

Stop the old console

The old console must never run again: two consoles with the same mesh keys both claim the servers. Power off the old host, and prevent its start or its connection to the servers. Or select Uninstall in the installer menu on the old host (see Uninstall). Uninstall removes the console volumes and .env.

If you cannot keep the old console isolated, stop here.

For a restore over a damaged console on the same host, skip this step.

Copy the files to the new host

Copy the backup file and the key file to the new host. Make the key file readable only by you (chmod 600).

Select Restore the console from a backup

On the new host, run the installer:

curl -fsSL https://enterprise.tigerdata.com/install/timescale-enterprise.sh | sh

From a bundle, run ./timescale-enterprise.sh in the bundle directory. In the menu, select Restore the console from a backup. At Console backup file:, enter the path of the .tse file.

To restore without the menu, add --restore FILE after sh -s -- (or after ./timescale-enterprise.sh). Add --offline on a host with no internet access. To use an install directory other than /opt/tse, add --dir (see Install directory).

Give the recovery key file

At Recovery key file:, enter the path of the key file. With no terminal, set TSE_INSTALL_RESTORE_KEY_FILE to the path.

Check the summary

The Console backup box shows the backup time (Created), the release, the console, the tiers, and the number of servers and services.

The Console backup summary of the installer during a restoreThe Console backup summary of the installer during a restore

The installer stops and changes nothing when:

  • the key does not open the backup;
  • a file of the backup is changed or missing;
  • the backup is of a newer release than the installer;
  • the backup is of a demo and you did not add --demo (on the host of its demo servers), or the reverse.

Correct the cause and run the installer again.

Keep or change the server-facing URL

At URL [<URL of the backup>]:, press Enter to keep the URL, or enter a new URL. With no terminal, TSE_INSTALL_PUBLIC_URL sets a new URL. See The console address for what each choice needs.

Let the installer check for the old console

If the old console answers at <URL of the backup>/api/v1/info, the installer stops. Stop the old console first. Add --force to skip this check only when you are sure that the old console cannot run again.

Wait for the console

On a new host, the installer asks for the backup directory (TSE_BACKUP_DIR). Over a console on this host, it first backs up that console to <TSE_BACKUP_DIR>/pre-restore/. If that backup fails, it starts that console again and stops (for a damaged console, see Console outage, step 5). At the end, it shows After the restore.

If the installer stops, run it again. It continues the restore.

Log in

Make the changes in The console address, then log in with the users, single sign-on and TSE_AUTH_TOKEN of the backup. Complete After the restore before other changes.

The console address

Each server finds the console at the host of TSE_PUBLIC_URL, on port 8090.

Case What happens What you do
Restore in place, on the same host Nothing changes. Nothing.
New host, TSE_PUBLIC_URL is a DNS name The servers connect again about one minute after the DNS change. Point the DNS record to the new host. Open 8090/tcp, 41641/udp, 3478/udp and the console ports to the new host.
New host with the IP address of the old host As for a DNS name. Move the address to the new host.
New host with a new IP address, and TSE_PUBLIC_URL is an IP address The servers cannot reach the console. Keep the old address on the new host (a second address, or a forward of 8090/tcp, 41641/udp and 3478/udp). Or set a new URL and run Re-enroll command on each server.

For a new URL, follow the server steps in Change IP addresses. The installer already set the URL: skip the URL change and restart there.

When the host name changes, a certificate in ./certs (provided mode) must have the new name. A single sign-on provider must accept the new redirect URL.

What a restore rolls back

Change after the backup After the restore What you do
A server enrolled Unknown to the console and the mesh. Its mesh traffic stops. Enroll it again. A member of a service waits for Replace a server.
A server enrolled again with a new mesh key The mesh has the old key. Run Re-enroll command on the server again.
A service was created It runs, but the console cannot manage it. Contact Tiger Data support. Back up after changes keeps this window short.
A service or a server was deleted The console shows it again. Its operations fail. Delete it again.
A password, a setting or a license changed The console has the old value. Make the change again. Install the license file again.
A console backup target, schedule or recovery key changed The console has the old values. Make the change again.

After any restore, every user logs in again. An operation that was running at the time of the backup shows as interrupted. Check the real state of the service before you run it again.

After the restore

Admins see the banner Restored from the backup of time. Select Open the checklist to open the After the restore card. The card lists unhealthy services and missing server packages. Dismiss removes the banner and the card for all admins.

Test each server

In the card, select Test each server. A server enrolled after the backup does not show or answer.

Check each service

On the Overview of each service, check that it is healthy. If not, use the matching runbook.

Load the missing packages

In Administration → Server packages, load the missing packages with Upload server packages, or with --pack (see Load server packages). A backup without the Server packages tier has none.

Check the console backups

In Administration → Console backups, check the targets, schedules and recovery key. Make a backup and wait for its check to pass.

Make the later changes again

Make the changes from after the backup again.

Restore in place

You must be an admin. The console must have a confirmed recovery key: the restore first backs up the current state to it.

Select the archive

Open Administration → Console backups. In the Backups card, select Restore on an archive. Or select Restore from a file, and upload a .tse file of this console.

Paste the recovery key

In Recovery key, paste the key file or its AGE-SECRET-KEY-1... line. For an archive on a target, the dialog names the fingerprint of the key it needs.

Check the archive

Select Check the archive. The console does not keep the key.

Read the summary

Read the summary and the table of what the restore rolls back. If the check fails, do not continue.

The restore panel after Check the archive, with the summary of the backupThe restore panel after Check the archive, with the summary of the backup

Restore the console

Type the name of this console, and select Restore the console.

The dialog shows The console is backing up its current state…, then The console is staging the archive…, then The console is restarting. Log in again when it is back. The current state goes to <TSE_BACKUP_DIR>/pre-restore/ (the newest 3 archives stay). If that backup fails, the restore stops and nothing changes.

The restart takes one to two minutes. The UI and the API are down. When the console is back, log in and complete After the restore. If it does not come back, follow Console outage.

Restore shows only on an archive of this console that is on its target and did not fail its latest check. The console refuses a restore in place:

  • while an operation, a backup, an upload or another restore is running;
  • of an archive of another console, of a newer release, or of a demo into a production console (or the reverse);
  • when the archive has another TSE_DB_ENCRYPTION_KEY or TSE_MESH_SUBNET than .env. Use Restore on a new host on this host instead;
  • when the archive does not match its sidecar (size or SHA-256). Run Check on it, or restore another archive.

To undo a restore in place, copy the archive from <TSE_BACKUP_DIR>/pre-restore/ to your computer. Restore it with Restore from a file and the recovery key that opens it. Then complete After the restore.