Was this page helpful?
Yes No

Upgrade from Tableau Server 2018.1 or earlier to Tableau Server with TSM

Tableau Server on Windows now includes Tableau Services Manager (TSM), which replaces the Configuration Utility and the command line tool. If you need help for an earlier version of Tableau Server, see the Tableau Help page.

Beginning with version 2018.2, Tableau Server on Windows is available with Tableau Services Manager (TSM). TSM is the web-based server configuration and management utility that replaces the Server Configuration utility and the tabadmin command line utility. The Tableau Server upgrade process has changed with the introduction of TSM. For information on how upgrade has changed, see Upgrade process changes.

When you upgrade from a pre-TSM version of Tableau Server (2018.1 or earlier) to a version running with TSM, you need to go through some special upgrade steps. These are required only for the pre-TSM to TSM upgrade. Pre-TSM versions of Tableau Server on Windows are versions older than 2018.2. Examples of pre-TSM versions are 9.3, 10.5, and 2018.1.

Note: 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.

Before you upgrade

Upgrading a server-based product requires planning and preparation. Upgrading Tableau Server from version 2018.1 or earlier to version 2018.2 or later is no different. Before you upgrade your production environment, make sure you have read through and completed the following sections: Research the Upgrade, Prepare for the Upgrade, and Test the Upgrade.

As a best practice, you should always make a backup of your Tableau Server data before upgrading, and save this backup in a safe place that is not part of your Tableau installation. This backup preserves your Tableau data if something unexpected happens during the upgrade, or if you need to go back to your previous version of Tableau Server. For more information, see Back up Tableau Server data.

Understand the key aspects of upgrading to TSM

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.

  • Licensing

    • 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. 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.

  • 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.

Multi-node upgrades:

  • 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.

ClosedConfirm your Run As user format includes the domain Confirm your Run As user format includes the domain

Tableau Server installations default to using the local Network Service account (NT Authority\Network Service) for the Run As user. If you are using this default account you can skip this section. If you changed the default account, or if you are not certain whether you are using a custom Run As user, follow the steps below.

Before upgrading to version 2018.2 or higher, make sure your Run As user is in the correct format. The format should include the domain, like this: <domain>\<runasuser>

  1. Stop the server by selecting All Programs > Tableau Server <version> > Stop Tableau Server on the Windows Start menu.

  2. Select Configure Tableau Server on the Windows Start menu.

  3. If you are using an Active Directory account for the server’s Run As User account, enter its password on the General tab.

  4. Confirm the format of your Run As User account:

    • If the Run As user is "NT AUTHORITY\NetworkService" you are using the default and do not need to make any changes. Cancel out of the configuration utility.

    • If the user name include the domain, you do not need to make any changes. Cancel out of the configuration utility.

    • If the user name does not include the domain, add the domain at the beginning of the user name, and separate the domain from the name using a back slash (\).

      For example, if the Server Run As User is "TableauServer" in the "MYCO" domain, update the User field to this: MYCO\TableauServer.

  5. Click OK.

  6. Restart the server.

ClosedGather existing files Gather existing files

You will need to gather the following files from your existing Tableau Server deployment. Later, at the end of the upgrade process, you will need to upload these files to complete the upgrade.

Some of these files contain secrets that must be protected. Use a secure process to copy, store, and transport these files.

  • Custom logos If you have customized the Tableau Server portal with custom images, then you will need copies of these files for the upgrade.

    For more information, see the Tableau Server 2018.1 online help topic, Change the Name or Logo.

  • SAML files. You will need the SAML certificate, key, and IdP metadata file. The default location for these files is C:\Program Files\Tableau\Tableau Server\SAML.

    For more information, see the Tableau Server 2018.1 online help topic, Configure SAML.

  • Kerberos keytab file. If you've enabled Kerberos SSO for Tableau Server, then you will need the keytab file that was generated as part of that configuration.

    For more information, see the Tableau Server 2018.1 online help topic, Kerberos Configuration Script.

  • SSL

    • CA cert file. If your existing Tableau Server is configured for mutual SSL, you will need to resubmit the CA cert file. The default location for these files is C:\Program Files\Tableau\Tableau Server\SSL.

    • Certificate and key files. You do not need to do anything with these files. These files are automatically upgraded.

  • Open ID file. If your organization uses a static discovery file (instead of an online discovery file), you will need a copy of that file for upgrade.

    For more information, see the Tableau Server 2018.1 online help topic, Configure Tableau Server for Open ID Connect.

ClosedUpgrade a single node Tableau Server Upgrade a single node Tableau Server
  1. After confirming that the Manage Product Keys application is not open, use Windows Control Panel to uninstall Tableau Server. Unlike earlier versions of the Setup program, version 2018.2 and later will not uninstall the previous version.

    Uninstalling will create a backup of your data and stop Tableau. Your data directories are left in place.

    The backup file created by the uninstall is used later, for the upgrade, and is saved as "uninstall-<version>.tsbak" in the Tableau data directory, by default: C:\ProgramData\Tableau\Tableau Server.

    Important: Save a copy of the backup on a different computer. This ensures you have the backup if something goes wrong on the Tableau Server computer. Creating and saving a backup to a non-Tableau location is a best practice step you should always take.

  2. Run the Setup program for the new version of Tableau Server with TSM on your initial (old primary) node.

    If you have not uninstalled your previous version of Tableau, a message will display telling you that the current version cannot be upgraded automatically. If you see this message, uninstall the previous version using Control Panel.

  3. When prompted for an install location, select the same location your previous installation used. If you do not select the correct location, the Setup program will assume a fresh installation and will not include your data.

    If you are upgrading an installation in a non-default location, see Upgrade Tableau Server in a Non-Default Location.

  4. When prompted for "Installation type", confirm that Upgrade Tableau Server. If multi-node, upgrade primary node of existing cluster. is selected (this is the default):

    Important: If you are not prompted with an upgrade option but instead see an option to Create a new Tableau Server installation, you may not have navigated to the correct location of your previous installation. If you continue, the installation will not include your data or configuration information from the previous installation.

  5. Click Next to continue.

    If you are prompted by Windows Defender Firewall, click Allow access. You may need to do this multiple times for the installation to complete.

  6. When the installation is done, the last page of the Setup program tells you that the upgrade is not yet finished. You need to run an upgrade script to complete the upgrade. You can run the script from the Setup program, or run it yourself from the command line.

  7. Run the upgrade script in one of two ways.

    • From the Setup program:

      1. Select Automatically launch the upgrade script, and click OK:

      2. A command window will open for the script. Because you are logged in as a user with local administrator rights, the script will run using your credentials and you will be prompted for the password for the TSM administrator. If your old installation of Tableau Server used a non-default Run As user, you will also be prompted for the Run As user password.

        The upgrade script will look for the backup file created by the uninstall of the previous version in the Tableau data folder (C:\ProgramData\Tableau\Tableau Server). You can specify a backup file in a different location using a --backup-path option but to do this you need to run the script from the command line.

    • On the command line:

      1. On the initial node, open a command prompt as administrator.

      2. Navigate to the scripts folder for your new installation.

        By default:

        C:\Program Files\Tableau\Tableau Server\packages\scripts.<version>\

      3. Run the upgrade script:

        upgrade-tsm

        The script will assume a location for a backup file from your previous installation, and prompt you for passwords:

        • By default the upgrade script will look for the backup file created by the uninstall of the previous version in the Tableau data folder (C:\ProgramData\Tableau\Tableau Server). You can specify a different location using a --backup-path option. For example:

          upgrade-tsm --backup-path "C:\path\to\backup\file\uninstall-10.5.tsbak"

        • Because you are logged in as a user with local administrator rights, the script will run using your credentials and you will be prompted for the password for the TSM administrator. You can specify a different user and password when you run the script using --username and --password options.

        • If your old installation of Tableau Server used a non-default Run As user, you will also be prompted for the Run As user password. You can provide this when you run the script using a --service-runas-password option.

        To see all options for the upgrade-tsm script, use the -h option:
        upgrade-tsm -h

  8. When the upgrade is complete, a browser window will open with the TSM sign in page. Sign in to TSM. You will be prompted to activate or register Tableau Server if these steps are needed.

    If the window does not open automatically, open a browser window and go to:

    https://<tsm-computer-name>:8850

  9. Start Tableau Server.

    • In the Web UI:

      • Click Tableau Server is stopped, and Start Tableau Server

    • On the command line:

      1. On the initial node, open a command prompt as administrator.

      2. Navigate to the bin directory for your new installation. By default this is:

        C:\Program Files\Tableau\Tableau Server\packages\bin.<version>

      3. Start Tableau Server:

        tsm start

  10. Upload files. Use the following TSM commands to upload files from your previous Tableau Server. The files must be uploaded with TSM. Do not copy them to destinations in the Tableau Server folder hierarchy. Instead, copy them to a temporary directory (for example, C:\temp) and then run the TSM commands to copy them into the system.

    • Custom logo files. If you have customized the Tableau Server portal with custom images, run the following command:

      tsm customize --header-logo <file> --signin-logo <file> --logo <file>

    • SAML files. Run the following command for SAML SSO:

      tsm authentication saml configure --cert-file <file> --key-file <file> --idp-metadata <file>

      If you are using SAML for datasource delegation, run the following command:

      tsm data-access set-saml-delegation --cert-file <file> --key-file <file>

    • Kerberos. Run the following commands:

      tsm authentication kerberos configure --keytab-file <file>

      tsm authentication kerberos enable

    • Mutual SSL files. Follow the instructions here:

      Configure Mutual SSL Authentication

    • Open ID file. Run the following command:

      tsm authentication openid configure --metadata-file <file>

    If you run any of the above commands, you also need to apply pending changes:

    tsm pending-changes apply

ClosedUpgrade a multi-node Tableau Server Upgrade a multi-node Tableau Server
  1. After confirming that the Manage Product Keys application is not open, use Windows Control Panel to uninstall Tableau Server. Unlike earlier versions of the Setup program, version 2018.2 and later will not uninstall the previous version.

    Uninstalling will create a backup of your data and stop Tableau. Your data directories are left in place.

    The backup file created by the uninstall is used later, for the upgrade, and is saved as "uninstall-<version>.tsbak" in the Tableau data directory, by default: C:\ProgramData\Tableau\Tableau Server.

    Important: Save a copy of the backup on a different computer. This ensures you have the backup if something goes wrong on the Tableau Server computer. Creating and saving a backup to a non-Tableau location is a best practice step you should always take.

  2. When Tableau Server is uninstalled on the primary node, use Control Panel to uninstall Tableau on all worker nodes before continuing.

  3. Run the Setup program for the new version of Tableau Server with TSM on your initial (old primary) node.

    If you have not uninstalled your previous version of Tableau, a message will display telling you that the current version cannot be upgraded automatically. If you see this message, uninstall the previous version using Control Panel.

  4. When prompted for an install location, select the same location your previous installation used. If you do not select the correct location, the Setup program will assume a fresh installation and will not include your data.

    If you are upgrading an installation in a non-default location, see Upgrade Tableau Server in a Non-Default Location.

  5. When prompted for "Installation type", confirm that Upgrade Tableau Server. If multi-node, upgrade primary node of existing cluster. is selected (this is the default).

    Important: If you are not prompted with an upgrade option but instead see an option to Create a new Tableau Server installation, you may not have navigated to the correct location of your previous installation. If you continue, the installation will not include your data or configuration information from the previous installation.

  6. Click Next to continue.

    If you are prompted by Windows Defender Firewall, click Allow access. You may need to do this multiple times for the installation to complete.

    When the installation is done, do not run the upgrade script. You need to generate a bootstrap file and install the other nodes before running the script.

  7. Generate the bootstrap file on the initial node:

    1. On the initial node, open a command prompt as administrator.

    2. Navigate to the bin directory for your new installation. By default this is:

      C:\Program Files\Tableau\Tableau Server\packages\bin.<version>

    3. Generate the bootstrap file:

      tsm topology nodes get-bootstrap-file -f <path\file>.json

  8. Copy the bootstrap file to each additional (worker) node, or to a network location accessible to the nodes.

  9. On each additional node, run Setup to install the new version of Tableau Server. Unlike previous versions of Tableau Server, version 2018.2 and later has one Setup program you use on both the initial node and all additional nodes.

    If you have not uninstalled your previous version of Tableau, a message will display telling you that the current version cannot be upgraded automatically. If you see this message, uninstall the previous version using Control Panel.

  10. When prompted for an install location, select the same location your previous installation used. If you do not select the correct location, the Setup program will assume a fresh installation and will not include your data.

    If you are upgrading an installation in a non-default location, see Upgrade Tableau Server in a Non-Default Location.

  11. When prompted for "Installation type", select the option to Upgrade worker node of existing Tableau Server cluster (only applies to multi-node):

    Important: If you are not prompted with an upgrade option but instead see an option to Create a new Tableau Server installation, you may not have navigated to the correct location of your previous installation. If you continue, the installation will not include your data or configuration information from the previous installation.

  12. Click Next to continue.

    If you are prompted by Windows Defender Firewall, click Allow access. You may need to do this multiple times for the installation to complete.

  13. When prompted:

    1. Navigate to the location of the bootstrap file you copied.

    2. Enter the username and password for a user who has administrative rights on the computer where the bootstrap file was created (for example, the TSM administrator who created the bootstrap file).

    3. Click Next to continue.

  14. When the node installation completes, a dialog tells you the upgrade is not yet complete:

    Click OK to close the dialog.

  15. After you install the new version on all nodes, run the upgrade script on the initial node:

    1. Navigate to the scripts directory for the new version.

      By default:

      C:\Program Files\Tableau\Tableau Server\packages\scripts.<version>\

    2. Run the upgrade script:

      upgrade-tsm

      Because you are logged in as a user with local administrator rights, the script will run using your credentials and you will be prompted for the password for the TSM administrator.

      By default the upgrade script will look for the backup file created by the uninstall of the previous version in the Tableau data folder (C:\ProgramData\Tableau\Tableau Server).

      Note: If your old installation of Tableau Server used a non-default Run As user, you will be prompted for the Run As user password. You can include the --service-runas-password option if you know this is the case. To see all options for the upgrade-tsm script, use the -h option:
      upgrade-tsm -h

  16. When the upgrade is complete, a browser window will open with the TSM sign in page. Sign in to TSM. You will be prompted to activate or register Tableau Server if these steps are needed.

    Note: If the window does not open automatically, open a browser window and go to:

    https://<tsm-computer-name>:8850

  17. Start Tableau Server:

    In the Web UI

    • Click Tableau Server is stopped, and Start Tableau Server:

    • On the command line:

      1. On the initial node, open a command prompt as administrator.

      2. Start Tableau Server:

        tsm start

        If you get an error that the command is not recognized, close all command windows and then open a command prompt as administrator.

  18. Upload files. Use the following TSM commands to upload files from your previous Tableau Server. The files must be uploaded with TSM. Do not copy them to destinations in the Tableau Server folder hierarchy. Instead, copy them to a temporary directory (for example, C:\temp) and then run the TSM commands to copy them into the system.

    After you have uploaded the files, the Client File Service process will distribute the files to the appropriate nodes in the installation.

    • Custom logo files. If you have customized the Tableau Server portal with custom images, run the following command:

      tsm customize --header-logo <file> --signin-logo <file> --logo <file>

    • SAML files. Run the following command for SAML SSO:

      tsm authentication saml configure --cert-file <file> --key-file <file> --idp-metadata <file>

      If you are using SAML for datasource delegation, run the following command:

      tsm data-access set-saml-delegation --cert-file <file> --key-file <file>

    • Kerberos. Run the following commands:

      tsm authentication kerberos configure --keytab-file <file>

      tsm authentication kerberos enable

    • Mutual SSL files. Follow the instructions here:

      Configure Mutual SSL Authentication

    • Open ID file. Run the following command:

      tsm authentication openid configure --metadata-file <file>

    If you run any of the above commands, you also need to apply pending changes:n

    tsm pending-changes apply