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.
There are two types of backup data that Tableau Server can generate. We recommend performing regular backups of each type in case you must 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 initialized with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialized 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.
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
andtsmadmin
. 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
.Customization settings. If your organization uses custom header or sign-in logos for Tableau Server web pages, you should include a copy of those assets with your back up portfolio. See tsm customize.
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 initialize the new instance.
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.
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 initialized with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialized 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.
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 customizations: See tsm customize.
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.