Tableau Server on Windows Help

Comparing Functionality of tabadmin and TSM

Version: 2019.2

The 2018.2 version of Tableau Server on Windows includes an updated management tool set called Tableau Services Manager (TSM), which replaces the legacy tabadmin CLI and GUI tool sets. Most of the functionality that was included with the legacy tool sets has been ported to TSM. The following list describes legacy functionality that has either not been ported directly or is no longer implemented in Tableau Server.

Note: Looking for tabadmin or Configuration Utility content for older versions of Tableau Server on Windows? See the archived online help on the Tableau Help page.

TSM is used to manage server-level configurations of Tableau Server. Access to TSM is available with a command-line interface (CLI) or a web interface. It replaces the following tools from previous versions of Tableau Server:

Tableau Server Configuration utility

tabadmin command-line utility

Tableau Server Monitor

As a shorthand, this topic refers to these legacy tools as "tabadmin." In previous versions of Tableau Server on Windows, for example, you used tabadmin to perform the following tasks that are now performed with TSM:

Features only available from the TSM command line

The features and functionality described in this section were previously available in the Tableau Server Configuration utility. The features and functionality below are not exposed in the TSM web UI and must therefore be configured with the TSM CLI.

Preferred active repository

The Tableau Server Configuration utility had an option to set the preferred active repository. With TSM you need to do this using the CLI command tsm configuration set -k pgsql.preferred_host. For more information, see "Preferred active repository" in Tableau Server Repository.

Data cache configuration

In previous versions, the Tableau Server Configuration utility provided a graphical UI to configure data caching. In the TSM version of Tableau Server, you must configure caching with the TSM CLI. See Configure Data Cache.

Initial install-only settings

In previous versions, the Tableau Server Configuration utility provided a graphical UI to change the gateway port and to install samples, even after installation. With TSM, you can still specify these options in the Web UI during installation, but after install is complete, you can only change them with command-line tools.

Initial SQL

In previous versions of Tableau Server, you could configure server to ignore initial SQL statements by selecting the Ignore initial SQL statements for all data sources option on the Data Connections tab of the Tableau Server Configuration utility. This configuration option is not included in the TSM Web UI. To configure server to ignore initial SQL statements, use the tsm configuration set command:

tsm configuration set -k vizqlserver.initialsql.disabled -v true

Site SAML

While the core SAML configuration options are included in the TSM web UI, to configure site SAML, you must use the TSM CLI. See Configure Site-Specific SAML.

SAP HANA SSO

Rebuilding the Search Index

In Tableau Server versions prior to 2018.2, the Status page in Tableau Server included an option to rebuild the Search & Browse index. This was not the recommended way to rebuild the index, and the option has been removed beginning with 2018.2. Instead, use the TSM maintenance reindex-search command. For details, see tsm maintenance reindex-search.

Differences in functionality

This section describes the difference of functionality in TSM implementation as compared to the admin experience in the legacy tabadmin versions of Tableau Server on Windows.

Host name configuration

With TSM you cannot change the hostname after Tableau Server has been installed.

Archive logs requires local administrator privilege

In the legacy tabadmin versions of Tableau Server, site admins could generate archive log snapshots from the Tableau Server Admin Pages. In the TSM version of Tableau Server, the log snapshot functionality is restricted to administrators with TSM access. The account running TSM web UI or CLI must be a member of the local administrators group on the Windows computer running Tableau Server. See Log File Snapshots (Archive Logs).

Windows Firewall configuration

Setup no longer attempts to configure the Windows Firewall. Before you install Tableau Server, verify that the appropriate ports are open on the local firewall. See Local firewall configuration.

Backup and restore processes write and read files to and from fixed locations. Unlike with Tableau Server 2018.1 and earlier, you cannot specify a file location when you run the command. For more information, see Fixed file locations below.

Asset keys

Asset keys are now included with backup files. If you are restoring a backup where you included regenerated asset keys in legacy tabadmin, then you'll need to import that .yml file as part of the TSM restore process. See Perform a Full Backup and Restore of Tableau Server.

Configuration import and export

In the legacy tabadmin versions of Tableau Server, configuration and topology information was managed as part of the backup and restore process. With the introduction of TSM, you can now export and import your configuration and topology information using the tsm settings commands.

Kerberos configuration

In the legacy versions of Tableau Server, the Tableau Server Configuration utility included an option on the Kerberos tab that generated a configuration bat script for your domain admin to run. This script set service principal names and created keytab files for the Run As service account. In the TSM version of Tableau Server, we have documented this bat script so you can prepare it for your admin. See Understanding Keytab Requirements.

File storage

In the TSM version of Tableau Server, a new process called client file service (CFS) handles distributing files in a multi-node deployment. You must use TSM CLI or web interface to upload files that are managed by CFS. See Tableau Server Processes.

TSM is a batch file

TSM is a batch file. When you run TSM commands at the command line, you are invoking a batch file (TSM.cmd). This means that if you are scripting or automating server maintenance or configuration in a batch file, you need to use the call command (for example, call tsm maintenance ziplogs) so that control is returned to the batch file.

You need to authenticate to use TSM

Unlike with tabadmin, where you could only run commands on the local computer where Tableau was installed, TSM allows you to run commands remotely, either from the Web UI or the CLI. This flexibility means that you need to sign in to TSM before running any commands. To sign in to the Web UI, open the TSM web page: https://<tsm_computer>:8850 and sign in when prompted. To sign in to the CLI, use the tsm login command.

Cleanup and clear cache

In the TSM version of Tableau Server, clearing the cache, and other optional clean up operations are included in the tsm maintenance cleanup command.

Uninstall and remove Tableau Server

In the legacy tabadmin versions of Tableau Server, you uninstall using Windows Control Panel, and the uninstall process leaves behind files and other Tableau Server configurations.

With TSM, uninstalling Tableau Server differs in these ways:

You should not uninstall Tableau Server while upgrading from a TSM version (2018.2.x or later) to a TSM version. After the upgrade is complete, you can uninstall your previous version using Windows Control Panel.

Do not use Windows Control Panel to uninstall Tableau Server if your install or upgrade attempt fails. In these situations, use the tableau-server-obliterate script described below to completely remove Tableau Server from your computer.

Using Windows Control Panel to uninstall Tableau Server does not create a backup of your data. You should create a backup using the tsm maintenance backup command and save the backup file to a safe location on a computer that is not part of your Tableau installation.

To completely remove Tableau Server, use the tableau-server-obliterate.bat script. This removes all Tableau Server files and configurations. As a best practice, you should restart the computer after running the obliterate script.

Tableau Server installation directory

In TSM installation, the default installation location is \Program Files\Tableau\Tableau Server\packages\ with a versioned subfolder for each process or service. For example: C:\Program Files\Tableau\Tableau Server\packages\bin.20182.18.1214.0751

Fixed file locations

In tabadmin you could specify a file location for files generated or used by commands such as backup, restore, and ziplogs. With TSM you cannot specify the location when running the equivalent command, but you can set the fixed file location before running the command by using a basefilepath variable. For details on which commands read from or write to a fixed file location, and how to change that location, see tsm File Paths.

Log file snapshots

The location you go to generate a log file snapshot has changed with TSM. With versions of Tableau Server on Windows prior to 2018.2, you could generate a log file snapshot and download it from the Status page of Tableau Server. With TSM you do this on the TSM Maintenance page. New in TSM is the ability to upload a log file snapshot directly to Tableau Support. For more information on how these two features work in TSM, see Log File Snapshots (Archive Logs).

Changes in high availability and distributed deployments

With TSM, we've changed the language we use to describe the Tableau Server nodes in a distributed installation. Prior to the release of TSM we referred to the first node as the "primary" node, and any additional nodes as "worker" nodes. With TSM the nodes are more similar to each other than in prior releases, so we refer to the first node as the "initial" node, and other nodes as "additional" nodes. The initial node includes some TSM-specific processes that are not installed on additional nodes, including the TSM Controller and the License Server. Tableau includes a script to move these key processes over to another node in your installation if a problem occurs on the initial node. For details, see Recover from an Initial Node Failure.

The installation process for distributed deployments has also changed.

Common installer file—In version 2018.1 and earlier, deployments required two separate installers. With 2018.2 and TSM, you run the same installer for all nodes and indicate if you are installing on the initial node or additional nodes.

No auto-discovery of nodes—With versions of Tableau Server prior to 2018.2, once you installed all nodes, you ran the Server Configuration utility and added worker nodes to the primary. With TSM, after installing the initial node, you generate a bootstrap configuration file and use this when you install all additional nodes. For more information about installing a multi-node cluster, see Distributed and High Availability Tableau Server Installations.

Coordination Service installation—When you configure a multi-node installation of Tableau Server you need to also deploy a Coordination Service ensemble to your additional nodes. In versions of Tableau Server on Windows prior to 2018.2, additional instances of the Coordination Service were automatically added as you added a total of three or five nodes. Now you need to manually deploy the Coordination Service. For more information on how to do this, see Deploy a Coordination Service Ensemble .

No "backup primary"—There is no longer a need for a "backup primary" node, and TSM does not support creating a backup for the initial node. With TSM, if your initial node encounters a problem, you move the key processes from that node to another of your cluster nodes using a script. For more information on how to do this, see Recover from an Initial Node Failure.

Upgrade process changes

Your upgrade steps depend on which version you are upgrading from. Upgrading from legacy tabadmin Tableau Server (2018.1.x or earlier) to a TSM version (2018.2 or later), requires special steps.

- Upgrading from version 2018.2 or later: If you are upgrading from Tableau Server on Windows version 2018.2 or later, read Upgrade Tableau Server. Do not follow the steps for a pre-TSM to TSM upgrade.

Below are key aspects of upgrading Tableau Server from version 2018.1 or earlier to version 2018.2 that you need to be aware of.

All upgrades:

Local administrator—Sign in as a local administrator. You need to be signed into the Tableau Server computer as a "local admin" to run the Tableau Server Setup program, and to run scripts related to upgrading. A "local admin" is a user who's a member of the Administrators group in the Local Users and Groups management console in Windows.

Local security policy—Verify that your local security policy will allow "log on as a service" and "log on locally" permissions for the Run As service account. For details, see Verify the Local Security Policy.

Licenses—

Trial product keys—You cannot directly upgrade a server that is running a trial product key from one major version to another (for example, from version 10.5.x to version 2018.x). To upgrade from one major version to another with a trial product key, install the new version of Tableau Server on a separate machine, activate a trial key there, and restore a backup from your existing version. For more information, see Confirm licensing requirements.

Expired maintenance—You cannot upgrade a server with a product key whose maintenance has expired or expires on a date earlier than the release date of the version you are upgrading to. If you attempt to upgrade a server in this state, your server will be unlicensed and the upgrade may fail. If your maintenance has expired or is too old, use the Manage Product Keys application to refresh your product key before you uninstall your original version. For more information about refreshing your product key in a version earlier than 2018.2.0, see Refresh Maintenance Date for the Product Key. If refreshing the key does not update maintenance to a valid date, check in the Tableau Customer Portal for a Tableau Server key with current maintenance.

Uninstall—Use Windows Control Panel to uninstall your existing pre-TSM version of Tableau Server before upgrading. This special case upgrade is unlike upgrades in earlier versions, which automatically uninstalled the previous version of Tableau Server. When you upgrade from version 2018.1 or earlier to version 2018.2 or later, you must uninstall your earlier version yourself. If you have not uninstalled your earlier version, you will be prompted to do so when you attempt to install your new version. This is specific to the 2018.1 or earlier to 20182 or later upgrades.

Backup—Save a backup of your earlier version to a safe place on a different computer. Uninstalling your previous version of Tableau Server will create a backup in the Tableau data directory (by default: C:\ProgramData\Tableau\Tableau Server). We strongly recommend you copy this backup to a computer that is not part of your Tableau Server installation before upgrading. This provides you with an up-to-date version of your data you can use if you need to go back to your earlier version of Tableau Server. For more information on properly preparing for an upgrade, see Prepare for the Upgrade.

Backups from versions of Tableau Server older than version 9.x cannot be used with version 2018.2.x or later. If you are running an older version of Server, you may need to do an intermediate upgrade to version 9.x through 10.x before upgrading to version 2018.2 or later.

Firewall management—Firewall management is manual. Unlike earlier versions of Tableau Server, you must manage the local firewall on any computers where you run Tableau Server. For more information, see Local firewall configuration.

Upgrade script—After installing the new version, complete the upgrade and switch to the new version by running the upgrade-tsm.cmd script. The script is installed in the \scripts.<version_code> folder of the new version you just installed.

Antivirus software—Antivirus software that scans directories used by Tableau Server can interfere with installation and ongoing use of Tableau Server. In some cases, this can result in installation failures, problems starting Tableau Server, or impacts to performance. If you plan to run antivirus software on the computer running Tableau Server, follow the recommendations in the Knowledge Base.

Multi-node upgrades:

Multi-node terminology—With TSM, we've changed the language we use to describe the Tableau Server nodes in a distributed installation. Prior to the release of TSM we referred to the first node as the "primary" node, and any additional nodes as "worker" nodes. With TSM the nodes are more closely peers, so we refer to the first node as the "initial" node, and other nodes as "additional" nodes.

Uninstall—Use Windows Control Panel to uninstall your existing pre-TSM version of Tableau Server from all nodes before upgrading. If you have not uninstalled your earlier version, you will be prompted to do so when you attempt to install your new version.

Node installation—Run the Setup program on all nodes in a cluster. Unlike some distributed installation upgrades in versions prior to 2018.2, there is no automatic upgrade of any additional nodes.

Single installer—Use the same Setup program on all nodes. Starting with 2018.2 you use the same installer on all nodes, and specify when prompted whether you are upgrading the initial (primary) node, or an additional (worker) node. There is no separate installer for the additional nodes.

Upgrade script—After installing the new version on all nodes in your cluster, complete the upgrade and switch to the new version by running the upgrade-tsm.cmd script on the initial node in the cluster.

Functionality that is not implemented in TSM

Restore config data from a backup file (.tsbak). The legacy version of tabadmin backup included configuration data by default. The analogous TSM command, tsm maintenance backup, does not include config data. To back up and restore config data in TSM, use the tsm settings commands.

With the introduction of Tableau Services Manager (TSM), you can no longer move the repository off the initial (primary) node in a two-node cluster. In versions 2018.1 and earlier, you could add a second repository to your second node and then remove the first repository. With TSM you cannot add a second repository on a two-node cluster, and this means you cannot move the repository off the initial node.