Migrate Tableau Server from Windows to Linux

Customers running Tableau Server on Windows can migrate to Linux by taking a backup of their existing Tableau installation and restoring it to a fresh installation on Linux. This topic describes the steps necessary to do this migration. You cannot migrate or upgrade from a beta version of Tableau Server to an officially released version.

The basic steps to migrate from Tableau Server on Windows to Tableau Server on Linux include:

  1. Step 1: Plan your migration—Plan for your migration, including gathering all the information you'll need to be successful. During this step you should familiarize yourself with potential differences between Tableau Server on Windows and Tableau Server on Linux.

  2. Step 2: Create a backup—Create a backup of Tableau Server on Windows.

  3. Step 3: Install Tableau Server on Linux and restore the Windows backup—Install a fresh instance of Tableau Server on Linux in a test environment so you can test out the migration, then restore your Windows backup. The restore of your Windows backup will restore the Tableau content (users, projects, sites, workbooks and data sources), but will not restore customizations, so you will need to spend some time configuring Tableau Server on Linux to match the expectations in your organization. If you have a multi-node installation you will need to add nodes and configure them separately.

  4. Step 4: Test Tableau Server on Linux—Try Tableau Server on Linux to make sure content is there as you expect, and users are able to perform all the actions they do on Windows. Look specifically at any changes identified as potential differences between Tableau Server on Windows and Tableau Server on Linux. Include key stakeholders in the testing both to leverage their knowledge and to help communicate the upcoming changes.

  5. Step 5: Install Tableau Server on Linux in your production environment and restore the Windows backup—Once you're satisfied that Tableau Server on Linux gives you the functionality you need, install Tableau in your production Linux environment and restore the Windows backup.

Step 1: Plan your migration

A successful migration from Windows to Linux requires some preparation beforehand. You will need to satisfy the following requirements:

  • Identity 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. To change the identity store from a local identity store to an external identity store, see Changing the Identity Store .

  • Server administrator: You must have password for at least one of the user accounts with Server Administrator privileges from the Tableau Server source (Windows) deployment. You must use the same user as the Server Administrator in the migrated deployment to Linux.

  • Clean installation of Tableau Server for Linux: When you install Tableau Server on Linux later in this topic, be sure to use the same identity store type as you are using on Windows, and do not create users or content. When you restore the Windows backup file to the Linux deployment of Tableau Server, all user data and content will be replaced from the Windows back up file.

  • Differences between Windows and Linux: Review the differences between Tableau Server on Windows and on Linux so you are aware of them and can investigate in your test environment.

    • If you are migrating from a version of Server on Windows prior to 10.5, approach the migration like an upgrade and familiarize yourself with any changes between your existing version and 10.5 by reading What's Changed in the Server on Windows help.

    • Any custom fonts you use may need to be installed on your Linux computer, and may render differently there than on Windows.

    • Connection options for Linux are a subset of those available for Tableau Server on Windows. Review the connection types that are available and make sure the ones you need are supported.

    • TSM replaces tabadmin. Understand the TSM commands and how they compare to older tabadmin commands. For a list of tabadmin commands and their TSM equivalents, see Migrate from Tabadmin to the TSM CLI.

Step 2: Create a backup

The steps to create a backup depend on what version of Tableau Server on Windows you are running. If you have version 2018.1.x or earlier, you need to use tabadmin to create your backup. If you are running version 2018.2.0 or later, you use TSM to create the backup.

Migrate from 2018.1 or earlier

If you are migrating from Tableau Server on Windows version 2018.1.x or earlier:

  1. Log on to the computer running Tableau Server on Windows.

  2. Open a command prompt as an administrator.

  3. Navigate to the bin directory. For example:

    cd "C:\Program Files\Tableau\Tableau Server\10.4\bin"

  4. Run the following command:

    tabadmin backup tabserver -v -d

    Include the -v flag to verify the integrity of the backup. Include the -d flag to include the date in the file name. In the example, tabserver will be used as the base file name of the resulting backup file. The date of the backup will be appended to the file name, for example, tabserver-2017-12-20.tsbak.

For more information, see Back Up Tableau Server Data in the Tableau Server on Windows help (version 2018.1).

Migrate from 2018.2 or later

If you are migrating from Tableau Server on Windows version 2018.2.0 or later:

  1. Log on to the computer running Tableau Server on Windows.

  2. Open a command prompt as an administrator.

  3. Run the following command:

    tsm maintenance backup -f <filename> -d

    Include the -d flag to include the date in the backup file name.

For more information, see Back up Tableau Server data in the Tableau Server on Windows help.

Step 3: Install Tableau Server on Linux and restore the Windows backup

In a test environment, install Tableau Server on Linux:

  • Install Tableau Server for Linux according to the procedure, Install and Configure Tableau Server. Use the same identity store as on your Windows deployment, and do not create users or content.

Restore the Tableau Server on Windows backup:

  1. Copy the Windows backup file to the computer running Tableau Server on Linux. By default the restore process will look for the file in this location:

    /var/opt/tableau/tableau_server/data/tabsvc/files/backups/

    You can change the location. For more information, see tsm File Paths.

  2. Run the following command to stop Tableau Server:

    tsm stop
  3. Run the following command to restore from the backup file:

    tsm maintenance restore -f <filename.tsbak>

    Where <filename.tsbak> is the name of your backup file, for example, tabserver-2017-10-20.tsbak.

    For more information, see tsm maintenance restore

  4. Run the following command to start Tableau Server:

    tsm start

After restoring your Tableau content, you may need to configure Tableau Server. For example, if you are migrating from a multi-node installation, you will need to add and configure the additional nodes. You will also need to configure any customizations you made on Windows, including copying over image or logo files if applicable.

Step 4: Test Tableau Server on Linux

Once you've installed Tableau Server on Linux and restored your Windows backup, you can test the new version of Tableau Server. Because the restore process only restores content to Tableau, you may need to update configuration, topology (adding additional nodes for example), and any customizations you have on your Windows installation.

You'll want to be familiar with the known differences between Windows and Linux, as well as any potential problem areas. Test basic functionality, along with any special aspects of server that your organization relies on. For example, there may be key data sources that your organization uses with Tableau. Test these to make sure you're seeing what you expect.

These are some areas of testing to consider:

  • User access. Confirm that Tableau Server users, including administrators, can sign in. Test your normal user sign in process. Have some of your users participate in the testing to make sure they are able to sign in as expected, and that they can get to the same content that they have access to in your production environment.

  • Viewing built-in administrative views. With this release of Tableau Server on Linux, you must install PostgreSQL drivers manually, and the administrative views depend on these. Confirm that you have installed the drivers necessary by accessing the built-in administrative views. For more information, see Administrative Views .

  • Data source availability. Tableau Server on Linux supports a subset of the data sources on Tableau Server on Windows. You need to confirm that the data sources used by your organization are supported on Linux, and install any drivers required. For details on which data sources are supported, see the Tableau Server tech specs. For information about installing drivers, see Database Drivers.

  • Access to file-based data sources on shared drives. Data sources such as Excel files on network drives will require special actions in order to be accessible from Linux. You or your IT department will need to mount the drives and update any workbooks using these data sources. For more information on connecting to network drives, see the Tableau Community.

  • Viewing published workbooks. Have users who are familiar with the content try to view published workbooks to make sure they appear as expected. Test views embedded in web pages (for example, in SharePoint pages). Be especially aware of how fonts may differ between Windows and Linux, and some custom fonts may need to be added to your Linux computer, or replaced with other fonts if they are not available on Linux. Dashboard layouts may appear different as well, due to differences in fonts.

  • Server processes. Sign in to Tableau Server as a server administrator, and then open the Server Status page to confirm that all services and processes are running as expected. Be aware of intentional changes due to changes in version 10.5. For more information, see Tableau Server Data Engine.

  • Publishing workbooks and data sources. Have users publish workbooks and data sources from Tableau Desktop to make sure this goes as you expect. You may need to install drivers to support the data source connections you are using. See Database Drivers.

  • Subscriptions and extract refreshes. Manually run some extract refreshes to confirm that they complete successfully. Run some key scheduled extract refreshes to confirm that they complete as expected.

  • Permissions. Confirm that permissions are still set as expected for users and content.

  • Command-line utilities and APIs. If applicable, test the command line utilities (tsm and tabcmd) and programmatic access via APIs. With Tableau Server on Linux, tabadmin is replaced by TSM. For more information, see Migrate from Tabadmin to the TSM CLI.

Step 5: Install Tableau Server on Linux in your production environment and restore the Windows backup

When you have completed testing and have identified those areas that require additional changes on your part, or communication to your users, you are ready to install Tableau Server on Linux in your production environment and restore the Windows backup. To do this, follow the same steps described above.

Important: If you are migrating from Tableau Server version 2018.1 or earlier on Windows - You can take a backup from Tableau Server on Linux and restore that backup to Tableau Server on Windows version 2018.2 or later, but you cannot restore that backup to Tableau Server on Windows version 2018.1 or earlier. This means that if you migrate to Linux, you cannot easily switch back to Tableau Server on Windows version 2018.1 or earlier. Keep this in mind as you test your migration, and consider keeping your installation on Windows until you are certain that you no longer need it.

Thanks for your feedback! There was an error submitting your feedback. Try again or send us a message.