# setup-cluster

## Description

Deploy a cluster across multiple hosts

This command conveniently runs various `sdb-toolbox-config`, `sdb-deploy`, and `sdb-admin` commands as a single command to produce a functional cluster that can be connected to and queried.

The `--password` flag is required and specifies the SingleStore `root` password on each node. Note that the `MEMSQL_PASSWORD` environment variable is a safer alternative option for setting the password.

If you would prefer to set up a local cluster for testing purposes, use the [SingleStore Dev Image](https://docs.singlestore.com/db/v9.1/deploy/singlestore-dev-image.md).

**Examples**

```shell
sdb-deploy setup-cluster \
  --master-host user@host1:33 \
  --aggregator-hosts host2 \
  --leaf-hosts host3,host4 \
  --identity-file ~/my_key.pem \
  --license AAAAAAa/Aaa/AA== \
  --password testpass
```

This will install the latest released version of `singlestoredb-server` on each host and deploy a Master Aggregator on `host1`; a child aggregator on `host2`; and leaf nodes on `host3` and `host4`. These hosts must be accessible via SSH using the current user and the key `~/my_key.pem`. A valid license and password for the SingleStore `root` user are also required. If you set a `MEMSQL_LICENSE` environment variable, you can omit the `--license` flag.

"High Availability" mode is enabled by default. To disable it, set `--high-availability` to false:

```shell
sdb-deploy setup-cluster --master-host host1 ... --high-availability=false
```

The command will deploy SingleStore on port `3306` on each node by default. To configure it to a different port, set `--memsql-port`:

```shell
sdb-deploy setup-cluster --master-host host1 ... --memsql-port 3307
```

If you want to install a version other than the latest released version, you can specify a different released version, or the path to a `singlestoredb-server` package:

```shell
sdb-deploy setup-cluster --master-host host1 ... --version 6.7.0

```

```shell
sdb-deploy setup-cluster --master-host host1 ... --file-path path/to/singlestoredb-server.deb

```

```shell
sdb-deploy setup-cluster --master-host host1 ... --file-path path/to/singlestoredb-server.rpm
```

If you need to specify a host's SSH user or SSH port, you can add the information to the host descriptor:

```shell
sdb-deploy setup-cluster --master-host admin@host1:10022 --leaf-hosts admin@host2:10022,admin@host3:10022 ...
```

If you want to use a YAML file to define your cluster you can do so by using the `--cluster-file` flag which takes in the path to a YAML file as input. Note that you have to give all the configurations as part of the cluster file and cannot use any other flag along with `--cluster-file`. If you want to learn about creating a cluster file please refer to [YAML File Configuration](https://docs.singlestore.com/#UUID-274263c9-ef7f-515d-3934-771654c7be6a_section-idm232319500933002.md).

Usage of the command with `--cluster-file` flag:

```shell
sdb-deploy setup-cluster --cluster-file path/to/cluster-file.yml
```

## YAML File Configuration

As of Toolbox 1.3.0, the `sdb-deploy setup-cluster` command now accepts YAML configuration files, and validates the configuration file format before attempting to set up the specified cluster.

The command is designed to be consistent, where re-running the `sdb-deploy setup-cluster` command with the same cluster file will always produce the same cluster. It is also resilient, allowing errors encountered at any stage of the cluster construction process to be corrected, and `sdb-deploy setup-cluster` re-run, in order to generate the desired cluster.

## Steps for using a Configuration File

1. [Install Toolbox](https://docs.singlestore.com/db/v9.1/user-and-cluster-administration/cluster-management-with-tools.md) onto the main deployment host.

2. Using the template below, create a YAML file with your desired cluster configuration.
   ```yaml
   license: <license-from-portal.singlestore.com>
   memsql_server_version: <version>
   package_type: <rpm | deb | tar>
   hosts:
   - hostname: <ip-address>
     localhost: true
     nodes:
     - register: false
       role: Master
       config:
         password: <secure-password>
         port: 3306
     - register: false
       role: Leaf
       config:
         password: <secure-password>
         port: 3307

   ```

3. Run the following with the path to the YAML file as input.
   ```shell
   sdb-deploy setup-cluster --cluster-file <path-to-cluster-file>

   ```

**Note**: By default, the `sdb-deploy setup-cluster` command configures the host's operating system per SingleStore's recommendations. To disable this auto-configuration, add the `--skip-auto-config=true` option to the `hosts` field in the YAML configuration file.

## Definitions

The following is a detailed explanation of each field that can be configured in the cluster file.

## CLUSTER

| Option                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `allow_duplicate_host_fingerprints` | When set to`true`, Toolbox allows hosts to have the same`ssh`fingerprints.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `assert_clean_state`                | When set to`true`, Toolbox verifies that no nodes currently exist in the cluster.                                                                                                                                                                                                                                                                                                                                                                                              |
| `high_availability`                 | This enables high availability on yourcluster. This will only work if there are an even number of leaves on yourcluster. The default value is`false`if not specified. If set to`true`, each node may be assigned an availability group via the`availability_group`field. Refer to[Managing High Availability](https://docs.singlestore.com/db/v9.1/user-and-cluster-administration/high-availability-and-disaster-recovery/managing-high-availability.md)for more information. |
| `license`                           | The license that will be used for thecluster. You can obtain a free or existing license from theCloud Portal. Your license will be used to bootstrap a Master Aggregator (MA).                                                                                                                                                                                                                                                                                                 |
| `optimize`                          | When set to`true`, optimizes memory usage for theclusterwith the recommended memory percentage. Also optimizes for NUMA.                                                                                                                                                                                                                                                                                                                                                       |
| `optimize_config`                   | Includes two fields that can change how theclusteris optimized. The`memory_percentage`option dictates the percentage of memory thatSingleStoreuses on each host. If the`no_numa`option is set to`true`, the NUMA optimization on theclusterwill not be performed.                                                                                                                                                                                                              |
| `root_password`                     | The default password for all the nodes if a password is not specified in the node password field. Required if a node-level password is not specified.                                                                                                                                                                                                                                                                                                                          |
| `skip_install`                      | When set to`true`, Toolbox skips the installation of`singlestoredb-server`. This can be useful for cases such as migration, where each host requires a custom installation.                                                                                                                                                                                                                                                                                                    |
| `skip_validate_env`                 | When set to`true`, Toolbox will perform cluster setup without validating the environment.                                                                                                                                                                                                                                                                                                                                                                                      |
| `sync_variables`                    | The list of sync variables that will be set on the Master Aggregator node.                                                                                                                                                                                                                                                                                                                                                                                                     |

The following two options are related to the version of SingleStore that will be installed for your cluster. Either option can be specified. If neither option is specified, the latest version of `singlestoredb-server` is installed.

| Option                    | Description                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memsql_server_version`   | The desired version of`singlestoredb-server`will be downloaded and installedcluster-wide.                                                                                                                                                                                                                                                                       |
| `memsql_server_file_path` | Installs version of`singlestoredb-server`package specified by the path to the`singlestoredb-server`package.                                                                                                                                                                                                                                                     |
| `package_type`            | The package type to use for the installation:`rpm`,`deb`, or`tar`. A package type of`tar`will only be used if explicitly specified. If the host has only one package manager for either`.rpm`or`.deb`packages,`sdb-deploy setup-cluster`will use the associated package manager. If multiple package managers are available on a host, this option is required. |

## HOST

| Option                  | Description                                                                                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hostname`              | Thecluster-addressable hostname of this host. If only one, local host is available, use`127.0.0.1`.                                                                    |
| `localhost`             | Use this option to specify that the target host is`localhost`. The default value is`false`if not specified. If provided,`localhost`commands do not require`ssh`access. |
| `memsqlctl_path`        | The path to the`memsqlctl`binary on the target host. Only required if a custom installation of`singlestoredb-server`was performed.                                     |
| `memsqlctl_config_path` | The path to the`memsqlctl.hcl`file on the target host. Only required if a custom installation of`singlestoredb-server`was performed.                                   |
| `skip_auto_config`      | When set to`true`, Toolbox will not configure system settings on the hosts.                                                                                            |
| `tar_install_dir`       | The directory to use for tarball-based installs on the target host. The default value is`$homedir/memsql`if not specified and a tarball-based install is performed.    |
| `tar_install_state`     | The path to the`packages.hcl`file on the target host. This option must only be used in conjunction with`tar_install_dir`.                                              |

The following `ssh`-related fields are required for remote hosts:

| Option        | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `host`        | The`ssh`hostname.                                                |
| `port`        | The`ssh`port (default:`22`).                                     |
| `private_key` | The identity file for the host (typically found in`~<user>/.ssh` |
| `user`        | The`ssh`user for the host.                                       |

## NODE

| Option               | Description                                                                                                                                                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availability_group` | The availability group to assign to the node when`high_availability`is set to`true`. Refer to[Availability Groups](https://docs.singlestore.com/db/v9.1/introduction/distributed-architecture/high-availability.md)for more information.                                                     |
| `force_registration` | When set to`true`, allows Toolbox to register offline nodes.                                                                                                                                                                                                                                 |
| `no_start`           | If set to`true`, the node will not be started after creation. This option is not valid if`register`is set to`true`.                                                                                                                                                                          |
| `register`           | Set the value of this field to`false`to create a new node. Set the value to`true`if the node is already present and you want to register it to Toolbox. The`configpath`field and value are also required when`register`is set to`true`.*Do not set this value to`true`to create a new node*. |
| `role`               | The role of the current node, which is one of`Master`,`Leaf`,`Aggregator`, or`Unknown`.*Do not use this option with the register option*.                                                                                                                                                    |
| `variables`          | The list of local variables that will be set on the node before the node starts.                                                                                                                                                                                                             |

## CONFIG

| Option                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auditlogsdir`         | The absolute path to the`auditlogs`directory. If`register`is set to`true`, this option must be specified in the configuration file.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `baseinstalldir`       | The absolute path to the base install directory. This option is only available when creating a node.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `configpath`           | The absolute path to the node’s configuration file. If`register`is set to`true`, this option must be specified in the configuration file.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `datadir`              | The absolute path to the node’s`data`directory. If`register`is set to`true`, this option must be specified in the configuration file.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `default install dir`  | When a node is created, its associated data and directories will be tied to a base install directory known as the“default install dir.”The directory’s name is a randomly-generated UUID. Run`memsqlctl env`to determine where the default install dir is on a host. Note that the`singlestoredb-server``.rpm`and`.deb`packages configure the default install dir to be`/var/lib/memsql`. If you prefer to configure a node’s directories, update the following`auditlogsdir`,`baseinstalldir`,`configpath`,`datadir`,`plancachedir`, and`tracelogsdir`fields. |
| `disable_auto_restart` | If set to`true`, the node will not be restarted automatically if it crashes. This option is not valid if`register`is set to`true`.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `password`             | TheSingleStorepassword for the node.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `plancachedir`         | The absolute path to the`plancache`directory. If`register`is set to`true`, this option must be specified in the configuration file.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `port`                 | The port that this node uses on its host. Ensure that all the nodes on a host are set to different ports. The default port is`3306`. A new port must be specified if port`3306`is already in use.                                                                                                                                                                                                                                                                                                                                                              |
| `ssl_fips_mode`        | When set to`true`, enables SSL/TLS[FIPS](https://wiki.openssl.org/index.php/FIPS_mode_and_TLS)mode on the node. To enable for the entire cluster, this parameter must be set to`true`on each node.                                                                                                                                                                                                                                                                                                                                                             |
| `tracelogsdir`         | The absolute path to the`tracelogs`directory. If`register`is set to`true`, this option must be specified in the configuration file.                                                                                                                                                                                                                                                                                                                                                                                                                            |

## Specify Node Directories

During cluster deployment, the directories in which nodes are created can be specified through the use of the following options:

| **Option**           | **Deployment via** | **Method**        | **Level**    |
| -------------------- | ------------------ | ----------------- | ------------ |
| `--base-install-dir` | RPM, DEB, Tarball  | Command line      | Host         |
| `baseinstalldir`     | RPM, DEB, Tarball  | Cluster file YAML | Node         |
| `tar_install_dir`    | Tarball            | Cluster file YAML | Host or node |

With regard to level:

* "Host" level reflects that each node will all be created in the same directory on each host
* "Node" level reflects that each node will be created in a unique subdirectory on each host

The base install directory for a leaf node can also be updated post-deployment. Refer to [Changing the Default Data Directory Post Installation for a Leaf Node](https://docs.singlestore.com/db/v9.1/user-and-cluster-administration/maintain-your-cluster/changing-the-default-data-directory-post-installation-for-a-leaf-node.md) for more information.

## Same Directory

In these deployment examples, each node is created in the same `/opt/singlestore/nodes` directory on each host.

## Multi-Host, Command Line

```shell
sdb-deploy setup-cluster \
--license <license>\
--version 8.5 \
--master-host <host-1> \
--aggregator-hosts <host-2>
--leaf-hosts <host-3>,<host-4> \
--password <secure-password> \
--base-install-dir "/opt/singlestore/nodes"
```

## Single Host, Cluster File

```yaml
license: <license>
memsql_server_file_path: </singlestoredb-server/including/path>
package_type: tar
hosts:
- hostname: host-1
  tar_install_dir: /opt/singlestore/nodes/
  localhost: true
  nodes:
  - register: false
    role: Master
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307
```

## Unique Directory

In these deployment examples, each node is created in a unique subdirectory in the `/opt/singlestore/nodes` directory on each host.

## Package-Based

```yaml
license: <license>
memsql_server_version: 8.5
package_type: rpm
hosts:
- hostname: host-1
  localhost: false
  nodes:
  - register: false
    role: Master
    config:
      baseinstalldir: /opt/singlestore/nodes/ma-3306
      password: <secure-password>
      port: 3306
- hostname: host-2
  localhost: false
  nodes:
  - register: false
    role: Leaf
    config:
      baseinstalldir: /opt/singlestore/nodes/leaf-3307
      password: <secure-password>
      port: 3307

```

## Tarball-Based

```yaml
license: <license>
memsql_server_file_path: </singlestoredb-server/including/path>
package_type: tar
hosts:
- hostname: host-1
  localhost: true
  nodes:
  - register: false
    role: Master
    config:
      baseinstalldir: /opt/singlestore/nodes/ma-3306
      password: <secure-password>
      port: 3306
- hostname: host-2
  localhost: false
  - register: false
    role: Leaf 
    config:
      baseinstalldir: /opt/singlestore/nodes/leaf-3307
      password: <secure-password>
      port: 3307
```

For multi-host, tarball-based deployments with a YAML file, using `tar_install_dir` at the *host* level is equivalent to using `baseinstalldir` at the *node* level as each node is created in a unique subdirectory.

```yaml
license: <license>
memsql_server_file_path: </singlestoredb-server/including/path>
package_type: tar
hosts:
- hostname: host-1
  tar_install_dir: /opt/singlestore/nodes/ma-3306
  localhost: false
  nodes:
  - register: false
    role: Master
    config:
      password: <secure-password>
      port: 3306
- hostname: host-2
  tar_install_dir: /opt/singlestore/nodes/leaf-3307
  localhost: false
  nodes:
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307

```

## Complete Cluster File Template

```yaml
license:                           <LICENSE | /path/to/LICENSE-file> [Required to bootstrap Master Aggregator]
high_availability:                 <true | false>
memsql_server_version:             <the version of memsql you want to install (6.7+)>
memsql_server_file_path:           <path to the downloaded memsql server file>
memsql_server_preinstalled_path:   <equivalent to using the '--preinstalled-path' option;
                                   the path to the unpacked singlestoredb-server file
                                   where the unpacked folder name must be of the form
                                   'singlestoredb-server-<version>*' or
                                   'memsql-server-<version>*'>
skip_install:                      <true | false> [ADVANCED]
skip_validate_env:                 <true | false> [ADVANCED]
allow_duplicate_host_fingerprints: <true | false> [ADVANCED]
assert_clean_state:                <true | false> [ADVANCED]
package_type:                      <rpm | deb | tar> [Required if multiple package managers are present]
root_password:                     <default password to be used for all nodes>
optimize:                          <true | false>
optimize_config:
  memory_percentage:               <percentage of memory you want memsql to use>
  no_numa:                         <true | false>
sync_variables:                    [ADVANCED]
  <variable's name>:               <variable's value>            
hosts:
- hostname:                        <host-name> [Required]
  localhost:                       <true | false> 
  skip_auto_config:                <true | false>
  memsqlctl_path:                  <path to memsqlctl> [ADVANCED]
  memsqlctl_config_path:           <path to memsqlctl config> [ADVANCED]
  tar_install_dir:                 <path to tar install dir> [ADVANCED]
  tar_install_state:               <path to tar install state> [ADVANCED]
  ssh:                             [Required for remote Hosts]
    host:                          <ssh host name>
    port:                          <ssh port>
    user:                          <ssh user>
    private_key:                   <path to your identity key>
  nodes:
  - register:                      <true | false>
    force_registration:            <true | false> [ADVANCED] 
    role:                          <Unknown | Master | Leaf | Aggregator> (case sensitive) [Required]
    aggregator_role:               <voting_member | follower (by default)> [Applicable only for role Aggregator]
    availability_group:            <availability group>
    no_start:                      <true | false>
    config: 
      auditlogsdir:                <path to auditlogs directory> [ADVANCED]
      baseinstalldir:              <path to base install directory> [ADVANCED]
      configpath:                  <path to configuration path> [ADVANCED] [Required if register is true]
      datadir:                     <path to data directory> [ADVANCED]
      disable_auto_restart:        <true | false>
      password:                    <password>
      plancachedir:                <path to plancache directory> [ADVANCED]
      port:                        <port number> [Required for node creation]
      tracelogsdir:                <path to tracelogs directory> [ADVANCED]
      bind_address:                <bind address> [ADVANCED]
      ssl_fips_mode:               <true | false > [ADVANCED]
    variables:
      <variable's name>:           <variable's value>
```

## Example Cluster Files

The following cluster file template examples can be used to set up a cluster.

Copy an example into an `example.yaml` file and pass this file to the `sdb-deploy setup-cluster` command.

```shell
sdb-deploy setup-cluster --cluster-file example.yaml

```

**Note**: Depending on how you installed Toolbox (for example, via [tarball-based install](https://docs.singlestore.com/db/v9.1/user-and-cluster-administration/cluster-management-with-tools/singlestore-tools-installation/singlestore-toolbox-installation/#install-singlestore-toolbox.md), you may need to include the full path to the cluster file.

```shell
./sdb-deploy setup-cluster --cluster-file /full-path/example.yaml

```

For Example 2, Example 3, and Example 4, you will need multiple hosts and the ability to `ssh` into each host from the main deployment host.

## Example 1

```yaml
license: <license-from-portal.singlestore.com>
memsql_server_version: 7.3.10
package_type: rpm
hosts:
- hostname: 127.0.0.1
  localhost: true
  nodes:
  - register: false
    role: Master
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307

```

Using this cluster file, `sdb-deploy setup-cluster`:

1. Registers a local host to the cluster.

2. Installs `singlestoredb-server` v7.3.10 on this local host.

3. Creates a Master Aggregator node on port `3306`.

4. Creates a leaf node on port `3307`.

## Example 2

```yaml
license: <license-from-portal.singlestore.com>
memsql_server_version: 7.3.10
package_type: rpm
hosts:
- hostname: <hostname1>
  localhost: true
- hostname: <hostname2>
  ssh: 
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>

```

Using this cluster file, `sdb-deploy setup-cluster`:

1. Registers a local host to the cluster.

2. Registers a remote host to the cluster using the provided `ssh` credentials.

3. Installs `singlestoredb-server` v7.3.10 on both hosts.

## Example 3

```yaml
license: <license-from-portal.singlestore.com>
memsql_server_version: 7.3.10
package_type: rpm                
hosts:
- hostname: <hostname1>
  localhost: true
  nodes:
  - register: false
    role: Master
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307
- hostname: <hostname2>
  ssh: 
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>
  nodes:
  - register: false
    role: Aggregator
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307

```

Using this cluster file, `sdb-deploy setup-cluster`:

1. Registers a local host to the cluster.

2. Register a remote host to the cluster using the provided `ssh` credentials.

3. Installs `singlestoredb-server` v7.3.10 on both the hosts.

4. On Host 1, creates a node on port `3306`, bootstraps it as the Master Aggregator using the specified license, and sets the password to the value provided in the cluster file.

5. On Host 1, creates a node on port `3307,` assign it as a leaf node, and sets the password to the value provided in the cluster file.

6. On Host 2, creates a node on port `3306`, assign it as a Child Aggregator, and sets the password to the value provided in the cluster file.

7. On Host 2, creates a node on port `3307`, assign it as a leaf node, and sets the password to the value provided in the cluster file.

## Example 4

```yaml
license: <license-from-portal.singlestore.com>
high_availability: true
package_type: rpm
memsql_server_file_path: /home/ec2-user/singlestoredb-server-7.3.10-5aa7127018.x86_64.rpm
hosts:
- hostname: <hostname1>
  localhost: true
  nodes:
  - role: Master
    config:
      password: <secure-password>
      port: 3306
- hostname: <hostname2>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>
  nodes:
  - role: Aggregator
    config:
      password: <secure-password>
- hostname: <hostname3>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>
  nodes:
  - role: Aggregator
    config:
      password: <secure-password>      
- hostname: <hostname4>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>
  nodes:
  - role: Leaf
    availability_group: 1  
    config:
      password: <secure-password>      
- hostname: <hostname5>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>    
  nodes:
  - role: Leaf
    availability_group: 1
    config:
      password: <secure-password>
- hostname: <hostname6>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>    
  nodes:
  - role: Leaf
    availability_group: 2
    config:
      password: <secure-password>  
- hostname: <hostname7>
  ssh:
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>    
  nodes:
  - role: Leaf
    availability_group: 2
    config:
      password: <secure-password>

```

Using this cluster file, `sdb-deploy setup-cluster`:

1. Enables [high availability](https://docs.singlestore.com/db/v9.1/user-and-cluster-administration/high-availability-and-disaster-recovery/managing-high-availability.md).

2. Specifies the use of RPM packages.

3. Specifies the location of the `singlestoredb-server` package which will be used directly instead of downloaded.

4. Installs `singlestoredb-server` v7.3.10 on all hosts.

5. On Host 1, creates a node on port `3306`, bootstraps it as the Master Aggregator using the specified license, and sets the password to the value provided in the cluster file.

6. On Host 2, creates a node on the default port (`3306`), assign it as a Child Aggregator, and sets the password to the value provided in the cluster file.

7. On Host 3, creates a node on the default port (`3306`), assign it as a Child Aggregator, and sets the password to the value provided in the cluster file.

8. On Host 4, creates a node on the default port (`3306`), assign it as a leaf node, sets the node’s [availability group](https://docs.singlestore.com/db/v9.1/introduction/distributed-architecture/high-availability.md) to `1`, and sets the password to the value provided in the cluster file.

9. On Host 5, creates a node on the default port (`3306`), assign it as a leaf node, sets the node’s availability group to `1`, and sets the password to the value provided in the cluster file.

10. On Host 6, creates a node on the default port (`3306`), assign it as a leaf node, sets the node’s availability group to `2`, and sets the password to the value provided in the cluster file.

11. On Host 7, creates a node on the default port (`3306`), assign it as a leaf node, sets the node’s availability group to `2`, and sets the password to the value provided in the cluster file.

## Example 5

```yaml
license: <license-from-portal.singlestore.com>
memsql_server_version: 8.0.5
package_type: deb
sync_variables:
  geo_sphere_radius: 10000.66
  cluster_name: <cluster-name>   
hosts:
- hostname: <hostname1>
  localhost: true
  nodes:
  - register: false
    role: Master
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307
- hostname: <hostname2>
  ssh: 
    host: <cluster-addressable-hostname>
    private_key: <path/to/private-key>
  nodes:
  - register: false
    role: Aggregator
    config:
      password: <secure-password>
      port: 3306
  - register: false
    role: Leaf
    config:
      password: <secure-password>
      port: 3307
    variables:
      http_api_pool_capacity: 4048
      allow_unsupported_filesystem: ON
```

Using this cluster file, `sdb-deploy setup-cluster`:

1. Registers a local host to the cluster.

2. Register a remote host to the cluster using the provided `ssh` credentials.

3. Installs `singlestoredb-server` v8.0.5 on both hosts.

4. On Host 1, creates a node on port `3306`, bootstraps it as the Master Aggregator using the specified license, and sets the password to the value provided in the cluster file.

5. On Host 1, creates a node on port `3307`, assign it as a leaf node, and sets the password to the value provided in the cluster file.

6. On Host 2, creates a node on port `3306`, assign it as a Child Aggregator, and sets the password to the value provided in the cluster file.

7. On Host 2, creates a node on port `3307`, assign it as a leaf node, sets `http_api_pool_capacity` and `allow_unsupported_filesystem` variables to values provided in the cluster file, and sets the password to the value provided in the cluster file.

8. Sets `geo_sphere_radius` and `cluster_name` sync variables to values provided in the cluster file.

## Host File Structure

For large clusters, you can specify all of your hosts' SSH information through an INI file that you reference using the `--host-file` flag. The format is below.

```
[master]
[ssh_user@]<master_host_IP_address|DNS_name>[:ssh_port]

[aggregators]
[ssh_user@]<agg_host1_IP_address|DNS_name>[:ssh_port]
...

[leaves]
[ssh_user@]<leaf_host1_IP_address|DNS_name>[:ssh_port]
...
```

## Usage

```
Usage:
  sdb-deploy setup-cluster [flags]

  For flags that can accept multiple values (indicated by VALUES after the name of the flag),
  separate each value with a comma.

Flags:
      --aggregator-hosts strings                 SSH addresses of the child aggregator hosts
      --allow-duplicate-host-fingerprints        Whether to allow hosts with identical SSH host keys. (ADVANCED)
      --allow-ipv6                               Sets allow_ipv6 to true for all nodes in cluster
      --base-install-dir ABSOLUTE_PATH           The absolute path to the base install directory for all the nodes
      --cluster-file FILE_PATH                   The path to the cluster definition file
      --data-dir ABSOLUTE_PATH                   The absolute path to the data directory for all the nodes
      --file-path ABSOLUTE_PATH                  The full path, including the filename, of the singlestoredb-server package to install
      --force-package-format {rpm | deb | tar}   Specify 'rpm', 'deb', or 'tar' package format. Required if you have both dpkg and rpm package managers found on the host
  -h, --help                                     Help for setup-cluster
      --high-availability                        Indicate whether to deploy the cluster in high-availability mode (default true)
      --hosts-file ABSOLUTE_PATH                 The file specifying the host addresses/hostnames for the Master Aggregator, child aggregators, and leaf nodes, in INI format with [master], [aggregators], and [leaves] sections
  -i, --identity-file ABSOLUTE_PATH              The identity file to SSH to each host
      --leaf-hosts strings                       SSH addresses/hostnames of each leaf node host. At least one must be specified
      --license LICENSE                          The license for the cluster
      --load-balanced                            Use load_balanced mode for partitioning leaf nodes when high availability is enabled
      --master-host string                       SSH address/hostname of the Master Aggregator host
      --memsql-port PORT                         The port each node will run on
      --password STRING                          The database root user's password. If a password is specified on the command line, it must not contain an unescaped '$' character as it will be replaced by the shell
      --preinstalled-path ABSOLUTE_PATH          The path to the folder (must be of the form 'singlestoredb-server-<version>*' or 'memsql-server-<version>*') that contains the singlestoredb-server binaries. Depending on the mode of cluster deployment, the folder contains either the unpacked tarball file or the installed package file (Debian or RPM) of singlestoredb-server. (ADVANCED)
      --skip-auto-config                         Skip automatic operating system configuration
      --skip-feature-flags-enabling              Skip enabling all feature flags for SingleStore versions 9.1 and later
      --skip-validate-env                        Skip environment validation
      --ssl-fips-mode string                     Whether the cluster operates in OpenSSL/FIPS mode
      --temp-dir ABSOLUTE_PATH                   The temporary directory to use for the installation on each host
      --version VERSION                          The version of singlestoredb-server to install (default production:latest)

Global Flags:
      --backup-cache FILE_PATH                File path for the backup cache
      --cache-file FILE_PATH                  File path for the Toolbox node cache
  -c, --config FILE_PATH                      File path for the Toolbox configuration
      --disable-colors                        Disable color output in console, which some terminal sessions/environments may have difficulty with
      --disable-spinner                       Disable the progress spinner, which some terminal sessions/environments may have issues with
  -j, --json                                  Enable JSON output
      --parallelism POSITIVE_INTEGER          Maximum number of operations to run in parallel
      --runtime-dir DIRECTORY_PATH            Where to store Toolbox runtime data
      --ssh-max-sessions POSITIVE_INTEGER     Maximum number of SSH sessions to open per host, must be at least 3
      --ssh-strict-host-key-checking          Enable strict host key checking for SSH connections
      --ssh-user-known-hosts-file FILE_PATH   Path to the user known_hosts file for SSH connections. If not set, /dev/null will be used
      --state-file FILE_PATH                  Toolbox state file path
  -v, --verbosity count                       Increase logging verbosity: valid values are 1, 2, 3. Usage -v=count or --verbosity=count
  -y, --yes                                   Enable non-interactive mode and assume the user would like to move forward with the proposed actions by default

```

## Remarks

This command is interactive unless you use either `--yes` or `--json` flag to override interactive behavior.

## Output

The following example uses the `setup-cluster` command to set up a simple cluster on two different hosts using a `hosts` file.

**hosts file**

```
[master]
172.18.1.4

[leaves]
172.18.1.5

```

**Setting up a cluster with a hosts file**

```shell
sdb-deploy setup-cluster -i clusterkey --license <license> --hosts-file hosts --password SecureKey

```

```output

✓ Registered hosts
sdb-deploy will perform the following actions:
  · Install singlestoredb-server 7.3.10 on hosts
    - 172.18.1.4
    - 172.18.1.5
  · Deploy a master aggregator on 172.18.1.4:3306
    - Enable high availability mode
  · Deploy a leaf node on 172.18.1.5:3306
  · Set root password on all nodes

Would you like to continue? [y/N]: y
✓ Downloaded singlestoredb-server 7.3.10
Installing SingleStore on all hosts...
✓ Installed singlestoredb-server7.3.10-6c220bccfc on host 172.18.1.4 (1/2)
✓ Installed singlestoredb-server7.3.10-6c220bccfc on host 172.18.1.5 (2/2)
✓ Successfully installed on 2 hosts
✓ Created master node
✓ Successfully set license
✓ Bootstrapped master aggregator
✓ Enabled high availability mode
✓ Created aggregator nodes
✓ Added aggregators nodes to cluster
✓ Created leaf nodes
✓ Added leaf nodes to cluster

To view your cluster, run 'sdb-admin list-nodes'

```

***

Modified at: January 13, 2026

Source: [/db/v9.1/reference/singlestore-tools-reference/sdb-deploy-commands/setup-cluster/](https://docs.singlestore.com/db/v9.1/reference/singlestore-tools-reference/sdb-deploy-commands/setup-cluster/)

(An index of the documentation is available at /llms.txt)