Running Setup

This chapter describes how to install Tableau Server 2021.1 on Linux and perform essential configuration steps to get the server up and running. Installing the software is the first step to sharing and connecting to workbooks. Later chapters of this guide describe how to configure Tableau Server so users can connect from anywhere to share, view, and publish data.

If you are upgrading your server, see Upgrade Tableau Server(Link opens in a new window).

The Everybody's Install Guide is published only for the most recent version (2021.1) of Tableau Server. If you want to install an earlier version of Tableau Server, refer to the deployment content for the version that you wish to install. See Archived Help Content(Link opens in a new window).

This chapter describes how to install Tableau Server on Linux using the GUI whenever possible. If you prefer to use a shell, follow the installation steps in our full server help(Link opens in a new window).

In this chapter

Let's review

In the previous chapter (Planning Your Deployment) you figured out:

  • How you're going to license your server (by users or by cores).

  • What hardware you'll need in order to run your server.

  • How your users are going to authenticate with Tableau Server—either using LDAP directory or using local authentication on Tableau Server.

Right? If not, go back and spend some time on these issues. This is where an ounce of prevention really does save a pound of cure. For example, if you go through this chapter and guess at the authentication configuration, and you get it wrong … well, you'll have to uninstall the server and start over. Or worse, if you undersize your hardware specs for the usage your organization requires, then eventually everyone will be grumpy because things run too slowly.

Before you install

There are a few things you must do before you proceed with installation.

Make sure you have the right version of Tableau Server software

Our recommendation is this: use the same version (for example, 2021.1) of Tableau Desktop and Tableau Server across your organization. To get the latest version of Tableau Server software, go to the Customer Portal(Link opens in a new window). When you purchase Tableau, you get a user name and password to sign in to the Customer Portal.

If you're in a situation where you must run different versions of Tableau on different computers, read the article Desktop and Server Compatibility(Link opens in a new window).

Get a product key and make sure you're registered

Using the user name and password that you received when you purchased Tableau, go to the Customer Portal(Link opens in a new window) and get your product key.

Also make sure that you've registered an email address. We need a contact email to associate with each product key. You should provide us with an email address that is checked frequently and that will not expire.

Make sure you have the right Linux distro

The following distributions of Linux are supported:

  • Amazon Linux 2
  • Red Hat Enterprise Linux (RHEL) 7.3 and higher (not 8.x), and Amazon Linux 2

  • CentOS 7.3 and higher (not 8.x)

  • Oracle Linux 7.3 and higher (not 8.x)

  • The latest versions of Ubuntu 16.04 LTS and 18.04 LTS (not 17.04)

  • Debian 9

Additional notes on Linux distributions:

  • Red Hat Enterprise Linux (RHEL), CentOS, Oracle Linux, and Amazon Linux distributions are collectively referred to in this documentation as RHEL-like.

  • RHEL 8 is not supported.

  • Non-LTS releases of Ubuntu are not supported.

  • Ubuntu version 17.04 is not supported.

  • Previous versions of CentOS and Ubuntu are not supported because Tableau Server requires systemd for process management.

  • The version of the installer with the file suffix, .deb, installs on both Ubuntu and Debian distributions.

  • Custom kernels are not supported.

Make sure you have root permissions

All installation tasks and administrative tasks for Tableau Server must be run as root. Often this is accomplished using the sudo command, but running the commands directly as the root user is also possible.

To install Tableau Server with the root account, you must specify a user account during installation. The account that you specify will be used for managing TSM. Specify the account by running the initialize-tsm script with the -a option. See Help Output for initialize-tsm Script(Link opens in a new window).

Make sure you're installing on a "clean" computer

As we discussed in the planning chapter, we recommend that you install Tableau Server on a computer that's dedicated to running Tableau Server. Here's why:

  • Performance. As Tableau Desktop users discover the data liberation that Tableau Server enables, they'll use Tableau Server to share data sources, and to view, share, and host workbooks as part of their daily decision making process. This data transformation requires a server computer that is fast and stable. Tuning performance is much more straightforward when Tableau Server is not competing with other resources, especially other database applications.

  • Security. A general security best practice is to segregate server applications as much as possible. Tableau Server acts as a conduit between your users and data that might be spread across your network. Tableau Server also stores extracts of your important data. All Tableau Software is built with disciplined security engineering practices, and we do a lot of work to protect data, accounts, and sensitive information with our default installation. But to reduce the risk of security incidents, you should reduce the attack surface of the computer running Tableau Server by removing (or not installing) other server software.

  • Interoperability. A highly experienced administrator can get Tableau Software to interoperate happily with lots of other server software that might be installed on the same computer. But we're assuming that you want to minimize the time you spend manually configuring the server.

    For example, if the server computer where you are installing Tableau Server is running a service that communicates over HTTP, then it will already be configured to use port 80 and/or 443, which means that port won't be available for Tableau Server. Sure, you can configure Tableau Server to use a different port, like 8000. But that means that anytime your users connect to Tableau Server, they'll have to put that port number into the URL (http://your-server:8000/). You can see how this would pretty much guarantee a steady stream of emails to you about how to connect to Tableau Server. It's not pretty and it's not conducive to a data revolution. Best practice, therefore, is to make sure Tableau Server has the server computer all to itself

File paths

We reference some file paths in the procedure that follows. When we know where a file lives, we reference it as an absolute path. For example:

cd /opt/tableau/tableau_server/packages/scripts.<version>

However, you may need to create files and you'll need to save them somewhere. Obviously, we have no way of knowing where you put those. In these cases, we reference paths in this way:

tsm register --file /path/to/registration_file.json

Ready? Let's lay those bits down …

Step 1: Install Tableau Server package and start Tableau Services Manager

Install Tableau Server with your distribution’s package manager, then run a script to initialize Tableau Services Manager (TSM). Tableau Services Manager is a the management toolset used to install, configure, and manage Tableau services.

The initialize script is included with the installed package.

  1. Log on as a user with sudo access to the computer where you want to install Tableau Server.

  2. Navigate to the directory where you copied the Tableau Server installation package.

  3. Use the package manager to install the Tableau Server package.

    Do not install to a location using a symbolic link or to a directory on a Network File System (NFS) volume.

    • On RHEL-like distributions, including CentOS, run the following commands, where <version> is formatted as major-minor-maintenance (ex: 2019-2-5):

      sudo yum update

      sudo yum install tableau-server-<version>.x86_64.rpm

      Note: When you use yum to install Tableau Server, all dependent packages are automatically downloaded and installed. This is the preferred method for installing Tableau. If your organization does not allow you to use yum and you must install using rpm -i, you must also install all dependent packages separately.

    • On Ubuntu and Debian, run the following commands, where <version> is formatted as major-minor-maintenance (ex: 2019-2-5):

      sudo apt-get update
      sudo apt-get upgrade
      sudo apt-get -y install gdebi-core
      sudo gdebi -n tableau-server-<version>_amd64.deb
  4. Navigate to the scripts directory:

    cd /opt/tableau/tableau_server/packages/scripts.<version>

  5. Run the ./initialize-tsm script to start TSM. At a minium, you'll need to run the --accepteula flag when you run the script.

    Whether or not you need to add another flag depends on how Tableau Server connects to the internet. Tableau Server must be able to access the internet to download map data and to connect with the Tableau licensing server.

    • If the Tableau Server that you are installing can access the internet directly, run the following script:

      sudo ./initialize-tsm --accepteula

    • If your organization uses a forward proxy solution to access the internet, then you will need to configure Tableau Server to use the proxy. In this case, you will need to find out what the host name or IP address of the proxy server is and the HTTP port that the port uses. In most cases, the HTTP port will be 80. And in all cases, the HTTPS (SSL) port must be 443.

      You must include the --http_proxy and/or --https_proxy flags to specify the forward proxy server.

      After you determine the host name or IP address of the proxy server, configure Tableau Server to use the proxy by running the following initialization script:

      sudo ./initialize-tsm --accepteula --http_proxy=http://proxy.example.lan:80/ --https_proxy=

      In this example, proxy.example.lan and are the example host name and IP address respectively. You'll need to replace one or both of those before you run the script.

      Also, take care to use http when you specify the URL for the https_proxy environmental variable. Do not specify the https protocol for the value of the https_proxy environmental variable.

  6. After initialization is complete, close the terminal session:


Step 2: Activate and register Tableau Server

Before you can configure Tableau Server you must activate a license and register.

Beginning by logging on to the TSM web UI. See sign in to Tableau Services Manager Web UI(Link opens in a new window).

What if I can't log in?

If you get an authentication error, verify that the user account is in the tsmadmin group. To view the user accounts in the tsmadmin group, run the following command in Bash:

grep tsmadmin /etc/group

If the user account is not in the group, run the following command to add the user to the tsmadmin group:

sudo usermod -G tsmadmin -a <username>

After you have added the user to the tsmadmin group, run the tsm login command.

After you have successfully logged in to TSM, sign in to Tableau Services Manager Web UI(Link opens in a new window) to activate and register Tableau Server:

  1. On the Activate page, Enter or paste your product key and click Activate License.

  2. On the Register page, enter your information into the fields and click Register.

Step 3: Configure general server settings

The most important configuration on this Setup page is the identity store option.

Make sure you've got the identity store type right

Make sure that you configure Tableau Server for the correct identity store solution. If you want to change it after you install, then you have to reinstall Tableau Server. Select one of the options below for the identity store you are configuring.

Option 1: Local identity store

Configuring the identity store for Local is straight-forward: just select it and your done.

Option 2: Active Directory

Tableau Server requires read access to Active Directory. You can use simple bind or GSSAPI bind to authenticate Tableau Server with Active Directory.

LDAP simple bind

If you are using simple bind to authenticate with Active Directory, enter a domain account and password. We recommend using LDAPS to connect. See LDAP over SSL(Link opens in a new window) in the server online help.


We recommend binding to LDAP directory with GSSAPI. To bind with GSSAPI you will need a keytab file specifically for the Tableau Server service. See Understanding Keytab Requirements(Link opens in a new window).

Option 3: OpenLDAP or other LDAP directory

This is an advanced configuration. Work with your IT administrator to develop an identityStore LDAP configuration(Link opens in a new window) file and run the CLI version of Setup as documented in the online server help. (Link opens in a new window)

Save the file locally, for example, ldap_config_file.json. During the setup process, instead of configuring for local idenity store, pass the ldap_config_file.json configuration file instead.

Gateway port

The default port for web access to Tableau Server (via HTTP) is port 80. If the installation program determines that port 80 is in use when you first install Tableau Server, an alternate port (for example 8000) is used and shown in the Port number box.

You may need to change the port for other networking needs, for example, if you have a hardware firewall or proxy in front of the Tableau Server host, this might make running a back-end system on port 80 undesirable.

Sample workbook installation

By default, Tableau Server will install sample workbooks in the Default site when you initialize the server.

Alternatively, you can publish samples after installation by using the publishsamples(Link opens in a new window) tabcmd command.

After you have configured the options on this page, click Initialize.

The initialization process can take a while. When initialization is complete the following page is displayed:

Step 4: Create the Tableau Server administrator account

Create the Tableau Server administrator account.

  • If you are using LDAP for authentication, then the account that you specify here must be a user in the directory.

    Run the following command:

    tabcmd initialuser --server 'localhost:80' --username '<AD-user-name>'

  • On the other hand, if you are running Tableau Server with local authentication, the username and password that you specify here will be used to create the administrative account. Enter a strong password for this account.

    Run the following command:

    tabcmd initialuser --server 'localhost:80' --username 'admin'

Use this account to access the Tableau Server admin web pages. See Sign in to Tableau Server Admin Pages(Link opens in a new window).

Wait... there are two different admin tools?

Strictly speaking, no, there are five different paths to administrating Tableau Server. The table here should clear it up. (The first two tools should be all you need.)

Admin tool used for... Account needed? How do I access it?
Tableau Server Admin Pages Tableau-specific tasks relating to content. Creating and managing: users, groups, projects, sites, permissions, etc.

Use the account that you just created in the last step above.

See Sign in to Tableau Server Admin Pages(Link opens in a new window).


This is the tool that you used to setup and configure Tableau Server. The kinds of configurations that you make with TSM relate to server settings. For example, if you decide to enable SAML, or configure more processes for Tableau Server components, you'll be using the TSM Web UI.

If you're familiar with older versions of Tableau Server, then think of TSM Web UI as a replacement for the Tableau Server Configuration Utility.

Any account that has administrative rights on the local computer where Tableau Server is running can access TSM Web UI.

See Sign in to Tableau Services Manager Web UI(Link opens in a new window).

TSM Command Line Interface (CLI)

This is a shell version of the TSM Web UI. If you are comfortable in the command line, then this is the tool for you. The TSM CLI has access to all configurable components of Tableau Services Manager, whereas the TSM Web UI is a subset.

If you're a CLI user and you are familiar with older versions of Tableau Server, then think of TSM CLI as a replacement for tabadmin cli tool.

Any account that has administrative rights on the local computer where Tableau Server is running can use TSM CLI to manage the server.

See tsm command line reference(Link opens in a new window).

tabcmd You can use the tabcmd command-line utility to automate site administration tasks on your Tableau Server site. For example, creating or deleting users, projects, and groups.

Use the same account for tabcmd that you use for Tableau Server. Using this account, you will have the same permissions to sites and content as you do when you sign in to Tableau.

See tabcmd(Link opens in a new window).

APIs and developer tools

There's a REST API, there's an Extract API, there's a Web Data Connector, and there are tools and samples on GitHub. These tools and APIs represent a huge potential for automating, extending, customizing, and optimizing Tableau Server for the data nerds in your organization.

Account requirements depend on what you're building.

Start here: Tableau Developer Tools(Link opens in a new window).

Step 5: Configure local firewall (optional)

We recommend that you run a local firewall on the computer that is running Tableau Server. This is a security best practice. By default, Linux distributions do not enable firewall during standard installations.

If you have installed or enabled a local firewall then you must open two ports for Tableau Server. These ports are the gateway port (TCP 80) and the tabadmincontroller port (TCP 8850). The following procedure shows an example of how to open these ports using Firewalld, which is the default firewall on CentOS. If you are using a different firewall then you'll need to determine the right commands to run to open these ports.

  1. Start firewalld:

    sudo systemctl start firewalld

  2. Set default zone to public. Run the following command:

    sudo firewall-cmd --set-default-zone=public

  3. Add ports for the gateway port and the tabadmincontroller port. Run the following commands:

    sudo firewall-cmd --permanent --add-port=80/tcp

    sudo firewall-cmd --permanent --add-port=8850/tcp

  4. Reload the firewall and verify the settings. Run the following commands:

    sudo firewall-cmd --reload

    sudo firewall-cmd --list-all

Step 6: Validate your installation

To validate that Tableau Server is installed and running properly and to review the built-in administrative views, you must install the PostgreSQL driver.

  1. Download PostgreSQL drivers from the Driver Download page(Link opens in a new window).

  2. Copy the .jar file to this folder (you may have to create it manually): /opt/tableau/tableau_driver/jdbc.

  3. Restart TSM:

    tsm restart

  4. To validate that the drivers installed, navigate to the Administrative Views in Tableau Server.

Your server is installed!

After you create the administrator user, you're signed in as the administrator to Tableau Server, using the web interface. You can poke around the UI to get a sense of what you can do. You can also try publishing a workbook(Link opens in a new window) to the server from Tableau Desktop.

But before you roll out Tableau Server to all colleagues, you must perform a few more steps. First: back up your server. Even though you don't have any users or data on your Tableau Server, you should do a quick back up. The next chapter, Backing Up Tableau Server, provides the essential steps.

After you back up the server, you'll probably want to secure access to your server by configuring SSL and (optionally) providing secure access from internet clients.

After that, we'll describe how to add users, create groups, and then configure projects so the right people have access to the right content.

Continue to Backing Up Tableau Server.

Thanks for your feedback!