Configure Virtual Desktop Support

Applies to: Tableau Desktop, Tableau Prep

Virtual desktop support is an opt-in feature of Tableau Desktop 10.5 and later and Tableau Prep Builder 2018.2.1 and later that gives you the ability to optimise your installations of Tableau for non-persistent virtual desktops, or for computers that are regularly reimaged. The authorization-to-run (ATR) service enables the Tableau licence server to manage the activation limits and deactivations of the virtual machines (VMs).

Starting with version 2020.1, virtual desktop can be configured for login-based licence management (no product keys needed). This is the preferred, and often the required, method to implement a virtual deployment of Tableau Desktop when end users are not issued product keys. For more information, see Activate Tableau using Login-based Licence Management(Link opens in a new window).

With virtual desktop support enabled, Tableau login-based licence management licence capacity or key leases are automatically returned when not in use after a predetermined amount of time. This means that you do not need to manually refresh or deactivate the login-based licence management lease or any product key. Tableau must communicate with Tableau Server or Tableau Cloud for login-based licence management. If you are still using product keys, Tableau Desktop clients must periodically connect to the Internet to communicate with the hosted licence service.

Without virtual desktop support, an activated Tableau licence or login-based licence management licence lease remains in use until the licence term expires or the licence is deactivated, causing a maximum activation error. Using virtual desktop support with frequently recycled VMs or regularly re-imaged computers means that the VM is returned and the activation is added back to login-based licence management for a future activation request. Virtual Desktop manages the login-based licence management activation or product key activation, which prevents the maximum activation error from occurring when configured with the correct activation duration.

How virtual desktop support works

When virtual desktop support is enabled, Tableau Desktop or Tableau Prep Builder periodically contacts a Tableau-hosted authorisation-to-run (ATR) service to verify that Tableau is authorised to run, based on its licence. When virtual desktop is configured to also use login-based licence management, Tableau Cloud and Tableau Server work as a proxy to the ATR service to verify that Tableau is authorised to run with a valid Tableau Cloud or Tableau Server Creator user.

The ATR service verifies the licence or whether the user is a valid Creator user and the length of the authorisation window. As long as this communication is successful, Tableau runs without any impact to the user. The diagrams below show the communication process between the client and licensing components.

Virtual desktop support and the ATR service without login-based licence management

  1. Tableau Desktop or Tableau Prep Builder contacts the ATR service to verify that Tableau Desktop or Tableau Prep Builder is authorised to run.

  2. The ATR service contacts the Tableau Licensing Service to verify that the licence is valid.

  3. The ATR service determines the length of the authorisation to run window.

  4. If valid, the ATR service allows you to use Tableau Desktop or Tableau Prep Builder.

Login-based licence management with Tableau Cloud

Login-based licence management with Tableau Server

  1. You install Tableau Desktop or Tableau Prep Builder and select Activate with your credentials. You sign into your Tableau Cloud or Tableau Server site.

  2. Tableau Cloud or Tableau Server verifies that you are a Creator. If not, you get an error. If yes, Tableau Cloud or Tableau Server communicates with the ATR service.

  3. The ATR service returns an ATR lease to Tableau Cloud or Tableau Server.

  4. Tableau Cloud or Tableau Server provides an ATR lease to Tableau Desktop or Tableau Prep Builder to finalise activation.

Requested duration

By default, an instance of Tableau Desktop or Tableau Prep Builder is given a 14 day authorisation window during which it is authorised to run. This means that after the initial authorisation, you could use Tableau without any network connection for 14 days before the activation expired. The authorisation checks are attempted regularly, and each time a check is successful, the authorisation window is reset to its full length. This happens without any impact to you, unless there have been no successful checks and the window is nearing its expiration, in which case a warning message lets you know that you need to connect Tableau to the network so the authorisation can be confirmed. The 14 day default is typically not a good value for deploying virtual desktop where you receive a new VM with every use. For more information, see Requested duration settings.

The length of the authorisation window is determined by the value of the requested duration. By default, the requested duration is 14 days (1,209,600 seconds), but you can configure this to fit your environment depending on how often a user will be receiving a new VM or if the Tableau Desktop is of a persistent nature.

Note: If you use both Tableau Desktop and Tableau Prep Builder, setting the requested duration for Tableau Desktop also sets this same duration for Tableau Prep Builder and vice-versa.

Requested duration settings

You set the requested duration in seconds. The minimum requested duration you can set is 4 hours (14,400 seconds) and the maximum is six months (15,552,000 seconds). Use the following guidelines to determine how to set the requested duration setting for your users:

  • For most non-shared computers, especially those that are sometimes offline for several weeks at a time, set the requested duration to three to six months (7,776,000 – 15,552,000 seconds). A longer duration will allow the user to continue to use Tableau for an extended time without an internet connection.

  • For computers that are reimaged approximately once per month, set the requested duration to 30 days (2,592,000 seconds).

  • For virtual desktops that are recycled nightly, set the requested duration to the minimum of 4 hours (14,400 seconds). This will allow you to reuse your product activations (either login-based licence management or a product key) each morning and eliminates the need to remember to deactivate them each evening before the virtual desktops are recycled.

Virtual machines and product keys

The benefit of using virtual desktop support is that for environments that regularly recycle their VMs, you can set a duration short enough to expire the licence activation before the desktop is reused. This means that you do not use up all your activations. You will still need to enter the product key to run Tableau after the desktop is recycled. Login-based licence management can improve the end-user experience in this scenario by requesting a sign in to Tableau Cloud or Tableau Server to activate Tableau Desktop or Tableau Prep Builder instead of entering a product key.

Note: When using virtual desktop with subscription licences, you cannot refresh your product keys. To renew a subscription or make licensing changes, you must identify the new product key in the Tableau Customer Portal and activate it.

How to use virtual desktop support

Virtual desktop support is an opt-in feature if you're not using login-based licence management, so you need to enable the feature in order to use it (it is disabled by default). If you're using login-based licence management, the Tableau-managed licence service (ATR) is on by default, but the ATR duration and additional installer flags need to be set for Virtual Desktop support. The ways to enable virtual desktop when not using login-based licence management depend on whether you are running Tableau on Windows or on the Mac:

On Windows you can enable and configure virtual desktop support:

  • At installation of Tableau Desktop and Tableau Prep Builder using command line install switches to enable virtual desktop support and specify a requested duration.

  • After installation, by editing the Windows registry to enable virtual desktop support and specify a requested duration.

On a Mac you can enable and configure virtual desktop support:

  • After installation of Tableau Desktop and Tableau Prep Builder using sudo defaults write commands.

Tableau Desktop and Tableau Prep Builder on Windows

There are three methods for setting the virtual desktop flags:

Enable virtual desktop support at install

Run the installer .exe file from the computer's command line as an administrator and set the recommended flags as follows to ensure the best end user experience:

  • ATRENABLED=1 (if using product keys)
  • ATRREQUESTEDDURATIONSECONDS=14400 (lowest allowed activation return value)
  • SILENTLYREGISTERUSER="true"
  • SYNCHRONOUSLICENSECHECK='true"

Include the ATRENABLED switch if login-based licence management is not being used (version 2019.4 and earlier, or manually disabled). The ATRENABLED switch is not needed if login-based licence management is configured on Tableau Desktop.

The default value of ATRREQUESTEDDURATIONSECONDS is 14 days. For more information about the ATRREQUESTEDDURATIONSECONDS flag, see Requested duration settings.

The SILENTLYREGISTERUSER flag will stop the registration prompt on each new VM delivered as similarly, SYNCHRONOUSLICENSECHECK will stop the message that the licence has changed with each new VM.

If you need to extract the .msi files, follow the instructions to Extract and run the Windows (MSI) installer.

You must run the command from the directory where the .exe file is located or specify a full path to the location of the .exe file on the computer. Do not run the setup program from a shared directory on your network. Instead, download the .exe file to a directory on the computer where you're installing.

The ATRREQUESTEDDURATIONSECONDS has a minimum setting of 4 hours (14,400 seconds). The following example shows the Windows installer command that enables automatic licence deactivation and set the duration to 12 hours (43,200 seconds):

tableauDesktop-64bit-2022-1-0.exe /quiet /norestart ACCEPTEULA=1 ATRENABLED=1 ATRREQUESTEDDURATIONSECONDS=43200 SILENTLYREGISTERUSER="true" SYNCHRONOUSLICENSECHECK="true"

or

tableauPrepBuilder-64bit-2022-1-2.exe /quiet /norestart ACCEPTEULA=1 ATRENABLED=1 ATRREQUESTEDDURATIONSECONDS=43200 SILENTLYREGISTERUSER="true" SYNCHRONOUSLICENSECHECK="true"

When creating a primary image for a large virtual deployment, the above settings are appropriate and no product key activation should be completed. When using a new VM, each end user will enter the product key or sign in to Tableau Desktop or Tableau Prep Builder if login-based licence management is enabled.

Enable virtual desktop support by editing the registry

If Tableau Desktop or Tableau Prep Builder is already installed, you can still enable virtual desktop support by editing the Windows registry to add an entry for ATREnabled. To change the default duration a licence activation is authorised for, you can add an entry for ATRREQUESTEDDURATIONSECONDS.

  1. As an administrator on the computer running Tableau Desktop or Tableau Prep Builder, make a backup of the registry file before you make any changes to it.

  2. Edit the registry, and in HKEY_LOCAL_MACHINE\SOFTWARE\Tableau, create a new hive named ATR with these values:

    • Name: Add a string value named ATREnabled.

    • Data: Add 1.

    • Name: Add a string value named ATRRequestedDurationSeconds.

    • Data: Add a number of seconds the duration should last. For example, add 43200 to set a duration of 12 hours.

    The illustration below shows what the ATR hive looks like in the registry editor.

  3. Restart Tableau so that the changes take effect.

Enable virtual desktop support by using the atr tool

If Tableau Desktop or Tableau Prep Builder is already installed, you can still enable virtual desktop support from the Windows command prompt. The atrdiag.exe program resides in the \bin directory for Windows and is a tool specific to the virtual desktop and login-based licence management settings. The atrdiag.exe program can report on the values selected, change virtual desktop configuration settings, and initially configure virtual desktop. If Tableau Technical Support is needed, providing the output from the atr tool is often helpful.

Note: Tableau Prep Builder must be installed on the same computer with Tableau Desktop in order to use atrdiag.exe with Tableau Prep Builder.

  1. Sign in on the computer running Tableau Desktop as an administrator.

  2. At a command prompt, navigate to the directory where Tableau Desktop is installed:

    cd C:\Program Files\Tableau\<version>\bin

  3. At a command prompt, enable the ATR service:

    atrdiag.exe -enableATRFeature

  4. Set the duration, in seconds, that the licence activation is authorised for. (For example, use 43200 to set a duration of 12 hours.)

    atrdiag.exe -setDuration 43200

  5. Restart Tableau so that the changes take effect.

Disable virtual desktop support by using the atr tool

If you no longer want to use the virtual desktop support feature, you can disable it.

  1. Shut down Tableau Desktop on the computer where you want to disable virtual desktop support.

  2. Open the Windows Command Prompt as an administrator, and then navigate to the directory where Tableau Desktop is installed:

    cd C:\Program Files\Tableau\<version>\bin

  3. At a command prompt, run the following command to turn off the ATR service:

    atrdiag.exe -disableATRFeature

  4. At a command prompt, run the following command:

    atrdiag.exe -deleteAllATRs

  5. Start Tableau Desktop.

  6. On the Licence Has Changed dialog, click Exit.

  7. Restart Tableau so that the changes take effect.

  8. On the Help menu, click Manage Product Keys to see if you can deactivate the product key.

Tableau Desktop and Tableau Prep Builder on Mac

Enable by updating the preference file

To enable virtual desktop support on the Mac, run the following commands in a terminal window and then install or restart Tableau Desktop or Tableau Prep Builder:

sudo defaults write /Library/Preferences/com.tableau.ATR ATREnabled "1"

sudo defaults write /Library/Preferences/com.tableau.ATR ATRRequestedDurationSeconds -string "43200"

Troubleshoot virtual desktop

If you encounter issues when configuring or using virtual desktop, you can collect diagnostic information about the computer that is running Tableau Prep Builder or Tableau Desktop using the virtual desktop diagnostic tool (atrdiag).

You can verify that virtual desktop is enabled and view the value set for the requested duration seconds in use for Tableau Desktop activation. The TTL Start and TTL End values reflect the current lease being used on the virtual machine (VM) running Tableau Desktop. The commands provided below will capture the state of your virtual desktop support installation, regardless of whether you have installed Tableau Desktop or Tableau Prep Builder.

Error: Licence information has changed

When using virtual desktop, you may get an error message that your licence information has changed whenever you launch a new VM for Tableau Desktop or Tableau Prep Builder. This error forces a restart, which then asks you to register Tableau Desktop again. This error occurs because the ATR service sends a new token that doesn’t match the licence cache.

To prevent this from occurring, you can use the SYNCHRONOUSLICENSECHECK and SILENTLYREGISTERUSER options with the installer on Windows. For example:

tableau-setup-std-tableau-2020 SYNCHRONOUSLICENSECHECK="true" SILENTLYREGISTERUSER="true" ATRREQUESTEDDURATIONSECONDS=14400

or

tableauDesktop-64bit-2020-1-0.exe /quiet /norestart ACCEPTEULA=1 ATRREQUESTEDDURATIONSECONDS=14400 ACTIVATIONSERVER=http://<tableau_online_site_url> SYNCHRONOUSLICENSECHECK="true" SILENTYLYREGISTERUSER="true"

Collect virtual desktop diagnostics on Windows

  1. Open a Command Prompt as an administrator.
  2. Navigate to the Tableau binaries (\bin) directory, using the following command:

    cd Program Files\Tableau\Tableau <version>\bin

    For example:

    cd Program Files\Tableau\Tableau 2022.4\bin

  3. Run the following command:

    atrdiag.exe

    To optionally save the output to a file:

    atrdiag.exe > AtrOutput.txt

Collect virtual desktop diagnostics on Mac

  1. Open the Terminal app.
  2. Navigate to the directory that contains the atrdiag tool, using the following command:

    cd "/Applications/Tableau Desktop <version>.app/Contents/MacOS"

    For example:

    cd "/Applications/Tableau Desktop 2022.4.app/Contents/MacOS"

  3. Run the following command:

    ./atrdiag

    To optionally save the output to a file:

    ./atrdiag > AtrOutput.txt

To learn more about resolving issues with Tableau Desktop installation, see Troubleshoot Your Tableau Desktop or Tableau Prep Builder Installation or Troubleshoot Tableau Desktop or Tableau Prep Builder Licensing.

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