Perform a Full Backup and Restore of Tableau Server

You can use the following steps to back up your Tableau Server deployment. Specifically, these steps describe how to recover a clone of a server from a collection of backup data and assets.

Note: The backup process can take a long time to run. Since no other jobs can be run while backup is running, we recommend that you run backup during non-business hours.

Backup data types

There are two types of backup data that Tableau Server can generate. We recommend performing regular backups of each type in case you need to restore a server in a recovery scenario:

Data managed by Tableau Server: consists of the Tableau PostgreSQL database or repository, and File Store, which contains workbook and user metadata, data extract files and site configuration data. When you use TSM to create a backup, all of this data is saved in a single file with a .tsbak extension. This data is backed up with the tsm maintenance backup command.
Note: When an external File Store is configured, you cannot use the tsm maintenance backup command to back up Tableau Server Data. For information on how to back up this data, see Backup and Restore with External File Store.
- You can only restore from a backup that has the same type of identity store as the running server. For example, a backup from a server using local authentication can be restored to a Tableau Server initialised with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialised with local authentication.
- You can only restore a backup file to a version of Tableau Server version that is the same or newer than the version the backup was created on. You cannot restore to an older version of Tableau.
- Important: If you perform Blue/Green upgrades or manually upgrade Tableau Server 2021.4 (or earlier) using the tsm maintenance (backup and restore) method, you must enable legacy-identity-mode before you can restore to Tableau Server 2022.1 (or later). For more information, see Troubleshoot Issues with the Identity Migration.
- Beginning with version 2022.3, backups created using tabadmin ("pre-TSM backups") are not supported. You cannot restore a pre-TSM backup to Tableau Server version 2022.3 or later.
Configuration and Topology data: includes most of the server configuration information required to fully recover a server. SMTP, alerting, some authentication assets, are all examples of configuration data that are exportable for backup. Topology data defines how your Tableau Server processes are configured in both single-server and multiple node deployments. Configuration and topology data is backed up with the tsm settings export command.

Note: You can change the file path used by the tsm maintenance backup command from the default value. For more information, see tsm File Paths.

Backup assets that require a manual process

Some configuration data is not included in the tsm settings export command and must therefore be documented and restored manually. The following configuration data is excluded from the tsm settings export operation. Your backup maintenance process should include documenting the following Tableau Server configuration data:

System user accounts. Tableau Server setup creates an unprivileged user account, tableau. This account is used to access Tableau Server resources. This account can be changed during setup. If you have not changed this account, then you do not need to document it.
TSM group membership. There are two groups created by Tableau Server: tableau and tsmadmin. If you configured alternative groups when you installed Tableau Server, then you'll need to document the group names.
In all cases, you should document the user accounts that are in these groups. To view membership in a group, run the following command grep <group_name> /etc/group.
Coordination Service deployment configuration. If you are running a multinode cluster, document which nodes are running the Coordination Services process. To view process configuration on your nodes, run tsm topology list-nodes -v.
Customisation settings. If your organisation uses custom header or sign-in logos for Tableau Server web pages, you should include a copy of those assets with your backup portfolio. See tsm customise.
Most authentication assets. While the locations for files may be included in an exported settings.json file, most certificate files, key files, keytab files or other authentication-related assets are not backed up by TSM. Verify that any of these assets you are trying to move won't need to be recreated.
There are three exceptions:
- The public certificate and private key for the internal PostgreSQL database (if enabled) are backed up.
- The certificate and key for external SSL are backed up and included in the configuration data.
- The custom certificate installed by tsm security custom-cert add (if added) is backed up.
However, all other authentication-related assets are not backed up. For example, if you have enabled access to the PostgreSQL database with the tsm data-access repository-access enable command, be sure to document the name/password pairs for each account you've configured. These credentials are not backed up. The certificate and key for mutual SSL are not included in the back up.
LDAP assets. Keytab files, configuration files, and or other LDAP-related assets are not backed up by TSM.

Internal server secrets and repository passwords are crypto-related configurations that are not exported. However, you do not need to document configuration values. New secrets will be created as part of the restoration process when you initialise the new instance.

Backing up Tableau Server for recovery

Tableau Server includes commands that you run to generate backup data for Tableau Server.

Note: When backing up Tableau Server on Linux, the unprivileged user must have write access to the network share where the backup files are written. Otherwise, backup will fail.

To back up server topology and configuration data, use the tsm settings command.

Topology and configuration data are included when you run the tsm settings export command. The data is exported as a json file. Specify the name and location of the json file by running the following command:
tsm settings export -f <filename>.json
Note: Because the backup contains secrets, we recommend that you encrypt the backup and store it in a secure place. For more information about Tableau Server secrets, see Manage Server Secrets.
Back up repository and File Store data. Repository data is backed up with the tsm maintenance backup command. Specify the name and location of the backup file by running the following command:
tsm maintenance backup -f <filename>.tsbak -d
The backup file is assembled in a temporary location in the data directory and then written to the directory defined in the TSM basefilepath.backuprestore variable:
/var/opt/tableau/tableau_server/data/tabsvc/files/backups/<filename>.tsbak
For more information about where backup files are written and how to change that location, see tsm File Paths. Note: Even when you change the backup location, the backup process uses a temporary location in the data directory to assemble the backup file.
Note: When File Store is configured external to Tableau Server you cannot use the tsm maintenance backup command to backup Tableau Server Data. For more information on how to backup this data, see Backup and Restore with External File Store.

Restoring core Tableau Server functionality

The procedure below uses the assets from the previous two sections to rebuild a Tableau Server in a recovery scenario.

Note: If you need to restore only the repository on an otherwise functional Tableau Server, see Restore from a Backup. If you are running a distributed deployment, and your initial node has failed, see Recover from an Initial Node Failure.

Topology and configuration backup data must be from Tableau Server on Linux. You cannot restore configuration data from a backup file that was generated on Tableau Server on Windows. To restore a backup made from Tableau Server on Windows to Tableau Server on Linux, see Migrate Tableau Server from Windows to Linux.

You must have the following assets ready:

Topology and configuration data: This is the json file that is generated by the tsm settings export command.
Repository backup file: This is the file with a .tsbak extension that is generated by the tsm maintenance backup command.
You can only restore from a backup that has the same type of identity store as the running server. For example, a backup from a server using local authentication can be restored to a Tableau Server initialised with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialised with local authentication.

When you use tsm maintenance restore to restore your Tableau data, data extract files and the contents of the PostgreSQL database are overwritten with the content in the backup file (.tsbak). If you are running a distributed installation of Tableau Server, perform the restore on the node running the TSM Controller (this is usually the initial node).
Backup assets: These assets include the list of documented configurations as noted in the previous section.

To restore a standalone Tableau Server

On the computer where you want to restore Tableau Server, Install and Initialise TSM. If your organisation used non-default system user accounts, as described in an early section of this topic, then you must specify the users during this step.
Activate and Register Tableau Server.
(Optional). Configure Local Firewall.
(Optional). Verify LDAP.
Initialise Tableau Server. See Configure Initial Node Settings.
Import topology and configuration data. Copy the topology and configuration json backup file to the computer. Import the json file by running the following command:
tsm settings import -f <filename>.json
(Optional). Apply pending changes. At a command prompt, run:
tsm pending-changes apply
Restart Tableau Server. At a command prompt, run:
tsm restart
Restore repository data. See Restore from a Backup.
(Optional). Repopulate TSM group membership. Add users to groups with this command:
sudo usermod -G <group_name> -a <username>

To restore a Tableau Server cluster

On the initial node, Install and Initialise TSM. If your organisation used non-default system user accounts, as described in an early section of this topic, then you must specify the users during this step.
On the initial node, Activate and Register Tableau Server.
(Optional). On the initial node, Configure Local Firewall.
On the initial node verify LDAP (optional), and initialise Tableau Server. See Configure Initial Node Settings.
On the initial node, run tsm topology nodes get-bootstrap-file --file <path\file>.json.
Copy the bootstrap.json file to all additional nodes in the cluster.
On each additional node in the cluster:

Install the Tableau Server package.
Navigate to the scripts directory.
Initiate communication between initial node and the additional node:
sudo ./initialize-tsm -b <path-to-bootstrap>.json -u <admin-user-on-first-node> --accepteula

On the initial node, run tsm topology list-nodes -v and ensure that the node names have not changed from exported topology settings. If the node names have changed, topology settings should be manually updated with new names, or the processes should be manually configured.
The Cluster Controller process is required on every node and needs to be added explicitly. From the initial node, add an instance of the Cluster Controller to each additional node, where <nodeID> is the ID of one of the additional nodes. Add the process to each node separately. In this example we are adding the Cluster Controller to nodes 2 and 3:
```
tsm topology set-process -n node2 -pr clustercontroller -c 1
tsm topology set-process -n node3 -pr clustercontroller -c 1
tsm pending-changes apply
```
From the initial node, Deploy a Coordination Service Ensemble. The ensemble configuration must match your previous configuration.
On the initial node, import topology and configuration data. Copy the topology and configuration json backup file to the computer. Import the json file by running the following command:
tsm settings import -f <filename>.json
On the initial node, apply pending changes. At a command prompt, run:
tsm pending-changes apply
On the initial node, restart Tableau Server. At a command prompt, run:
tsm restart
On the initial node, restore repository data. See Restore from a Backup.
On the initial node, repopulate TSM group membership. Add users to groups with this command:
sudo usermod -G <group_name> -a <username>

Restore other functionality

If the previous server was configured with the following features, then you will need to re-enable and reconfigure them on the restored server:

Authentication solutions: OpenID, external SSL, and trusted authentication. See Authentication.
Site customisations: See tsm customise.
Enable access to PostgreSQL repository: See tsm data-access repository-access enable.

Reencrypt Extracts After Restore

Optionally, if you are using the extract encryption at rest feature, after the backup is restored, you can reencrypt the extracts using different encryption keys. See Extract Encryption at Rest.

Run tabcmd reencryptextracts <site-name> to reencrypt extracts on a given site. For more information, see reencryptextracts. Run this command on every site where you are storing encrypted extracts. Depending on the number of encrypted extracts on the site, this operation could consume significant server processing load. Consider running this operation outside of business hours.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Linux Help