Configure Virtual Desktop Support
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 optimize your installations of Tableau for non-persistent virtual desktops or for computers that are regularly reimaged. With virtual desktop support enabled, Tableau licenses are automatically deactivated after a predetermined amount of time if Tableau Desktop or Tableau Prep Builder cannot connect to a Tableau-hosted service that confirms the validity of the license. This means that you do not need to manually refresh or deactivate the product key. The requirement that Tableau communicate with the hosted service means that you must periodically connect to the Internet.
Without virtual desktop support, an activated Tableau license remains activated until you explicitly deactivate it. This means that with frequently recycled VMs and regularly reimaged computers, you may never have the opportunity to deactivate the license before the system is recreated, and the license activation remains in effect. Reactivating Tableau can fail if there are no valid activations left for the license.
How virtual desktop support works
When virtual desktop support is enabled, Tableau Desktop or Tableau Prep Builder periodically contacts a Tableau-hosted “Authorization to Run” (ATR) service to verify that Tableau is authorized to run, based on its license. The ATR service verifies the license and the length of the “authorization window.” As long as this communication is successful, Tableau runs without any impact to the user.
By default, an instance of Tableau Desktop and Tableau Prep Builder is given a 45 day authorization window during which it is authorized to run. This means that after the initial authorization, you could use Tableau without any network connection for 45 days before the activation expired. The authorization checks are attempted regularly, and each time a check is successful, the authorization window is reset to its full length. This happens without any impact to a user, unless there has been no successful check and the window is nearing its expiration, in which case a warning message lets the user know they need to connect Tableau to the network so the authorization can be confirmed.
The length of the authorization window is determined by the value of the requested duration. By default, the requested duration is 45 days (3,888,000 seconds), but you can configure this to fit your environment and how you use Tableau.
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.
You set the requested duration in seconds. The minimum requested duration you can set is 12 hours (43,200 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 – 15552000 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 12 hours (43,200 seconds). This will allow you to reuse your product keys each morning, and eliminate the need to remember to deactivate them each evening before the virtual desktops are recycled.
Virtual machines and product keys
The benefit of using Tableau's virtual desktop support is that for environments that regularly recycle their VMs, you can set a duration short enough to expire the license 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.
How to use virtual desktop support
Virtual desktop support is an "opt in" feature, so you need to enable the feature in order to use it (it is disabled by default). The ways to do this 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 writecommands
Tableau Desktop and Tableau Prep Builder on Windows
Enable at install
Run the installer
.exe file from the computer's command line as an administrator, including the
ATRENABLED switch. To use a duration length other than the default of 45 days, include the
ATRREQUESTEDDURATIONSECONDS switch. 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 following example shows the Windows installer command that enables automatic license deactivation and set the duration to 12 hours:
tableauDesktop-64bit-2019-1-0.exe /quiet /norestart ACCEPTEULA=1 ATRENABLED=1
tableauPrepBuilder-64bit-2019-1-2.exe /quiet /norestart ACCEPTEULA=1 ATRENABLED=1
Enable 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 license activation is authorized for, you can add an entry for ATRRequestedDurationSeconds.
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.
Edit the registry, and in
HKEY_LOCAL_MACHINE\SOFTWARE\Tableau, create a new hive named
ATRwith these values:
Name: Add a string value named
Name: Add a string value named
Data: Add a number of seconds the duration should last. For example, add
43200to set a duration of 12 hours.
The illustration below shows what the
ATRhive looks like in the registry editor.
- Restart Tableau so the changes take effect.
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"
If you encounter issues when using virtual desktop support, the Tableau Support team might request that you collect diagnostic information about the computer that is running Tableau Prep Builder or Tableau Desktop using the virtual desktop support diagnostic tool (atrdiag). After you collect this diagnostic information, you can email it to Tableau Support. 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.
Note: You should only run the Virtual Desktop Support diagnostic tool at the request of the Tableau Support team.
Collect Virtual Desktop Support diagnostics on Windows
- Open a Command Prompt as an administrator.
- Navigate to the Tableau binaries (
\bin) directory, using the following command:
cd Program Files\Tableau\Tableau <version>\bin
- Run the following command:
atrdiag.exe > AtrOutput.txt
Collect Virtual Desktop Support diagnostics on Mac
- Open a Terminal app.
- Navigate to the directory that contains the atrdiag tool, using the following command:
cd /Applications/Tableau Desktop <version>.app/Contents/MacOS
- Run the following command:
./atrdiag.exe > AtrOutput.txt
To learn more about resolving issues with Tableau Desktop installation, see Troubleshoot Your Tableau Desktop or Tableau Prep Builder Installation.