Tableau Server on Windows Help

You can run tsm commands on the initial node (the node where TSM is installed), or on any additional node in the cluster.

To run tsm commands, you need to open Windows Command Prompt. Do not use PowerShell to run tsm commands. Using PowerShell can cause unexpected behaviour.

1. Open Windows Command Prompt with an account that is a member of the Administrators group on a node in the cluster.

2. Run the command you want. If you are running the command from a node other than the initial node, include the -s option to specify the URL of the initial node by name (not IP address), and include the TSM port, 8850.

   To see the version of TSM and Tableau Server from the initial node:

   tsm version

   To see the version of TSM and Tableau Server from an additional node:

   tsm version -s https://<inital_node_name>:8850

   For example:

   tsm version -s https://myTableauHost:8850

backgrounder.failure_threshold_for_run_prevention

Default value: 5

The number of consecutive failures of a subscription, extract or flow run job before that job is suspended. Suspending continuously failing jobs helps preserver backgrounder resources for other jobs. To disable suspension of failing background tasks, set this to -1.

backgrounder.log.level

Version: Added in version 2020.3.0.

Default value: info

The logging level for the backgrounder process. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

backgrounder.restrict_serial_collections_to_site_level

Default value: false

In Tableau Server, you can schedule extract refreshes, subscriptions or flows to run periodically. These scheduled items are referred to as tasks. The Backgrounder process initiates unique instances of these tasks to run them at the scheduled time. The unique instances of the tasks that are initiated as a result are referred to as jobs.

This setting affects schedules that are configured to run serially. By default, when a schedule is configured to run serially, all jobs using that schedule will run serially. When this setting is set to true, jobs running on different sites can run in parallel. Jobs for scheduled tasks on the same site will continue to run serially.

The example below illustrates this scenario:

Tableau Server includes a schedule named "Daily" to run jobs every day at 7 am. The "Daily" schedule is configured to run serially. Site "HR" and site "Payroll" each have multiple scheduled tasks that use the schedule, "Daily". When this setting is set to true, jobs for these scheduled tasks on Site "HR" can run in parallel with jobs on site "Payroll", whereas jobs on the same site will still only run serially.

backgrounder.timeout.single_subscription_notify

Version: Added in version 2021.2.

Default Value: 1800 seconds (30 minutes)

This is the maximum allowable time specified in seconds for completing a single subscription job.

backgrounder.timeout.sync_ad_group

Version: Added in version 2021.1.23, 2021.2.21, 2021.3.20, 2021.4.15, 2022.1.11, 2022.3.3, 2023.1.

Default Value: 14400 seconds (4 hours)

This is the maximum allowable time, specified in seconds, for completing an Active Directory group sync. This applies to scheduled group synchronisations done by the backgrounder service and prevents long-running syncs from running indefinitely. This does not impact group synchronisations done using the Tableau Server UI or the REST API.

backgrounder.vInstances_max_overflow_queue_size

Version: Added in version 20221.2.

Default Value: 1000

The maximum number of jobs that can be in the secondary queue. A secondary queue is created when the number of jobs running is at the set concurrency limit. The default maximum is set to 1000 jobs – meaning if there are more than 1000 jobs when the concurrency limit is hit, anything more than 1000 jobs will not be queued. Use the backgrounder.vInstance_max_overflow_queue_size tsm command to make changes to the overflow maximum queue size.

The values should be specified in whole numbers.

backup.zstd.thread_count

Version: Added in version 2021.1.0. This key is dynamically configurable. For more information, see Tableau Server Dynamic Topology Changes

Default value: 2

The number of threads that should be used when creating a backup.

Increasing this number can improve backup performance, but we recommend thread count not exceed the number of logical processors on the Tableau Server computer, up to four.

basefilepath.backuprestore

Default value: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\backups\

The location in which the tsm maintenance backup command creates the backup. This is also the location where the backup file must be when restored using the tsm maintenance restore command or the tsm maintenance send-logs command. After setting this, you should run the tsm maintenance validate-backup-basefilepath command (available in version 2022.1 and later) to verify that permissions are set properly for the location. For more information, see tsm File Paths.

basefilepath.log_archive

Default value: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\log-archives\

The location in which the tsm maintenance ziplogs command creates the zipped archive. For more information, see tsm File Paths.

basefilepath.site_export.exports

Default value: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\siteexports\

The location in which the tsm sites export command creates the export file. For more information, see tsm File Paths.

basefilepath.site_import.exports

Default value: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\siteimports\

The location in which the tsm sites import command expects the import file to be located. For more information, see tsm File Paths.

clustercontroller.log.level

Version: Added in version 2020.3.0.

Default value: info

The logging level for Cluster Controller. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

databaseservice.max_database_deletes_per_run

Version: Added in version 2021.2.

Default value: null

Use this option to adjust the maximum number of embedded external assets (databases and tables) that can be deleted each time the backgrounder process, controlled by features.DeleteOrphanedEmbeddedDatabaseAsset, runs. If this option is left empty, the default maximum number of embedded external assets that can be deleted is 100.

For more information, see features.DeleteOrphanedEmbeddedDatabaseAsset.

dataserver.log.level

Version: Added in version 2020.3.0.

Default value: info

The logging level for Data Server. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

dataserver_<n>.port

Port that the data server instance (specified by "<n>") runs on.

excel.shadow_copy_all_remote.enabled

Version: Added in versions 2019.1.5, 2019.2.1.

Default value: false

Controls whether Tableau Server creates a "shadow copy" of a shared Excel spreadsheet (.xlxs or .xlxm) that is being used as a live data source. When enabled, this option prevents Excel users from seeing a "Sharing Violation Error" and a message that the file is "currently in use". This option can have a performance impact with large Excel files. If Excel users do not need to edit the shared file, you do not need to enable this option.

Note: Tableau Server always attempts to create a shadow copy of a .xls file. This option does not change that behaviour.

extractservice.command.execution.timeout

Version: Added in version 2021.4.

Default value: 7200 seconds

Sets the timeout value for VConn extract refresh run time.

Example: tsm configuration set -k extractservice.command.execution.timeout -v <timeout_in_seconds> --force-keys

Note: You must use the --force-keys option to change this value.

features.ActiveMQ

Version: Added in version 2021.4.

Default value: true

Controls whether Tableau Server uses the Apache ActiveMQ service (Tableau Server Messaging Service) for the internal messaging mechanism.

features.DeleteOrphanedEmbeddedDatabaseAsset

Version: Added in version 2021.2.

Default value: true

Controls a backgrounder process, for Tableau Catalogue (or Tableau Metadata API), that deletes embedded external assets (databases and tables) that are no longer associated with downstream Tableau content. This process runs every day at 22:00:00 UTC (coordinated universal time) and can delete a maximum of 100 external assets each day until there are no remaining external assets without connections to downstream Tableau content. You can set this option to false to stop this process from running. Alternatively, you can also adjust the maximum number of external embedded assets that can be deleted using databaseservice.max_database_deletes_per_run.

For more information see, Troubleshoot missing content.

features.IdentityMigrationBackgroundJob

Version: Added in version 2022.1. Default value was changed to false in versions 2021.4.22, 2022.1.18, 2022.3.10, 2023.1.6 and 2023.3.

Default value: false

Controls the process that performs the identity migration. When set to true, the identity migration runs in existing deployments immediately after upgrading Tableau Server to version 2022.1 (or later) and restoring a backup of Tableau Server version 2021.4 (or earlier). Set to false (default) to disable the identity migration.

For example, to start the identity migration, run the following:

tsm configuration set -k features.IdentityMigrationBackgroundJob -v true

For more information, see About the Identity Migration.

Note: If the identity migration is disabled, Tableau Server cannot use the Identity Service to store and manage user identity information. Using the Identity Service is a prerequisite for certain capabilities like identity pools.

features.IdentityPools

Version: Added in version 2023.1.

Default value: false

A component of the identity pools capability that needs to be enabled if you perform a new Tableau Server installation. Requires feature.NewIdentityMode and wgserver.authentication.legacy_identity_mode.enabled. Set to true to enable identity pools. Set to false (default) to disable identity pools.

For example, to enable identity pools, run the following:

tsm configuration set -k features.IdentityPools -v true
tsm configuration set -k features.NewIdentityMode -v true
tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled -v false
tsm pending-changes apply

For more information, see Troubleshoot identity pools.

features.MessageBusEnabled

Version: Added in version 2019.4.

Default value: true

Controls whether Tableau Server uses the new internal messaging mechanism.

features.NewIdentityMode

Version: Added in version 2022.1.

Default value: false. The default value was changed from true to false in 2023.1.6.

A prerequisite of the identity pools capability. Requires wgserver.authentication.legacy_identity_mode.enabled to be set to false to enable identity pools. Set to true to disable identity pools.

tsm configuration set -k features.IdentityPools -v true
tsm configuration set -k features.NewIdentityMode -v true
tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled -v false
tsm pending-changes apply

For more information, see Troubleshoot identity pools.

features.PasswordlessBootstrapInit

Default value: true

Controls whether Tableau Server allows embedded credentials in bootstrap files. When enabled (the default), embedded credentials are included in the bootstrap file unless you specify that they should not be included. Set this to false if credentials should never be included in any bootstrap file you generate. For more information on generating bootstrap files, see tsm topology nodes get-bootstrap-file.

This option was added beginning with Tableau Server version 2019.3.

features.PasswordReset

Version: Retired in version 2024.2. For versions 2024.2 and later, use vizportal.password_reset.

Default value: false

Applies only to servers that use local authentication. Set to trueto let users reset their passwords with a "Forgot password" option on the sign-in page.

filestore.empty_folders_reaper.enabled

Version: Added in 2020.x (2020.1.14, 2020.2.11, 2020.3.6, 2020.4.2) and 2021.1.x. The default value was changed to true in 2021.2.

Default value: true

Enables the job that "reaps" (removes) empty Filestore folders.

filestore_empty_folders_reap.frequency_s

Version: Added in 2020.x (2020.1.14, 2020.2.11, 2020.3.6, 2020.4.2).

Default value: 86400 (24 hours)

Specifies, in minutes, how often to run the job that removes empty Filestore folders.

features.Hyper_DisallowTDEPublishing

Version: Defaults to true beginning in version 2023.1.0. Deprecated in Tableau Server 2024.2.

Default value: true

Specifies if users can upload .tde format files. This format was replaced by .hyper format beginning in version 10.5 of Tableau Server, but were not blocked from upload. Starting with Version 2024.3, .tde format files are no longer usable. The files were automatically converted to .hyper format if one of several actions were performed. For more information, see Extract Upgrade to .hyper Format.

filestore.log.level

Version: Added in version 2020.3.0.

Default value: info

The logging level for File Store. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

filestore.reapemptyfoldersholdoffms

Version: Added in 2020.x (2020.1.14, 2020.2.11, 2020.3.6, 2020.4.2). This is not yet available in 2021.1.

Default value: 300000 (5 minutes)

Specifies in milliseconds, the amount of time to wait before removing empty Filestore folders.

floweditor.max_datafile_upload_size_in_kb

Version: Added in version 2020.4

Default value: 1048576

For Tableau Prep flow web authoring, the maximum size of delimited text files (for example, CSV or TXT) that can be uploaded to Tableau Server.

gateway.external_url

Version: Added in version 2023.1

Default value: Null

Required when OpenID Connect (OIDC) authentication is configured in TSM during Tableau Server setup or with identity pools. Specifies the Tableau Server URL used by the identity provider (IdP) to redirect users who authenticate into Tableau. The gateway external URL is the same URL that you specified as the redirect URL with your IdP, which is used for matching purposes.

For example, to redirect the IdP associated with OIDC authentication configuration to your Tableau Server, http://myco, run the following command:

tsm configuration set -k gateway.external_url -v http://myco

gateway.http.hsts

Default value: false

The HTTP Strict Transport Security (HSTS) header forces browsers to use HTTPS on the domain where it is enabled.

gateway.httpd.loglevel

Version: Added in 2021.3.0.

Default value: notice

Specifies the logging level for the Gateway (Apache HTTPD server). By default, this is set to notice. Other options include debug, info, warning, error. If you change the logging level, be aware of potential impact to disk space usage and performance. As a best practice, return the logging level to the default after you have gathered the information you need. For detailed information on Apache logging, see the Apache HTTP documentation(Link opens in a new window).

gateway.httpd.shmcb.size

Version: Added in 2021.4

Default value: 2048000

Specifies the amount of memory in bytes for the circular buffer when using the shmcb storage type. This configuration key doesn’t apply when using the dbm storage type.

gateway.httpd.socache

Version: Added in 2021.4

Default value: shmcb

Specifies the storage type of the global/inter-process SSL Session Cache. By default, this is set to shmcb, with another configurable option dbm. For more information about shmcb and dbm storage types, see SSLSessionCache Directive(Link opens in a new window) on the Apache website.

gateway.log.level

Version: Added in version 2020.3.0.

Default value: info

The logging level for Gateway. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

hyper.log_queries

Default value: true

When set to true, query information is logged.

By default query information is logged. If however you find that the log files are too large for the amount of disk space available, you can set it to false to disable logging query information. Tableau recommends leaving this configuration set to true.

hyper.session_memory_limit

Default value: 0 (which means unlimited)

Controls the maximum memory consumption that an individual query can have. Specify the number of bytes. Append the letter 'k' to the value to indicate kilobytes, 'm' to indicate megabytes, 'g' to indicate gigabytes or 't' to indicate terabytes.

For example, to set the memory limit to 900 megabytes, run the following command:

tsm configuration set -k hyper.session_memory_limit -v 900m.

Alternatively, to specify the session memory limit as a percentage of the overall available system memory run the following command:

tsm configuration set -k hyper.session_memory_limit -v 90%.

Lowering this value can help when a query is using excessive amounts of memory and making other queries fail over a long period of time. By lowering the limit, the single big query would fail (or resort to spooling if spooling isn’t turned off) and not have a negative impact on other queries.

hyper.srm_cpu_limit_percentage

Default value (in percent): 75

Specifies the maximum hourly average CPU usage permitted by Hyper. If exceeded, Data Engine will restart itself to minimise impact to other processes on the computer.

By default Data Engine will restart itself if it averages more than 75% usage of CPU over an hour. This value should not be changed except when working with Tableau Support, or if you are running Data Engine on a dedicated server node. If Data Engine is running on a dedicated node, you can safely increase this value to 95 percent to take full advantage of available computer hardware. For details on running Data Engine on a dedicated node, see Optimise for Extract Query-Heavy Environments.

To increase this to 95%:

tsm configuration set -k hyper.srm_cpu_limit_percentage -v 95 --force-keys

tsm pending-changes apply

To reset this to the default of 75%:

tsm configuration set -k hyper.srm_cpu_limit_percentage -v 75 --force-keys

tsm pending-changes apply

hyper_standalone.consistent_hashing.enabled

Default value: true

Improves the chance that the extract for a query is already cached. If the node with the extract cached cannot support additional load, you will be routed to a new node and the extract will be loaded into cache on the new node. This results in better system utilisation because extracts are only loaded into memory if there is load that justifies the need.

indexandsearchserver.vmopts

Version: Added in version: 2022.1.

Default value: "-Xmx<default_value> -Xms<default_value>"

The default value is based on the amount of system memory and is 3.125% of the total system RAM.

Controls the Index and Search Server heap size. Because the default value scales automatically, use this option to override the default value only when absolutely necessary. Append the letter 'k' to the value to indicate kilobytes, 'm' for megabytes or 'g' to indicate gigabytes. As a general rule, set initial heap size (-Xms) equal to the maximum heap size (-Xmx) to minimise garbage collections.

jmx.security.enabled

Version: Added in version: 2022.1.

Default value: false

JMX is disabled by default, so secure JMX is also disabled. If you are enabling JMX, we strongly recommend you enable secure JMX.

This is set to true and turns secure JMX on with SSL and basic username/password authentication for readonly access when you run the tsm maintenance jmx enable command and answer y when prompted to enable security features for JMX:

tsm maintenance jmx enable
We do not recommend you enable JMX unsecured on a production environment. Would you like to enable security features for JMX?
(y/n): y

jmx.ssl.enabled

Version: Added in version: 2022.1.

Default value: true

Enforces SSL for JMX. This option defaults to true but has no effect unless jmx.security.enabled is also set to true. To enable JMX security, run the tsm maintenance jmx enable command. Answer y when prompted to leave SSL enabled, or n to disable SSL:

tsm maintenance jmx enable
...
Would you like to enable SSL?
(y/n): n

jmx.ssl.require_client_auth

Version: Added in version: 2022.1.

Default value: false

This is set to true when you run the tsm maintenance jmx enable command and answer y when prompted to require client authentication (mTLS):

tsm maintenance jmx enable
...
Would you like to require client authentication (mTLS)?
(y/n): y

To complete configuration you must have a client cert and place this in the correct location on your client computer.

jmx.ssl.user.name

Version: Added in version: 2022.1.

Default value: tsmjmxuser

This is set when you install or upgrade Tableau Server.

jmx.ssl.user.password

Version: Added in version: 2022.1.

Default value: <generated>

This is set when you install or upgrade Tableau Server.

jmx.user.access

Version: Added in version: 2022.1.

Default value: readonly

You can change this to readwrite when you run the tsm maintenance jmx enable command and answer y when prompted to add readwrite access:

tsm maintenance jmx enable
...
JMX access is readonly by default. Would you like to add readwrite access?
(y/n): y

licensing.login_based_licence_management.default_requested_duration_seconds

Default value: 0

Set to the duration (in seconds) that a user's login-based licence can be offline with no connection to Tableau Server before they are prompted to activate again. This duration is always refreshed when Tableau Desktop is in use and can connect to Tableau Server.

licensing.login_based_license_management.enabled

Default value: true

Set to true to enable login-based licence management. Set to false to disable login-based licence management.

Note: In order to use login-based licence management, you must activate a product key that is enabled for login-based licence management. You can use the tsm licenses list to see which product keys have login-based licence management enabled.

licensing.login_based_licence_management.max_requested_duration_seconds

Default value: 7776000

Set to the maximum duration (in seconds) that a user’s login-based licence can be offline with no connection to Tableau Server before they are prompted to activate Tableau again. The maximum value is 7776000 seconds (90 days). This duration is always refreshed when Tableau Desktop is in use and can connect to Tableau Server.

metadata.ingestor.blocklist

Default value: null

When configured, Tableau Catalogue blocks specified content from being ingested. To specify which content to block, you must identify the blocklist values, which is a combination of both the site ID, content type and content ID of the content you want to block, from the server “noninteractive” log files. Blocklist values must be separated by a comma.

Important: You should only use this option when directed to do so by Tableau Support.

For example, you can use the tsm configuration set --force-keys -k metadata.ingestor.blocklist to block ingestion of a combination of data sources, workbooks and flows using the following command:

tsm configuration set --force-keys -k metadata.ingestor.blocklist -v "sites/1/datasources/289, sites/2/datasources/111, sites/1/workbooks/32, sites/3/workbooks/15, sites/1/flows/13, sites/1/flows/18”

To validate blocked content, review the server “noninteractive” log files for the following events:

• Skipping ingestion for
• Successfully updated blocklist to

For example:

Skipping ingestion for contentType [Workbook], contentId [sites/1/datasources/289], siteDisabled [false], swallowEvent [false], contentBlocked [true]

Skipping ingestion for contentType [Workbook], contentId [sites/3/workbooks/15], siteDisabled [false], swallowEvent [false], contentBlocked [true]

and

Successfully updated blocklist to: [sites/1/datasources/289, sites/1/workbooks/32, sites/2/datasources/111]

metadata.ingestor.pipeline.throttleEventsEnable

Default value: false

Controls whether indexing of new and updated content, also called eventing, is regulated across all sites on the server. By default, event throttling is turned off. To turn on event throttling, change this setting to true using the following command: 

tsm configuration set -k metadata.ingestor.pipeline.throttleEventsEnable -v true --force-keys

For more information about event throttling, see Enable Tableau Catalog.

metadata.ingestor.pipeline.throttleLimit

Default value: 20

When event throttling is enabled, this is the maximum number of new and updated content items that can be indexed during a specified period of time. Once the specified limit is reached for a specific item, indexing is deferred.

By default, the limit is set to 20 and can't be set to lower than 2. You can use the following command to change the limit: 

tsm configuration set -k metadata.ingestor.pipeline.throttleLimit -v 25 --force-keys

Throttled events can be identified in the server "noninteractive" log files as ingestor event flagged for removal by throttle filter.

metadata.ingestor.pipeline.throttlePeriodLength

Default value: 20

When event throttling is enabled, this is the period of time, in minutes, a specified maximum number of new and updated content items can be indexed. Once the specified time is reached, indexing of any additional new and updated content is deferred.

By default, the time is set to 30 minutes. You can use the following command to change the time:

tsm configuration set -k metadata.ingestor.pipeline.throttlePeriodLength -v PT45M --force-keys

metadata.query.limits.time

Default value: 20

This is the longest allowable time, in seconds, for a Catalogue or Metadata API query to run before a timeout occurs and the query is cancelled. Tableau recommends incrementally increasing the timeout limit to no more than 60 seconds using the following command:

tsm configuration set -k metadata.query.limits.time –v PT30S --force-keys

Important: This option should be changed only if you see the error described here, Timeout limit and node limit exceeded messages. Increasing the timeout limit can utilise more CPU for longer, which can impact the performance of tasks across Tableau Server. Increasing the timeout limit can also cause higher memory usage, which can cause issues with the interactive microservices container when queries run in parallel.

metadata.query.limits.count

Default value: 20000

This is the number of objects (which can loosely map to the number of query results) that Catalogue can return before the node limit is exceeded and the query is cancelled. Tableau recommends incrementally increasing the timeout limit, to no more than 100,000 using the following command:

tsm configuration set -k metadata.query.limits.count –v 3000 --force-keys

Important: This option should be changed only if you see the error described here, Timeout limit and node limit exceeded messages. Increasing the node limit can cause higher memory usage, which can cause issues with the interactive microservices container when queries run in parallel.

metadata.query.throttling.enabled

Version: Added in version 2023.3

Default value: true

Controls whether Metadata API(Link opens in a new window) query throttling is enabled. Metadata API query throttling is a feature designed to prevent a server's API responses from negatively impacting overall performance. When set to true (the default), if a request to the Metadata API exceeds the defined threshold, a RATE_EXCEEDED error is returned.

If Metadata API users are seeing frequent RATE_EXCEEDED errors, an administrator can try to adjust throttling using the metadata.query.throttling.tokenRefilledPerSecond and metadata.query.throttling.queryCostCapacity settings. Alternatively, the administrator can disable throttling entirely by setting the metadata.query.throttling.enabled value to false. Doing so would prevent the performance-protecting benefits of the feature, however.

metadata.query.throttling.queryCostCapacity

Version: Added in version 2023.3

Default value: 20000000

A number representing the capacity that the Metadata API(Link opens in a new window) has for answering queries. Each request to the Metadata API has a calculated cost that is subtracted from this number when it's executed. (Using a token bucket model, this is the maximum amount of tokens that can be in the bucket.)

If Metadata API users are seeing frequent RATE_EXCEEDED errors, an administrator can adjust throttling settings. They should adjust metadata.query.throttling.tokenRefilledPerSecond and test the results before trying to adjust metadata.query.throttling.queryCostCapacity. Alternatively, the administrator can disable throttling entirely by setting metadata.query.throttling.enabled to false. Doing so would prevent the performance-protecting benefits of the feature, however.

metadata.query.throttling.tokenRefilledPerSecond

Version: Added in version 2023.3

Default value: 5555

A number representing the amount of Metadata API(Link opens in a new window) query capacity that's regenerated every second. (Using a token bucket model, this is the number of tokens that are put into the bucket every second.)

If Metadata API users are seeing frequent RATE_EXCEEDED errors, an administrator can adjust throttling settings. They should adjust metadata.query.throttling.tokenRefilledPerSecond and test the results before trying to adjust metadata.query.throttling.queryCostCapacity. Alternatively, the administrator can disable throttling entirely by setting metadata.query.throttling.enabled to false. Doing so would prevent the performance-protecting benefits of the feature, however.

native_api.allowed_paths

Default value: ""

Note: In Tableau Server releases (including maintenance releases) before October 2023, this setting was configured to allowed access to all paths by default.

Use this setting to specify an allowlist for access to files stored on Tableau or on remote shares. This scenario allows authorised Tableau Server users to build workbooks that use files on the server as file-based data sources (such as spreadsheets).

This setting allows you to limit access only to those directories that you specify. The Run As Service Account access is therefore limited to the directory paths where you host data files.

Important: Make sure the file paths you specify in this setting exist and are accessible by the system account.

native_api.ExplainDataEnabled

Default value: true

This option controls whether Explain Data is enabled or disabled for the server. For more information about Explain Data, see Get Started with Explain Data(Link opens in a new window) in the Tableau Help.

This option was added beginning with Tableau Server version: 2019.3.

nlp.concepts_shards_count

Default value: 1

Note: The default shard count value is sufficient for most Tableau Server installations.

Controls the number of data shards for the Concepts index of Ask Data, field names, field synonyms and analytical terms stored in shards in:

• The Index and Search Server for 2022.1 and later versions.
• Elastic Server for 2019.1 - 2021. 4

The shard count partitions the search index to reduce total index size, which may improve the performance of Ask Data's semantic parser. Adjusting the shard count is another performance enhancement measure that you can take along with increasing the heap size through elasticserver.vmopts or indexandsearchserver.vmopts, depending on the version of Tableau Server that you are running.

Tableau recommends increasing the shard count by 1 for every 50 GB. To reduce the number of times you need to adjust the shard count, calculate the total index size by adding 50% to the current index. For example, if the total index size is less than 50 GB, then 1 shard is sufficient. Actual performance will vary depending on the server, the rate at which the index size grows and other factors.

• 0 to 50 GB: 1
• 50 GB to 100 GB: 2
• 100 GB to 150 GB: 3

You can use the following command to increase the Concepts index shard count from default to 2:

tsm configuration set -k nlp.concepts_shards_count -v 2

nlp.values_shards_count

Default value: 1

Controls the number of data shards for the Concepts index of Ask Data, field names, field synonyms and analytical terms stored in shards in:

• The Index and Search Server for 2022.1 and later versions.
• Elastic Server for 2019.1 - 2021. 4

The shard count partitions the search index to reduce total index size, which may improve the performance of Ask Data's semantic parser. Adjusting the shard count is another performance enhancement measure that you can take along with increasing the heap size through elasticserver.vmopts or indexandsearchserver.vmopts, depending on the version of Tableau Server that you are running.

Tableau recommends increasing the shard count by 1 for every 50 GB. To reduce the number of times you need to adjust the shard count, calculate the total index size by adding 50% to the current index. For example, if the total index size is less than 50 GB, then 1 shard is sufficient. Actual performance will vary depending on the server, the rate at which the index size grows and other factors.

• 0 to 50 GB: 1
• 50 GB to 100 GB: 2
• 100 GB to 150 GB: 3

You can use the following command to increase the Values index shard count from default to 2:

tsm configuration set -k nlp.values_shards_count -v 2

nlp.defaultNewSiteAskDataMode

Default value: disabled_by_default

Use this option to set the initial value of the Ask Data Mode when a site is created. For more information see Disable or Enable Ask Data for a Site.

Valid options are disabled_by_default and disabled_always.

This option was added beginning with Tableau Server versions: 2019.4.5, 2020.1.3.

noninteractive.vmopts

pgsql.port

Default value: 8060

Port that PostgreSQL listens on.

pgsql.preferred_host

Specifies the computer name of the node with the preferred repository installed. This value is used if the --preferred or -r option is specified with the tsm topology failover-repository command.

Example:

pgsql.ssl.ciphersuite

Default value: HIGH:MEDIUM:!aNULL:!MD5:!RC4

Specifies the cipher algorithms that are allowed for SSL for the Repository.

For acceptable values and formatting requirements, see ssl_ciphers(Link opens in a new window) on the Postgres website.

pgsql.ssl.max_protocol_version

Default value:TLSv1.3

Sets the maximum SSL/TLS protocol version to use when connecting to the repository over SSL.

Valid values: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

pgsql.ssl.min_protocol_version

Default value:TLSv1.2

Sets the minimum SSL/TLS protocol version to use when connecting to the repository over SSL.

Valid values: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

pgsql.verify_restore.port

Default value: 8061

Port used to verify the integrity of the PostgreSQL database. See tsm maintenance backup for more information.

ports.blocklist

Version: Added in version 2021.1

Default value: no ports blocked in the range used for automatic port assignment.

Used to specify ports within the port assignment range that should not be used by Tableau when dynamically assigning ports. This is useful when you know that another application is using a port within the range. Separate multiple ports with commas, for example:

tsm configuration set -k ports.blocklist -v 8000,8089, 8090

For more information on using the ports.blocklist key, see Blocking specific ports within the range

recommendations.enabled

Default value: true

Controls the recommendations feature, which powers recommendations for data sources and tables (for Tableau Desktop) and recommendations for views (for Tableau Server). Recommendations are based on the popularity of content and on content used by other users determined to be similar to the current user.

searchserver.connection_timeout_milliseconds

Version: Added in version 2019.1. Deprecated in version 2022.3. Retired in version 2023.3.

Default value, in milliseconds: 100000

Specifies, in milliseconds, the amount of time Search & Browse clients will wait to establish a connection to the Search & Browse server.

On especially busy Tableau Server computers, or if you see log errors "Failed zookeeper health check. Refusing to start SOLR." increase this value.

For more information, see Client session timeouts.

searchserver.index.bulk_query_user_groups

Version: Retired in version 2022.3.

Default value: true

Specifies whether querying of site users is done in bulk when importing or deleting users with a CSV file. When set to true (the default), indexing is done as in bulk.

searchserver.javamemopts

Version: Added in version 2019.1. Retired in 2023.3

Default value: -Xmx512m -Xms512m -XX:+ExitOnOutOfMemoryError -XX:-UsePerfData

Determines JVM options for SOLR.

Of all configurable options, the maximum heap memory, configured by the -Xmx parameter, is the most important when tuning the searchserver. In most cases this should be set as high as is possible, up to 24 GB, based on available physical memory on the Tableau Server computer. To change only the max heap memory, specify the entire default string but only change the value for -Xmx.

Valid values for -Xmx depend on available memory on the Tableau Server computer, but cannot be greater than 24 GB. For more information, see Search & Browse Max Heap Memory.

searchserver.startup.zookeeper_healthcheck_timeout_ms

Version: Added in version 2020.1. Retired in version 2023.3.

Default value, in milliseconds: 300000

Specifies, in milliseconds, the amount of time Tableau Server should wait for a successful Zookeeper health check on startup.

On especially busy Tableau Server computers, or if you see log errors "Failed zookeeper health check. Refusing to start SOLR." increase this value.

For more information, see Zookeeper connection health check timeout at startup.

searchserver.zookeeper_session_timeout_milliseconds

Version: Retired in version 2022.3.

Default value, in milliseconds: 100000

Specifies, in milliseconds, the amount of time Search & Browse clients will wait to establish a connection to the Coordination Service (Zookeeper).

For more information, see Client session timeouts.

ServerExportCSVMaxRowsByCols

Version: Added in version 2020.3.

Default value: 0 (no limit)

Specifies the maximum number of cells of data that can be downloaded from View Data into a CSV file. By default, there is no limit. Specify the number of cells. For example to set a limit of 3 million: 

tsm configuration set -k ServerExportCSVMaxRowsByCols -v 3000000 

tsm pending-changes apply

ssl.ciphersuite

Default value: HIGH:MEDIUM:!EXP:!aNULL:!MD5:!RC4:!3DES:!CAMELLIA:!IDEA:!SEED

Specifies the cipher algorithms that are allowed for SSL for Gateway.

For acceptable values and formatting requirements, see SSLCipherSuite(Link opens in a new window) on the Apache website.

ssl.client_certificate_login.blocklisted_signature_algorithms

Default value:

• Version 2020.4.0: 

  sha1withrsaencryption,
sha1withrsa

• Version 2020.4.1 and later:

  sha1withrsaencryption,
sha1withrsa,
sha1withrsaandmgf1,
sha1withdsa,
sha1withecdsa

The default value blocks certificates with the SHA-1 signing algorithm. Specifies the client signing algorithms that are blocked for SSL. To disable blocking of all signature algorithms, run this key with an empty set of quotes.

For more information about this key, see the Knowledge Base article, Mutual SSL Fails After Upgrading if Certificates Signed with SHA-1(Link opens in a new window).

ssl.client_certificate_login.min_allowed.elliptic_curve_size

Default value: 256

Specifies the minimum elliptic curve size required for ECDSA client certificates that are authenticating with Tableau Server over mutual SSL If a client presents an ECDSA client certificate that does not satisfy this minimum curve size, the authentication request will fail.

This option was introduced in Tableau Server version 2021.1.

ssl.client_certificate_login.min_allowed.rsa_key_size

Default value: 2048

Specifies the minimum key size for RSA client certificates that are authenticating with Tableau Server over mutual SSL If a client presents an RSA client certificate that does not satisfy this minimum key size, the authentication request will fail.

This option was introduced in Tableau Server version 2021.1.

ssl.protocols

Default value: all +TLSv1.2 -SSLv2 -SSLv3 -TLSv1.3

Specifies the SSL protocols that Tableau Server supports for TLS connections for Gateway. Acceptable values derive from the Apache SSLPrtocol Directive(Link opens in a new window). We recommend following SSL protocol configuration as described in Security Hardening Checklist.

storage.monitoring.email_enabled

Default value: false

Controls whether email notifications are enabled for server disk space monitoring. By default, email notifications are enabled. To enable notifications for disk space monitoring, set this to true.

SMTP must be configured for notifications to be sent. For details, see Configure SMTP Setup.

storage.monitoring.warning_percent

Default value: 20

Warning threshold of remaining disk space, in percentage of total disk space. If disk space falls below this threshold, a warning notification is sent.

storage.monitoring.critical_percent

Default value: 10

Critical threshold of remaining disk space, in percentage of total disk space. If disk space falls below this threshold, a critical notification is sent.

storage.monitoring.email_interval_min

Default value: 60

How often, in minutes, that email notifications should be sent when disk space monitoring is enabled and a threshold is crossed.

storage.monitoring.record_history_enabled

Default value: true

Determines whether free disk space history is saved and available to view in Administrative Views. To disable history storage for monitoring, set storage.monitoring.record_history_enabled to false.

svcmonitor.notification.smtp.enabled

Default value: false

Controls whether email notifications are enabled for server process events. By default notifications are sent when processes go down, fail over or restart. To enable server process notifications, set this to true.

SMTP must be configured for notifications to be sent. For details, see Configure SMTP Setup.

svcmonitor.notification.smtp.mime_use_multipart_mixed

Version: Added in version: 2020.1.8, 2020.2.5, 2020.3.1

Default value: false

Controls whether subscription HTML MIME attachments are sent as multipart/related (the default) or multipart/mixed.

In rare cases, email clients may not properly parse emails sent by Tableau Server. Many times this can be fixed by setting this property to true. Known clients include iOS Mail and Microsoft Outlook (when paired with Exchange S/MIME encryption).

tabadmincontroller.auth.expiration.minutes

Default value: 120

Controls how long session cookies are valid. By default this is set to 120 minutes. This value also determines how long the embedded credentials in a node bootstrap file are valid. For more information, see tsm topology nodes get-bootstrap-file.

tdsservice.log.level

Version: Added in version 2020.3.0

Default value: info

The logging level for the Data Source Properties service. This is dynamically configurable, so if you are only changing this you do not have to restart Tableau Server. For more information, see Change Logging Levels.

tomcat.useSystemProxies

Default value: false

Specifies whether tomcat components (OpenID) require access to the forward proxy configuration on the local Windows operating system. See Configure Tableau Server for OpenID Connect.

tomcatcontainer.log.level

Default value: info

The logging level for microservices in the Interactive Microservice Container and Non-Interactive Microservice Container. This is dynamically configurable starting in version 2020.4, so if you are only changing this, you do not have to restart Tableau Server. For more information, see Change Logging Levels.

tsm.log.level

Default value: info

Logging level for TSM services. These logs include information that can be useful if you have problems with TSM services: Administration Agent, Administration Controller, Client File Service, Cluster Controller, Service Manager and Licence Service. This configuration key does not change the logging level for Coordination Service or for maintenance processes. For more information, see Change Logging Levels and Tableau Server Processes.

tsm.controlapp.log.level

Default value: info

Logging level for control_<app> services. These logs include information that can be useful if you are running into problems starting or reconfiguring a TSM or Tableau Server process. For more information, see Change Logging Levels.

usernotifications.reap_after_days

Default value: 30

Number of days after which a user notification will be deleted from the server.

vizportal.adsync.update_system_user

Default value: false

Specifies whether email addresses and display names of users are changed (even when changed in Active Directory) when an Active Directory group is synchronised in Tableau Server. To ensure that user email addresses and display names are updated during synchronisation, set vizportal.adsync.update_system_user to true, and then restart the server.

vizportal.alwaysUseEmbeddedShareLinks

Version: Added in version 2021.3.0

Default value: false

Specifies whether the Copy Link option should include the "embed=y" parameter. Starting in version 2019.4, by default, it does not include this parameter. Setting this configuration key to true changes the behaviour so that the "embed=y" parameter is included. For details about using the Copy Link option to share links for embedding in web pages, see Embed Views into Webpages(Link opens in a new window) in the Tableau Desktop and Web Authoring Help.

vizportal.art_skip_list

Version: Added in version 2024.2.

Default value: null

Use this configuration key to specify aspects of Tableau Server functionality that do not use Activity and Resource Tracing (ART) and will generate large amounts of unnecessary data while ART is enabled.

This key is used together with vizportal.log_art_java and vizportal.enable_art for troubleshooting issues with Application Server (VizPortal). When set to [need info here about what it gets set to.] To learn how to use this configuration setting, see Troubleshooting problems with Application Server.

vizportal.csv_user_mgmt.index_site_users

Version: Deprecated in version 2022.3. Retired (removed entirely) in version 2023.3.

Default value: true

Specifies whether indexing of site users is done user by user when importing or deleting users with a CSV file. When set to true(the default) indexing is done as each user is added or deleted. To delay the indexing of the site users until after the entire CSV file has been processed, set this to false.

vizportal.csv_user_mgmt.bulk_index_users

Version: Deprecated in version 2022.3. Retired (removed entirely) in version 2023.3.

Default value: false

Specifies whether indexing of site users is done in bulk when importing or deleting users with a CSV file. When set to false (the default), indexing is done individually. To have the indexing done in bulk after the CSV file has been processed, set this to true.

vizportal.enable_art

Version: Added in version 2024.2.

Default value: false

This configuration key is used together with vizportal.log_art_java and vizportal.art_skip_list for troubleshooting issues with Application Server (VizPortal). When set to true, this enables Activity and Resource Tracing in Application Server. To learn how to use this configuration setting, see Troubleshooting problems with Application Server.

vizportal.log_art_java

Version: Added in version 2024.2.

Default value: false

This configuration key is used together with vizportal.enable_art and vizportal.art_skip_list for troubleshooting issues with Application Server (VizPortal). When set to true, this enables Activity and Resource Tracing in Application Server. To learn how to use this configuration setting, see Troubleshooting problems with Application Server.

vizportal.oauth.connected_apps.max_expiration_period_in_minutes

Version: Added in version 2021.4.

Default value: 10

The maximum period of time, in minutes, the JSON web token (JWT) is valid. At the time the JWT is verified, Tableau Server checks that the time period specified in the JWT doesn’t exceed this default value. This setting is used when a Tableau-connected app has been configured on Tableau Server using the Tableau REST API(Link opens in a new window).

For example, to change maximum period to 5 minutes, run the following command:

tsm configuration set -k vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes -v 5

vizportal.oauth.external_authorization.enabled

Version: Added in version 2021.4.

Default value: false

In Tableau Server 2024.2 and later, the Enable connected apps option is enabled for Tableau Server. In Tableau Server 2023.2 and earlier, it is specified whether the Enable OAuth Access for Embedding Content option is enabled for Tableau Server.

Use this option to register an external authorisation server (EAS) with Tableau Server so that you can enable application integration. For more information, see Configure Connected Apps with OAuth 2.0 Trust.

To enable this option, run the following command:

tsm configuration set -k vizportal.oauth.external_authorization.enabled -v true

vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms

Version: Added in version 2021.4.

Default value: ES256K

When an external authorisation server (EAS) is registered or connected app is configured, you can use this command to specify the signing algorithm used in JSON web token (JWT) header. For more information, see Configure Connected Apps with OAuth 2.0 Trust or Use Tableau Connected Apps for Application Integration.

For example, if needed, you might run the following command to remove the algorithm:

tsm configuration set - k vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms -v

Important: The example command above allows unsafe signing algorithms and should only be used to troubleshoot errors.

vizportal.oauth.external_authorization_server.issuer

Version: Added in version 2021.4.

Default value: null

Required. Use this command to specify the issuer URL. The issuer URL is required to register the external authorisation server (EAS) with Tableau Server. For more information, see Configure Connected Apps with OAuth 2.0 Trust.

For example, if your EAS is Okta, you might run a command similar to the following:

tsm configuration set -k vizportal.oauth.external_authorization_server.issuer -v "https://dev-12345678.okta.com/oauth2/abcdefg9abc8eFghi76j5"

vizportal.oauth.external_authorization_server.jwks

Version: Added in version 2021.4.

Default value: null

When an external authorisation server (EAS) is registered, you can use this command to specify the JSON web key set (JWKS) URL. The JWKS URL is required if the identity provider (IdP) doesn’t expose the external authorisation server metadata endpoint.

For example, if your IdP is Amazon Cognito, you might run a command similar to the following:

tsm configuration set -k vizportal.oauth.external_authorization_server.jwks -v "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_Ab129faBb/.well-known/jwks.json"

vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes

Version: Added in version 2021.4.

Default value: 10

The maximum period of time, in minutes, the JSON web token (JWT) is valid. At the time the JWT is verified, Tableau Server checks that the time period specified in the JWT doesn’t exceed this default value. This setting is used when an EAS has been registered with Tableau Server. For more information, see Configure Connected Apps with OAuth 2.0 Trust.

For example, to change maximum period to 5 minutes, run the following command:

tsm configuration set -k vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes -v 5

vizportal.openid.full_server_request_logging_enabled

Default value: false

Specifies whether to do full logging of OpenID activity.

Set this to true when troubleshooting OpenID Connect issues to gather more detailed logs and allow you to better troubleshoot.

As with all logging-related configurations, we recommend that after you have finished troubleshooting and collecting logs, you reset this key to its default (false). This limits the amount of information logged and keeps the log file sizes to a minimum.

vizportal.password_reset

Version: Replaces features.PasswordReset in version 2024.2.

Default value: false

Applies only to servers that use local authentication. Set to trueto let users reset their passwords with a "Forgot password" option on the sign-in page.

vizportal.rest_api.cors.enabled

Default value: false

Controls whether Tableau Server allows Cross Origin Resource Sharing (CORS). When set to true, the server allows web browsers to access the Tableau REST API endpoints. You can use this option and the REST API to create custom portals. By default, this functionality is not enabled. To specify which origins (sites) have access, use the vizportal.rest_api.cors.allow_origin option. Only the origins specified with this option are allowed to make requests to the Tableau Server REST API. For more information, see Enabling CORS on Tableau Server.

vizportal.site_user_group_count_enabled

Version: Added in version 2022.3.5 and later, 2023.1.0 and later.

Default value: false

Controls whether Site Users page will include a column showing the group count for each user.

vizqlserver.force_maps_to_offline

Version: Added in version 2020.4.0.

Default value: false

Determines whether Tableau Server runs in offline mode for maps. This is useful in disconnected environments where access to the internet and the map server is restricted. To enable offline mode for maps, set this value to true. For more information about installing and configuring Tableau Server in an environment without internet access, see Install Tableau Server in a Disconnected (Air-Gapped) Environment.

wgserver.authentication.legacy_identity_mode.enabled

Version: Added in version 2022.1

Default value: false for Tableau Server 2022.1 and later. For pre-2022.1 Tableau Server deployments upgraded to 2022.1 or later, default value is true.

Set to false to use identity pools.

For more information, see Troubleshoot identity pools.

wgserver.authentication.identity_pools.default_pool_description

Version: Added in version 2023.1

Default value: Null

Optionally, you can add a description for the initial pool (TSM configured) to the Tableau Server landing page and is visible to all users. When one or more identity pools are created, this description is added below the primary sign-in option and can be used to help guide users that belong to the initial pool (TSM configured) to the correct sign-in option.

For example, to add a “Regular employees sign in here” description, you can use the following command:

tsm configuration set -k wgserver.authentication.identity_pools.default_pool_description -v “Regular employees sign in here"

Note: The initial pool (TSM configured) description is different from the Sign-In Customisation note. The Sign In Customisation note is displayed on the Tableau Server landing page below all sign-in options and on the page where your initial pool (TSM configured) users enter their username and password.

wgserver.domain.accept_list

Version: This was added in version 2020.4.0 and replaces wgserver.domain.whitelist.

Default value: null

Allows connection from Tableau Server to secondary Active Directory domains. A secondary domain is one that Tableau Server connects to for user synchronisation, but is a domain where Tableau Server is not installed. Tableau Server will attempt to connect to secondary domains for user and group synchronisation. In some cases, Tableau Server may be unable to connect to the secondary domain, which will result in the error, "Domain not in accept list (errorCode=101015)."

Setting the wgserver.domain.accept_list option is required by a fix for the security vulnerability, [Important] ADV-2020-003: Tableau Server Forced Authentication(Link opens in a new window). As of February 2020, the fix for this vulnerability is included in all latest versions and maintenance releases of Tableau Server.

To set this option, enter the secondary domain enclosed by double-quotes. Multiple domains must be separated by a comma and a space. For example, tsm configuration set -k wgserver.domain.accept_list -v "example.org, domain.com".

Wildcard functionality is not supported. For example, if Tableau connects to sub1.example.org and sub2.example.org, then both domains must be added.

Updating the wgserver.domain.accept_list option overwrites the existing value. Therefore, if you are adding a new domain to an existing set of domains stored in the value, include all existing domains with the new domain when you set the option. You can retrieve the full list of existing domains by running tsm configuration get –k wgserver.domain.accept_list.

wgserver.domain.allow_insecure_connection

Default value: False

This setting only applies to Windows. This option specifies whether Tableau Server will connect to Active Directory over an unencrypted channel. The default value, False, enforces an encrypted channel. If the LDAP channel is not encrypted, then Tableau Server will not connect to Active Directory.

Your Active Directory infrastructure should manage certificates and trust with domain-joined computers. As such, the channel communication between Tableau Server and Active Directory resources should be encrypted. We do not recommend allowing unencrypted communications with Active Directory, as this configuration is vulnerable to man-in-the-middle attacks.

If you are upgrading to Tableau Server 2021.2 or later and your LDAP channel is not encrypted, upgrade will fail. You can run this command to allow an insecure connection on older versions of Tableau Server before you upgrade. If you are running this command on a version prior to 2021.2, you must include the --force-keys option with the command.

wgserver.domain.fqdn

Default value: value of %USERDOMAIN%

The fully qualified domain name of the Active Directory server to use.

wgserver.domain.password

Default value: null

Specifies password for the user account that is used for LDAP connection. See External Identity Store Configuration Reference.

wgserver.domain.username

Default value: null

Specifies name for the user account that is used for LDAP connection. See External Identity Store Configuration Reference.

wgserver.domain.allowlist

Important: This key has been deprecated as of version 2020.4.0. Use wgserver.domain.accept_list instead.

Default value: null

Allows connection from Tableau Server to secondary Active Directory domains. A secondary domain is one that Tableau Server connects to for user synchronisation, but is a domain where Tableau Server is not installed. Tableau Server will attempt to connect to secondary domains for user and group synchronisation. In some cases, Tableau Server may be unable to connect to the secondary domain, which will result in the error, “Domain not in allowlist (errorCode=101015)”.

wgserver.ignore_domain_in_username_for_matching

Version: Added in versions 2021.4.21, 2022.1.17, 2022.3.9 and 2023.1.5

Default value: false

When you enable SAML, you can configure Tableau Server to ignore the domain portion of the SAML username attribute when matching the identity provider (IdP) user name to a user account on Tableau Server. You might ignore the domain portion of the username attribute when you already have users defined in Tableau Server that match the prefix portion of a username attribute but not the domain portion of the username attribute. For more information, see the Ignore domain when matching SAML username attribute section in the SAML Requirements topic.

For example, to ignore the domain name in the SAML username attribute, run the following command:

tsm configuration set -k wgserver.ignore_domain_in_username_for_matching -v true

Important:

• We do not recommend ignoring the domain name without taking precautions. Specifically, verify that user names are unique across the configured domains that you've created in your IdP.
• This command only works in Tableau Server deployments that are in legacy-identity-mode or deployments that have not been updated through the identity migration(Link opens in a new window) to use the Identity Service.

wgserver.saml.blocklisted_digest_algorithms

Version: Added in version 2021.1.

Default value: SHA1

Specifies the hashing algorithms that are not allowed for any relevant SAML certificate signatures or SAML assertion digest method or signature methods . When set, certificates or assertions that are signed & hashed with a blocklisted algorithm will be rejected and fail.

There are multiple places where SHA-1 could be used on both the Tableau and IdP side. For example:

• Certificates uploaded with TSM that are used by Tableau Server to sign the request that is sent to the IdP.
• Certificates in the IdP metadata used to verify the AuthnResponse (signature) received from the IdP using the public key in the Certificate.
• Incoming assertions signed and hashed with SHA-1 (DigestMethod set to SHA-1 and SignatureMethod set to SHA-1).

The default value was changed to (SHA1 in Tableau Server 2021.2. For more information about upgrading to 2021.2 with SAML configured, see the Knowledge Base article, Tableau Server Using SAML Authentication Fails to Start or Rejects Login After Upgrade to Tableau Server 2021.2.

wgserver.saml.forceauthn

Version: Added in version 2019.3.

Default value: false

When set to true, if the Tableau user session expires, Tableau Server will re-authenticate the user with the IdP. This option can also be used to ask the IdP to prompt the user for re-authentication, even if the user has an active IdP session.

wgserver.saml.min_allowed.elliptic_curve_size

Default value: 256

Version: Added in version 2021.1 but did not include a default value. In 2021.2, the default value was set to 256.

This option specifies the minimum allowed ECDSA curve size for the certificate used for SAML authentication. If you upload a certificate that has an ECDSA curve size less than 256, TSM will log an error when you apply changes.

If you are upgrading to Tableau Server 2021.2 or later and your SAML certificate uses an ECDSA curve size less than 256, Tableau Server will not start after upgrading. We recommend uploading a new certificate with 256 (or larger) ECDSA curve size before upgrading. Alternatively, you can run this command to set a lower ECDSA curve size on older versions (pre-2021.1) of Tableau Server before you upgrade. If you are running this command on a version prior to 2021.1, you must include the --force-keys option with the command. For more information about upgrading to 2021.2 with SAML configured, see the Knowledge Base article, Tableau Server Using SAML Authentication Fails to Start or Rejects Login After Upgrade to Tableau Server 2021.2.

wgserver.saml.min_allowed.rsa_key_size

Default value: 2048

Version: Added in version 2021.1 but did not include a default value. In 2021.2, the default value was set to 2048.

This option specifies the minimum allowed RSA key length for the certificate used for SAML authentication. If you upload a certificate that has an RSA key length less than 2048, TSM will log an error when you apply changes.

To run SAML authentication with a 1024 RSA key length (not recommended), set this value to 1024.

If you are upgrading to Tableau Server 2021.2 or later and your SAML certificate uses a key length less than 2048, Tableau Server will not start after upgrading. We recommend uploading a new certificate with 2048 (or larger) key length before upgrading. Alternatively, you can run this command to set a lower key strength on older versions (pre-2021.1) of Tableau Server before you upgrade. If you are running this command on a version prior to 2021.1, you must include the --force-keys option with the command. For more information about upgrading to 2021.2 with SAML configured, see the Knowledge Base article, Tableau Server Using SAML Authentication Fails to Start or Rejects Login After Upgrade to Tableau Server 2021.2.