Tableau Server on Windows Help

Use the tsm topology commands to prepare File Store nodes for safe removal or to put them back into read-write mode. You can also initiate a repository failover, get a list of nodes or ports, get the bootstrap configuration file required to add additional nodes to your cluster, remove nodes, configure external repository and external File Store.

Important: When making changes to topology, you need to apply those pending changes for the changes to take effect. For more information, see tsm pending-changes.

tsm topology cleanup-coordination-service

Note: Beginning with version 2020.1.0, all coordination service ensemble commands require input for a "y/n" prompt confirming that a server restart will take place. To run these commands without input, include the --ignore-prompt option.

Use the tsm topology cleanup-coordination-service command to remove the non-production Tableau Server Coordination Service ensemble after you deploy a new ensemble. This command removes the old Coordination Service instances on all nodes in the non-production Coordination Service ensemble and is required after you deploy a new Coordination Service ensemble. To learn more about Coordination Service ensembles, see Deploy a Coordination Service Ensemble.

In version 2020.1.0 and later, the tsm topology deploy-coordination-service command also removes the old ensemble. There is no need to run this command separately unless the deployment fails.

Synopsis

tsm topology cleanup-coordination-service [option] [global options]

Option

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish. Default value is 2700 (45 minutes).

tsm topology deploy-coordination-service

Note: Beginning with version 2020.1.0, all coordination service ensemble commands require input for a "y/n" prompt confirming that a server restart will take place. To run these commands without input, include the --ignore-prompt option.

You can use the tsm topology deploy-coordination-service command to deploy the Tableau Server Coordination Service. This command deploys a Coordination Service ensemble, which is a set of Coordination Service instances that run on specified nodes in your server cluster. To learn more about Coordination Service ensembles, including how many nodes in your cluster should have a Coordination Service instance, see Deploy a Coordination Service Ensemble.

In version 2020.1.0 and later, the tsm topology deploy-coordination-service command also removes the old ensemble. There is no need to run the cleanup-coordination-service command separately.

Synopsis

tsm topology deploy-coordination-service --nodes <nodeID,nodeID,...> [option] [global-options]

Options

-n, --nodes <nodeID,nodeID,...>

Required.

Node IDs of nodes to include in the new Coordination Service ensemble, separated by commas. You can specify 1, 3, or 5 Coordination Service nodes, depending on the total number of nodes in your cluster. For more information, see The Coordination Service Quorum.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish. Default value is 2700 (45 minutes).

tsm topology external-services gateway disable [options] [global options]

tsm topology external-services gateway enable [options] [global options]

tsm topology external-services gateway update [option] [global options]

tsm topology external-services list

Use the tsm topology external-service-list command to get a the service that is used for Tableau Server External Repository. For example, if you have configured Tableau Server to use Amazon RDS, you will see the following message:

These externally configured services are in use by Tableau Server:

- pgsql

Synopsis

tsm topology external-service list [global options]

Option

There are no options for this command.

tsm topology external-services repository disable -n nodeN

Use the tsm topology external-services repository disable command to stop using the external repository and reconfigure the installation to use a local repository. This will migrate the data to a local repository and configure Tableau Server to use the local repository.

Synopsis

tsm topology external-services repository disable -n nodeN

Option

-n, --node-name <nodeID>

Required.

Specifies the node ID of the node where the repository should be moved to.

Important: This does not stop or delete the RDS instance. For more information on how to delete an RDS instance, see Deleting a DB Instance(Link opens in a new window) on the AWS web site.

tsm topology external-services repository enable

Use the tsm topology external-services repository enable command to configure Tableau Server to use an external repository. This command can be used during installation of a new Tableau Server to configure the external repository. If this command is run on an already existing and running Tableau Server, it will migrate the data from the local node to the external repository and configure Tableau Server to use the external repository after the migration is complete.

Synopsis

tsm topology external-services repository enable -f <filename>.json -c <ssl certificate file>.pem

Options

--f <file name>

Required.

Full path and file name where the configuration file is saved. For more information, see Re-Configure Tableau Server Repository.

--c <ssl certificate file>

Required for versions 2021.2 and 2021.2.1. Optional for versions 2021.2.2 and later.

For SSL configurations, download the certificate file and specify the file for use with this option.

1. Amazon RDS: See Using SSL to Encrypt the Connection to a DB Instance(Link opens in a new window).

2. Azure Database: See Configure TLS connectivity for Azure Database for PostgreSQL(Link opens in a new window).
3. Stand-alone PostgreSQL Instance: See Configure SSL.

--no-ssl

Optional. This option is available in version 2021.2.2 and later.

This means SSL is not required when connecting to the External Repository. If you do not need to use encrypted connections, you must also configure the External Repository to allow unencrypted connections. When you use this option, connections will be encrypted if the external repository is configured to support TLS/SSL connections. Otherwise, Tableau Server will use non-encrypted connections.

Skips the check to see if the external repository is already configured for use with Tableau Server. This option is typically not recommended, as it may lead to the same repository being used by multiple Tableau Server installations, which can cause errors. This option may be useful for testing or disaster recovery purposes.

--skip-state-check

Optional. This option is available in version 2022.3.0 and later.

Skips the check to see if the external repository is already configured for use with Tableau Server. This option may be useful for testing or disaster recovery purposes but is not recommended for normal use, as it may result in the same repository being used by multiple Tableau Server installations.

tsm topology external-services repository replace-host

This command updates Tableau Server configuration settings to use the specified external repository. Use the tsm topology external-services repository replace-host command to reconfigure Tableau Server to use the new external repository immediately without moving data to it from your current external repository. You may need to manually migrate the data. You should only do this after you have fully evaluated and understand the impact of the potential data loss.

This command can be used in the following scenarios:

• Planned expiration of the SSL certificates used by RDS instances: RDS instances need to be updated with the new certificates, and Tableau Server needs to be configured to use the new certificate file to connect to the RDS instance.

• Disaster recovery: Use this to connect to a new RDS instance in disaster recovery scenarios. For more information, see Create a PostgreSQL DB Instance on AWS Relational Database Service (RDS)

Synopsis

tsm topology external-services repository replace-host -f <filename>.json -c <ssl certificate file>.pem

Options

-f <file name>

Required.

Full path and file name where the configuration file is saved. For more information, see Re-Configure Tableau Server Repository.

-c <ssl certificate file>

Optional.

The certificate file is the certificate to be imported to allow connections to the instance. For RDS, this is the CA cert used to sign the certificate of the instance. This is usually the latest root certificate rds-ca-XXXX-root.pem file. Use this parameter to update Tableu server if the certificate has changed on the RDS instance.

For more information, see Using SSL/TLS to Encrypt a Connection to a DB Instance.

For more information on how to get the .pem file, see Using SSL to Encrypt a Connection to a DB Instance(Link opens in a new window).

--ignore-prompt

Optional.

Run this command without prompts.

tsm topology external-services storage disable [options] [global options]

tsm topology external-services storage enable [options] [global options]

tsm topology external-services storage switch-share [option] [global options]

tsm topology failover-repository

You can use the tsm topology failover-repository to manually initiate a repository failover from the current active repository to the second, passive repository.

The tsm topology failover-repository command is persistent. The failover repository remains the active repository until you issue the command again, or, if Tableau Server is configured for it, until automatic failover occurs. If you have a preferred active repository configured, use the --preferred option to switch back to that repository. For more information about configuring a preferred active repository, see Tableau Server Repository.If Tableau Server is configured for high availability, failover of the repository is automatic when necessary. Use the failover-repository command to manually fail over the repository.

Synopsis

tsm topology failover-repository --preferred | --target <node_id> [global options]

Options

-r, --preferred

Required if -t or --target is not used.

Use the configured preferred node as the target for repository failover.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish. Default value is 1800 (30 minutes).

-t, --target <node_id>

Required if -r or --preferred is not used.

The node id of the target node onto which failover will occur. Find the node id by using the tsm topology list-nodes command.

tsm topology filestore decommission

You must use the tsm topology filestore decommission command to prepare a file store node or nodes for safe removal. This command puts the specified nodes into read-only mode and ensures there is no unique content on the specified nodes.

If decommissioning results in a single file store node, you must use the --override option or the decommission will fail.

Synopsis

tsm topology filestore decommission --nodes <nodeID,nodeID,...> [options] [global options]

Options

-n, --nodes <nodeID,nodeID,...>

Required.

List of one or more nodes to decommission, specified by node ID and separated by commas.

--delete-filestore

Optional.

Forces the removal of the file store, even if it has not been decommissioned. You should only use this option if the node the file store is on is in an error state and decommissioning cannot be done. Any unique files on the node will be permanently deleted.

-o, --override

Optional.

Overrides warnings or failures that would normally occur if removing the target File Store node would reduce the number of remaining file store nodes to one. This option cannot be used with the --delete-filestore option.

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish. Default value is 1800 (30 minutes).

tsm topology filestore recommission

Use the tsm topology filestore recommission command to revert any decommissioned nodes back to read-write mode.

Synopsis

tsm topology filestore recommission --nodes <nodeID,nodeID,...> [global options]

Options

-n, --nodes <nodeID,nodeID,...>

Required.

List of one or more nodes to recommission, specified by node ID and separated by commas.

tsm topology list-nodes

Display the nodes in the cluster and (optionally) the services on each node.

Synopsis

tsm topology list-nodes [options] [global options]

Options

tsm topology list-ports

Display the ports in the cluster.

Synopsis

tsm topology list-ports [options] [global options]

Options

--node-name <nodeID>

Optional.

Specify the node to list ports for.

--service-name

Optional.

Specify the service to list ports for.

tsm topology node-nickname list

Display the node nicknames for nodes in the cluster.

Synopsis

tsm topology node-nickname list [options] [global options]

Options

--nodes <nodeID,nodeID,...>

Optional.

Specify the node IDs of the nodes to list with nicknames.

tsm topology node-nickname remove

Remove the nickname from the specified node or nodes.

Synopsis

tsm topology node-nickname remove [options] [global options]

Options

--all

Required if --nodes is not specified.

Remove the nicknames from all nodes in the cluster.

--nodes <nodeID,nodeID,...>

Required if --all is not specified.

Specify the node ID of the node or nodes whose nicknames should be removed.

tsm topology node-nickname set

Set the nickname for the specified node.

Synopsis

tsm topology node-nickname set [options] [global options]

Options

-id, --node <nodeID>

Required.

Specify the node to set the nickname for.

-nn, --nickname <name>

Required.

The nickname for the specified node.

tsm topology nodes get-bootstrap-file

You can use the tsm topology nodes get-bootstrap-file command to get the bootstrap file that is required to add a new node to the cluster.

Synopsis

tsm topology nodes get-bootstrap-file --file <path\file>.json [global options]

Options

-f,--file <file>

Required.

Full path and file name where the configuration file will be saved. If a duplicate file exists it will be overwritten.

-nec,--no-embedded-credential

Optional.

Added in version 2019.3.

By default embedded credentials are included in the bootstrap file. Use this option if credentials should not be included in the bootstrap file. Embedded credentials are temporary, and expire based on the value of the tabadmincontroller.auth.expiration.minutesconfiguration key, by default 120 minutes.

Note: You can disable the ability to include embedded credentials at the server level, using a configuration option. For more information, see features.PasswordlessBootstrapInit.

tsm topology remove-nodes

Remove nodes from the cluster.

To complete removal of a node, you also must run the tsm pending-changes apply command. Some scenarios require that you move or redeploy processes before removing nodes. See Remove a Node.

If you remove a node and want to re-add it to the cluster, you need to first run the obliterate script to clean Tableau off it, then reinstall the node using the normal process for adding a new node. For more information, see Remove Tableau Server from Your Computer and Install and Configure Additional Nodes.

Note: To remove a node from a cluster it must have been configured with a process at some point in the past. If you are removing a node on which you've not configured any processes, then you must add a process on it, run tsm pending-changes apply, and then remove the node.

Synopsis

tsm topology remove-nodes --nodes <nodeID,nodeID,...> [global options]

Options

-n, --nodes <nodeID,nodeID,...>

Required.

Specify the node or nodes to remove. If specifying multiple nodes, separate node IDs with a comma.

tsm topology set-node-role

Set the Backgrounder and Extract Queries node roles. This determines the type of tasks that will be performed on the nodes. The following node roles can be useful if you have a multi-node cluster. Different node roles may require licences for Advanced Management or Data Management, or for both. For more information about licence requirements, see Workload Management through Node Roles.

Note: Making configurations to node roles require a restart of the server and will require some downtime. For more information, see tsm pending-changes.

Synopsis

tsm topology set-node-role [options] [global options]

Options

-n, --nodes <nodeID,nodeID,...>

Required.

List of one or more nodes to set node roles for, specified by node ID and separated by commas and without spaces between nodes.

-r --role <all-jobs,flows,no-flows,extract-refreshes,subscriptions,extract-refreshes-and-subscriptions,no-extract-refreshes,no-subscriptions,no-extract-refreshes-and-subscriptions,extract-queries,extract-queries-interactive>

Required

Sets the role for the nodes specified. The valid values for this option are:

• all-jobs: Backgrounder will run all types of jobs.

• flows :Backgrounder will run only flow run jobs.

• no-flows: Backgrounder will not run flow run jobs.

• extract-refreshes: Backgrounder will run only extract refresh jobs. This includes, incremental refreshes, full refreshes, encryption and decryption of all extracts including extracts that flow outputs generate.

• subscriptions: Backgrounder will run only subscription jobs.

• extract-refreshes-and-subscriptions: Backgrounder will run extract-refreshes, encryption and decryption of all extracts including extracts that flow outputs create and subscription jobs.

• no-extract-refreshes: Backgrounder will run all jobs except extract-refreshes, extract encryption and decryption including extracts created from flow outputs.

• no-subscriptions: Backgrounder will run all jobs except subscriptions.

• no-extract-refreshes-and-subscriptions: Backgrounder will run all jobs except extract-refreshes, encryption and decryption of all extracts including extracts created from flow outputs and subscriptions.

• extract-queries: The nodes selected will run as all-jobs and will prioritise the processing of extract queries.

• extract-queries-interactive: The nodes selected will run as all-jobs and will prioritise the processing of interactive extract queries, such as those that run when a user is looking at their screen and waiting for an extract-based dashboard to load. This is an advanced setting and it should only be used if the cluster has a heavy subscription and alert job workload that causes users to experience degraded performance on viz load times that run around the same time as scheduled loads.

• system: Backgrounder will run only system maintenance jobs that interact with other Tableau Server processes, such as cleaning crashed jobs, reaping database events and syncing Active Directory.

• no-system: Backgrounder will run all jobs except system maintenance jobs.

tsm topology set-ports

Set the ports for a service instance.

Synopsis

tsm topology set-ports --node-name <nodeID> --port-name <port_name> --port-value <port_value> [options] [global options]

Options

-i, --instance <instance_id>

Optional.

Specifies the instance id of the service. Defaults to 0 (zero) if not specified.

-n, --node-name <nodeID>

Required.

Specifies the node ID of the node.

-pn, --port-name <port_name>

Required.

The name of the port to be set, in this format: service_name:port_type. If no port type is specified, the primary port is assumed. For port name syntax, see Dynamically mapped ports.

-pv, --port-value <port_value>

Required.

The port to set.

-r, --restart

Optional.

Suppress the prompt for restart and restart Tableau Server when necessary.

tsm topology set-process

Set the number of instances of a process on a node. If a node already has the specified process, the number is updated to match the specified count.

• You can only set one process at a time. If you specify more than one process, any process after the first one will be silently ignored.
• You must set a process one node at a time. If you specify more than one node, the command will display an "invalid node name" error.

When you update the number of processes on nodes, you also need to apply pending changes. In most cases this also requires a server restart (you will be prompted), but there are special cases where you can make dynamic topology changes without needing to restart the server. For more information, see Tableau Server Dynamic Topology Changes.

Note: For a complete list of process names, see Tableau Server Processes.

Synopsis

tsm topology set-process --count <process_count> --node <nodeID> --process <process_name> [global options]

Options

-c, --count <process_count>

Required.

The process count (number of instances) to set.

-n, --node <nodeID>

Required.

Specifies the node ID of the node on which to set the process.

-pr, --process <process_name>

Required.

The name of the process to be set.

tsm topology toggle-coordination-service

Note: Beginning with version 2020.1.0, all coordination service ensemble commands require input for a "y/n" prompt confirming that a server restart will take place. To run these commands without input, include the --ignore-prompt option.

You can use the tsm topology toggle-coordination-service command to switch between coordination service ensembles. To learn more about Coordination Service ensembles, see Deploy a Coordination Service Ensemble.

In version 2020.1.0 and later, the tsm topology deploy-coordination-service command also switches to the new ensemble. There is no need to run this command separately.

Synopsis

tsm topology toggle-coordination-service [option] [global options]

Option

--request-timeout <timeout in seconds>

Optional.

Wait the specified amount of time for the command to finish. Default value is 1800 (30 minutes).

Global options

-h, --help

Optional.

Show the command help.

-p, --password <password>

Required, along with -u or --username if no session is active.

Specify the password for the user specified in -u or --username.

If the password includes spaces or special characters, enclose it in quotes:

--password "my password"

-s, --server https://<hostname>:8850

Optional.

Use the specified address for Tableau Services Manager. The URL must start with https, include port 8850, and use the server name not the IP address. For example https://<tsm_hostname>:8850. If no server is specified, https://<localhost | dnsname>:8850 is assumed.

--trust-admin-controller-cert

Optional.

Use this flag to trust the self-signed certificate on the TSM controller. For more information about certificate trust and CLI connections, see Connecting TSM clients.

-u, --username <user>

Required if no session is active, along with -p or --password.

Specify a user account. If you do not include this option, the command is run using credentials you signed in with.