tsm maintenance


You can use the tsm maintenance commands to manage server maintenance tasks like creating backups or restoring Tableau Server from a previously created backup.

tsm maintenance backup

Creates a backup of the data managed by Tableau Server. This data includes the Tableau PostgreSQL database (the repository) which contains workbook and user metadata, and extract (.hyper files, and .tde files for versions 2024.2 and older) files. This data does not include configuration data. See Perform a Full Backup and Restore of Tableau Server.

Note: Do not use this command on Tableau Server installations with External File Store. See Backup and Restore with External File Store.

Optimizing with topology configurations:

  • Co-locating File Store on the same node as the Administration Controller can reduce the length of time it takes to back up Tableau Server by reducing or eliminating the need to transfer data between nodes during the backup process. This is especially true if your organization uses many extracts.
  • Co-locating the repository (pgsql) with the Administration Controller node can also help to reduce back up time, but the time savings is less significant than that of the File Store.

The Administration Controller is usually on the initial node, unless you have had an initial node failure and moved the controller to another node.

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. By default:

C:\ProgramData\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.

Synopsis

tsm maintenance backup --file <backup_file> [options] [global options]

Options

-f, --file <backup_file>

Required.

For more information about backing up the repository data, see Back up Tableau Server Data for more information.

-d, --append-date

Optional.

Append the current date to the end of the backup file name.

Note: Backups created using a schedule automatically include a date/time at the beginning of the backup file name. If you also use the -d option your file name will include the date twice. For more information about scheduling backups, see Scheduling and Managing Backups.

-i, --description <string>

Optional.

Include the specified description of the backup file.

--ignore-prompt

Optional. Added in version 2020.2.

Back up without prompting, even if the File Store is not on the same node as the Administration Controller (usually the initial node). Use this prompt if automating backups (for example, with scripts).

-k, --skip-verification

Optional.

Do not verify the integrity of the database backup.

--multithreaded

Optional. Added in version 2021.1

By default, a single thread is used when creating a Tableau Server backup. When this option is specified, a backup is created using multiple threads. Two threads are used by default, when this option is specified. You can change the number of threads used by setting the backup.zstd.thread_count configuration key.

--override-disk-space-check

Optional.

Attempt to create a backup even when there is a low disk space warning.

-po, --pg-only

Optional.

Generates only the repository backup.

Important: Do not use the pg-only option when generating a backup unless instructed by Tableau Support. This option will only back up the repository and cannot be used to restore your Server. Its primary use is for troubleshooting, and Tableau Support will ask you to create a --pg-only back up if this is necessary.

--request-timeout <timeout in seconds>

Optional.

Number of seconds to wait for the command to finish. Default value is 86400 (1440 minutes).

-sd, --schedule-days <day[,day]>

Optional. Added in version 2020.4.

Days on which to run the schedule. Use 1-7 for weekly schedule (1 for Monday, 7 for Sunday), 1-31 for monthly schedules (if a month does not include the specified day, the last day of the month is used). Separate multiple values with commas.

-si, --schedule-id <ID>

Optional. Added in version 2020.4.

Specify the ID of an existing schedule you want to update.

--skip-compression

Optional.

Create a backup without using compression. This results in a larger backup file but can reduce the amount of time it takes to complete the backup. If using this in a multi-node installation, we strongly recommend you have a File Store instance configured on your initial node.

-sn, --schedule-name <name>

Optional. Added in version 2020.4.

Specify the name for a schedule you are creating or updating.

-sr, --schedule-recurrence <frequency>

Optional. Added in version 2020.4.

Frequency of schedule recurrence. Valid options are "daily", " weekly", or "monthly".

-st, --schedule-time <HH:MM>

Optional. Added in version 2020.4.

The time a schedule should be run, in 24-hour format: HH:MM.

Examples

This example creates a backup called ts_backup-<yyyy-mm-dd>.tsbak in the C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\backups\ folder:

tsm maintenance backup -f ts_backup -d

This example creates a recurring weekly backup schedule named "weekly-saturday-backup" that runs every Saturday at noon and creates a backup called <yyyy.mm.dd.hh.mm>-ts_saturday_backup.tsbak:

tsm maintenance backup -f ts_saturday_backup -sr weekly -st 12:00 -sd 6 -sn weekly-saturday-backup

For more details on managing scheduled backups, see Scheduling and Managing Backups.

tsm maintenance cleanup

By default the tsm maintenance cleanup command deletes temporary files and log files older than one day. Command options can modify retention length and which files are deleted.

The impact of this command depends on whether Tableau Server is running.

  • If the server is running, most old files and http_requests table entries can be deleted, but any files in use (locked by the operating system) cannot be deleted, so temporary files and active log files are not removed. To delete temporary files and current log files, you must stop the server before running this command. To delete http_requests table entries, use the -q option.
  • If the server is stopped http_requests entries cannot be deleted.

If you are running Tableau Server on a distributed deployment, run this command on the node that is running the Administration Controller (also referred to as the TSM Controller) process. By default and in most cases, the controller is on the initial node in the cluster.

Synopsis

tsm maintenance cleanup [options] [global options]

Options

-a, --all

Optional.

Perform all cleanup operations with default retention values. Equivalent to running the cleanup command with the following options: -l -t -r -q -ic.

--http-requests-table-retention <# of days>

Optional.

Default: 7 days

Specify the number of days of http_requests table entries that should be retained. Use this option with the -q option to specify the number of days of table entries to retain, overriding the default of 7 days. This option specifies table entry retention age but does not trigger actual deletion of table entries. Use this together with the -q option, which triggers deletion of entries.

-ic, --sheet-image-cache

Optional. Added in version 2019.4.

Clear the image cache. This cache can contain images for offline previews, snapshots for subscription email messages, and subscription pdfs, as well as any images requested from the publish rest API endpoint (see rest_api_ref.htm(Link opens in a new window) for more information).

-l, --log-files

Optional.

Delete log files that are older than 1 day. Files in the subdirectories under data\tabsvc\logs will be deleted.

--log-files-retention <# of days>

Optional.

Default: 1 (24 hours)

Delete logs older than this number of days. Use this to override the default retention period of 1 day. This command does not apply to temporary files.

-q, --http-requests-table

Optional.

Delete old http_requests table entries. Tableau Server must be running for table entries to be deleted. This option is ignored if Tableau Server is stopped. This option can be used alone to specify deletion of entries older than the default retention period (7 days), or together with the --http-requests-table-retention to specify a non-default retention period.

Note: Deleting http_requests table entries permanently removes data that is available to custom administrative views. Be sure removing this data will not impact any custom views you need.

-r, --redis-cache

Optional.

Clear the Redis cache.

--request-timeout <timeout in seconds>

Optional.

Default: 3600

Wait the specified amount of time for the command to finish.

-t, --temp-files

Optional.

Delete all files and subdirectories in the following directories:

  • <install dir>\ProgramData\Tableau\Tableau Server\data\tabsvc\temp: To delete files under each Tableau Server process directory, you must stop Tableau Server before running the command. If you execute the command while Tableau Server is running, only directories storing files for expired (not running) sessions are deleted.

  • <install dir>\ProgramData\Tableau\Tableau Server\data\tabsvc\httpd\temp

  • <install dir>\ProgramData\Tableau\Tableau Server\temp

Examples

This example cleans up all log files older than 2 days old:

tsm maintenance cleanup -l --log-files-retention 2

tsm maintenance jmx disable

Version: Command added in version 2022.1.

Use the tsm maintenance jmx disable command to disable JMX on Tableau Server.

Running this command requires a restart of Tableau Server, including TSM services.

Synopsis

tsm maintenance jmx disable [options] [global options]

Options

--ignore-prompt

Optional.

Disable JMX without prompting.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance jmx enable

Version: Command added in version 2022.1.

Use the tsm maintenance jmx enable command to enable JMX on Tableau Server.

This command is interactive, prompting you for applicable options if you don't provide them as command line parameters.

This command requires a restart of Tableau Server, including TSM services.

Synopsis

tsm maintenance jmx enable

Options

--access <readonly | readwrite>

Optional.

Enable JMX with either readonly or readwrite access. Default is readonly.

--ignore-prompt

Optional.

Enable JMX without prompting for additional security options. This enables JMX with SSL and restarts Tableau Server if you do not include any other command options. For example:

tsm maintenance jmx enable --ignore-prompt

--no-ssl

Optional.

Enable JMX without SSL.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

--ssl-client-auth

Optional.

Enable JMX requiring client auth for SSL.

--unsecured

Optional.

Enable JMX with no security features enabled (this is not recommended). This is the equivalent of setting the service.jmx_enabled configuration key to true in pre-2022.1 versions.

tsm maintenance metadata-services disable

Version: Command added in version 2019.3.

Use the tsm maintenance metadata-services disable command to disable the Tableau Metadata API.

Disabling the Metadata API stops continuous ingestion and indexing of information about the content on Tableau Server, deletes the index of information about the content published to Tableau Server and assets associated with that content, and disables the ability to both query the Metadata API and access Tableau Catalog.

Running this command stops and starts some services used by Tableau Server, which causes certain functionality, such as Recommendations, to be temporarily unavailable to your users.

Synopsis

tsm maintenance metadata-services disable

Option

--ignore-prompt

Optional.

Dismiss the confirmation prompt when disabling the Metadata API.

tsm maintenance metadata-services enable

Version: Command added in version 2019.3.

Use the tsm maintenance metadata-services enable command to enable the Tableau Metadata API for Tableau Server.

If Tableau Server is licensed with the Data Management, enabling the Metadata API enables Tableau Catalog.

When enabling the Metadata API, information about the content on Tableau Server is ingested and then indexed to the Metadata API Store. The Metadata API can be used to query schema, lineage, and user managed metadata about the content published to Tableau Server. After the Metadata API is enabled, metadata is continuously ingested and indexed until the Metadata API is disabled.

When running this command, keep the following in mind:

  • This command stops and starts some services used by Tableau Server, which causes certain functionality, such as Recommendations, to be temporarily unavailable to your users.
  • A new index of metadata is created and replaces the previous index every time this command is used.

For more information about the Tableau Catalog, see, About Tableau Catalog.

Synopsis

tsm maintenance metadata-services enable

Option

--ignore-prompt

Optional.

Dismiss the confirmation prompt when enabling the Metadata API.

tsm maintenance metadata-services get-status

Version: Command added in version 2019.3.

Use the tsm maintenance metadata-services get-status command to get status information on Metadata Services.

Status on Metadata Services indicates if the Metadata API Store has been initialized or if the Tableau Metadata API is running or not.

Synopsis

tsm maintenance metadata-services get-status

tsm maintenance preflight-check permissions

Version: Command added for Tableau Server on Windows in version 2020.3.

Use the tsm maintenance preflight-check permissions command to verify the directory permissions.

Synopsis

tsm maintenance preflight-check permissions [options] [global options]

Option

-d, --data-dir <data directory>

Optional.

Specifies the data directory on which to verify permissions. If not included, the data directory is determined based on the current Tableau Server configuration.

-i, --install-dir <install directory>

Optional.

Specifies the install directory on which to verify permissions. If not included, the install directory is determined based on the current Tableau Server configuration.

-n --nodes <nodeID,nodeID,...>

Optional.

Node IDs of nodes to specifically include in the permissions check. If not specified, the check is performed on all nodes in the cluster.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

-ru --runas-user <timeout in seconds>

Optional.

The Run As user name to verify permissions for. If not provided, the Run As user is determined from the current configuration.

tsm maintenance preflight-check ports

Version: Command added for Tableau Server on Windows in version 2020.3.

Use the tsm maintenance preflight-check ports command to verify that ports are available for all currently installed services. Specify a service and port to verify the port is available for that service, even if the service is not currently installed.

Synopsis

tsm maintenance preflight-check ports [options] [global options]

Option

-a, --tabadminagent-addresses <hostname:port>

Optional.

Specifies the host and port on which to check for access to the Administration Agent. Addresses are formatted as hostname:port. Separate multiple addresses by commas if more than one is being checked. Use this option to see if a port is available before installing or changing ports.

-g, --gateway-addresses <hostname:port>

Optional.

Specifies the host and port on which to check for access for the Gateway service. Addresses are formatted as hostname:port. Separate multiple addresses by commas if more than one is being checked. Use this option to see if a port is available before installing or changing ports.

-n --nodes <nodeID,nodeID,...>

Optional.

Node IDs of nodes to run preflight check on. If not specified, the checks are performed on all nodes in the cluster.

-r, --repository-addresses <hostname:port>

Optional.

Specifies the host and port on which to check for access for the Repository service. Addresses are formatted as hostname:port. Separate multiple addresses by commas if more than one is being checked. Use this option to see if a port is available before installing or changing ports.

-re --remote

Optional.

Checks remote access to the Administration Agent from all nodes. This is not done by default.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

-t, --tabadmincontroller-addresses <hostname:port>

Optional.

Specifies the host and port on which to check for access for the Administration Controller. Addresses are formatted as hostname:port. Separate multiple addresses by commas if more than one is being checked. Use this option to see if a port is available before installing or changing ports.

tsm maintenance reindex-search

Use the tsm maintenance reindex-search command to rebuild the search index.

Synopsis

tsm maintenance reindex-search [options] [global options]

Option

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance reset-searchserver

Version: This command was retired (removed) in 2023.3.0 when Search and Browse (also called Search Server) was retired. Search and Browse has been replaced by Index and Search Server.

Note: Running this command on version 2023.3.0 or later will not do anything.

Resets the search server to a clean state, deleting search information and rebuilding the search index.

Synopsis

tsm maintenance reset-searchserver [options] [global options]

Option

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance restore

Restore Tableau Server using the specified backup file. Restoring a backup file does not restore any configuration data. See Perform a Full Backup and Restore of Tableau Server.

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.

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.

Synopsis

tsm maintenance restore --file <file_name> [--restart-server] [global options]

Options

-f, --file <file_name>

Required.

Specifies the backup file to restore from.

The restore command expects a backup file in the directory defined in the TSM basefilepath.backuprestore variable. By default:

C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\backups\

For more information about file paths and how to change them, see tsm File Paths.

-ak, --asset-key-file <file_name>

Optional. Deprecated in version 2021.4.0.

Specify this option only if you are restoring from assets that were created by tabadmin on Tableau Server (versions 2018.1 and earlier).

Name of asset key file to restore from. The asset key file is created by the tabadmin assetkeys command. The file must be in the predefined backup/restore location on the server.

-k, --skip-identity-store-verification

Optional. Specify this option only if you are restoring from a backup file that was created by tabadmin on Tableau Server (versions 2018.1 and earlier).

Do not use this key in an attempt to change identity store type from Tableau Server that created original backup file. To change the identity store, see Changing the Identity Store .

-po, --pg-only

Optional.

Restores only the repository.

-r, --restart-server

Optional.

Restart the server after the restore.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance send-logs

Upload the specified file to Tableau and associate it with a support case. To successfully upload files to Tableau, your Tableau Server must be able to communicate with the send-logs server at https://report-issue.tableau.com.

Synopsis

tsm maintenance send-logs --case <case_number> --email <contact_email> --file <path/to/file> [global options]

Options

-c,--case <case_number>

Required.

Support case number.

-e,--email <contact_email>

Required.

Contact email.

-f, --file <path/to/file>

Required.

Specifies the location and name of the log file archive to send.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance snapshot-backup complete

Version: Command added in version 2020.1 and only available when Tableau Server is configured for External File Store.

Complete the snapshot backup process on Tableau Server. Run this after you have taken a snapshot backup of your external storage.

The tsm maintenance snapshot-backup prepare and the tsm maintenace snapshot-backup complete commands are used to create a backup of Tableau Server data for Tableau Server installations that are configured with External File Store. For more information, see Backup and Restore with External File Store

Synopsis

tsm maintenance snapshot-backup complete [options] [global options]

Options

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance snapshot-backup prepare

Version: Command added in version 2020.1 and only available when Tableau Server is configured for External File Store.

Prepares for snapshot backup. Once the preparation step is complete, you may take a snapshot backup of your network storage.

The tsm maintenance snapshot-backup prepare and the tsm maintenace snapshot-backup complete commands are used to create a backup of Tableau Server data for Tableau Server installations that are configured with External File Store. For more information, see Backup and Restore with External File Store

Synopsis

tsm maintenance snapshot-backup prepare [options] [global options]

Options

--include-pg-backup

Optional. Added in version 2021.1. Prior versions always included a backup of the External Repository.

Optional.

A backup of the Repository is made and copied to the network share. This is only applicable to deployments where both External Repository and External File Store are configured. For more information, see Backup and Restore with External File Store.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance snapshot-backup restore

Version: Command added in version 2020.1 and only available when Tableau Server is configured for External File Store.

Restores the repository backup from the storage snapshot to Tableau Server.

For more information, see Backup and Restore with External File Store.

Synopsis

tsm maintenance snapshot-backup restore [options] [global options]

Options

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance validate-backup-basefilepath

Version: Command added in version 2022.1.

Validate that the backup/restore base filepath location has correct permissions to allow backup and restore functions to work properly. Run this after setting the basefilepath for backup and restore. For more information, see Change the current file location .

Synopsis

tsm maintenance validate-backup-basefilepath [options][global options]

Options

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance validate-resources

Validate workbooks and data sources for a site. Use this command before migrating a site, to detect issues with site resources such as workbooks and data sources that will cause a site import to fail. Some resource problems can be corrected by republishing from local sources. Other problems might require assistance from Tableau Support.

Synopsis

tsm maintenance validate-resources --site-id <site ID> [global options]

Options

-id,--site-id <site ID>

Required.

ID for the site whose resources you are validating.

-r,--repair

Optional.

Attempt to repair invalid resources. Those that cannot be repaired are noted in output.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish.

tsm maintenance ziplogs

Use the ziplogs command to create an archive of Tableau Server log files.

Synopsis

tsm maintenance ziplogs [options] [global options]

Options

-a, --all

Optional.

Includes msinfo, netstat, and latest dump. Equivalent of running the command with these options: -mi -t -l. Does not include PostgreSQL data.

-d, --with-postgresql-data

Optional.

Include the PostgreSQL data folder if Tableau Server is stopped or PostgreSQL dump files if Tableau Server is running. This flag is ignored for deployments running with a Tableau Server External Repository.

--enddate "<mm/dd/yyyy H:mm>"

Optional. Time option (H:mm) added in version 2021.4.0.

The last date of log files to be included. This option must be used with --startdate and cannot be used with --minimumdate. If this option is not specified, up to two days of logs will be included, starting at 00:00 GMT.

If you include the time option you must use quotes around date and time. The time option uses GMT, however, the resulting log files will be written using the local time zone of the Tableau Server machine.

Example: If the local time zone of the Tableau Server machine is PDT and you want the log files to begin at 7am PDT and end at 7pm PDT on 07/28/2022, use the following:

tsm maintenance ziplogs -f logs.zip --startdate "07/28/2022 14:00" --enddate "07/29/2022 02:00"

-f, --file <name>

Optional.

Specify a name for the zipped archive file. If no name is provided the archive is created as logs.zip. The file is written to the directory defined in the TSM basefilepath.log_archive variable. By default:

C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\log-archives\

For more information about file paths and how to change them, see tsm File Paths.

-i, --description <string>

Optional.

Include the specified description of the archive file.

-l, --with-latest-dump

Optional.

When any service crashes, Tableau Server generates a dumpfile. Set this option to include the most recent service crash dumpfile.If you do not set this option, then no dumpfile will be included in the resulting ziplog.

-m, --minimumdate <mm/dd/yyyy>

Optional.

Earliest date of log files to be included. If not specified, a maximum of two days of log files are included. Format of date should be "mm/dd/yyyy". This option cannot be used with --startdate and --enddate or --all.

-mi, --with-msinfo

Optional.

Include the msinfo32 report, with system information about OS, hardware, and running software.

--nodes

Optional. Added in version 2020.3.

Specify the nodes for which to create a ziplog file. If not specified, ziplog files are created for all nodes and saved to the initial node. Separate nodes with a comma. For example, to gather logs for nodes 2 and 4:

tsm maintenance ziplogs --nodes node2,node4

-o, --overwrite

Optional.

For an overwrite of an existing ziplog file. If a file by the same name already exists and this option is not used, the ziplogs command will fail.

By default the file is written to:

C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\log-archives\

For more information about file paths and how to change them, see tsm File Paths.

--request-timeout <seconds>

Optional.

Number of seconds to wait for the command to finish. Default value is 7200 (120 minutes).

--startdate "<mm/dd/yyyy H:mm>"

Optional. Time option (H:mm) added in version 2021.4.0.

The last date of log files to be included. This option must be used with --enddate and cannot be used with --minimumdate. If this option is not specified, up to two days of logs will be included, starting at 00:00 GMT.

If you include the time option you must use quotes around date and time. The time option uses GMT, however, the resulting log files will be written using the local time zone of the Tableau Server machine.

Example: If the local time zone of the Tableau Server machine is PDT and you want the log files to begin at 7am PDT and end at 7pm PDT on 07/28/2022, use the following:

tsm maintenance ziplogs -f logs.zip --startdate "07/28/2022 14:00" --enddate "07/29/2022 02:00"

-t, --with-netstat-info

Optional.

Include netstat information.

 

Global options

-h, --help

Optional.

Show the command help.

-p, --password <password>

Required, along with -u or --username if no session is active.

Specify the password for the user specified in -u or --username.

If the password includes spaces or special characters, enclose it in quotes:

--password "my password"

-s, --server https://<hostname>:8850

Optional.

Use the specified address for Tableau Services Manager. The URL must start with https, include port 8850, and use the server name not the IP address. For example https://<tsm_hostname>:8850. If no server is specified, https://<localhost | dnsname>:8850 is assumed.

--trust-admin-controller-cert

Optional.

Use this flag to trust the self-signed certificate on the TSM controller. For more information about certificate trust and CLI connections, see Connecting TSM clients.

-u, --username <user>

Required if no session is active, along with -p or --password.

Specify a user account. If you do not include this option, the command is run using credentials you signed in with.

 

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!