SingleStore Toolbox Config Files

File	Location & Description	Format
`toolbox.hcl`	When `XDG_CONFIG_HOME` is set: `$XDG_CONFIG_HOME/singlestoredb-toolbox/toolbox.hcl` When `XDG_CONFIG_HOME` is not set: `$HOME/.config` For example: `/home/<user>/.config/singlestoredb-toolbox/toolbox.hcl`	HCL
	The Toolbox configuration file. Overrides the default settings for a given user. Toolbox uses a description of the cluster which is stored in the user's home directory by default. Running a Toolbox command as the `root` user (by using `sudo`, for example) will use a different cluster description than the one stored for the user. Toolbox commands should not be run via `sudo` as they do not require elevated privileges. To run Toolbox commands as `root`, add a `user = "root"` line to the `/root/.config/singlestoredb-toolbox/toolbox.hcl`. file. This file contains the following settings: `state`: The path to the Toolbox state file, `toolbox-state.hcl`, where Toolbox stores the set of hosts in a cluster. `cache`: The path to the Toolbox cache file, `toolbox-cache.hcl`, which Toolbox uses to make Toolbox commands run faster. `runtimeDir`: The path to the runtime directory, where Toolbox stores temporary session data. `user`: The username that is allowed to run Toolbox with this configuration file. `parallelism`: The maximum number of operations to run in parallel. The following example shows expanded system defaults for a user on a 4-core host: `version = 1 state = "/home/<user>/.local/share/singlestoredb-toolbox/toolbox-state.hcl" cache = "/home/<user>/.local/share/singlestoredb-toolbox/toolbox-cache.hcl" runtimeDir = "/run/user/1000" user = "<user>" parallelism = 4`
`toolbox-state.hcl`	When `XDG_DATA_HOME` is set: `$XDG_DATA_HOME/singlestoredb-toolbox/toolbox-state.hcl` When `XDG_DATA_HOME` is not set: `$HOME/.local/share/` For example: `/home/<user>/.local/share/singlestoredb-toolbox/toolbox-state.hcl`	HCL
	The Toolbox state file. Maintains a list of hosts that are part of a cluster. There are two types of hosts: local and remote. Remote hosts may optionally contain an `ssh` block that overrides the default SSH configuration for a host. The following is an empty Toolbox state file. `version = 1` The following is a Toolbox state file that specifies three hosts and their connection information. `version = 1 host { hostname = "host-01.example.com" } host { hostname = "host-02.example.com" localhost = true } host { hostname = "host-03.example.com" ssh { host = "host-03.example.com" port = 23 privateKey = "/home/bob/.ssh/id_rsa" user = "bob" } } secure = "dGhpc2tleWlzdGhpcnR5dHdvY2hhcmFjdGVyc2xvbmc="`

Toolbox and memsqlctl Differences

SingleStore provides two complementary tools to manage clusters: Toolbox and memsqlctl.

Toolbox

Toolbox is a collection of command-line tools that can be used to deploy, administer, and manage a cluster. These tools are intended to simplify high-level administrative tasks across a multi-host cluster, where Toolbox commands are proxied through memsqlctl. Toolbox, which is installed separately from the SingleStore engine, is available as a Debian or RPM package or a tarball file, which allows it to be incorporated into common, automated deployment workflows.

Toolbox consists of four primary command-line tools:

sdb-deploy: Used to deploy and upgrade the SingleStore server across hosts in a cluster.
sdb-admin: Used to perform cluster administrative tasks, such as adding nodes, enabling high availability (HA), setting up cluster monitoring, performing backup operations, optimizing performance settings, and more.
sdb-report: Used to collect diagnostic information about a cluster.
sdb-toolbox-config: Primarily used to register and unregister hosts in a cluster.

Toolbox can be installed on any Linux computer with network access to all of the hosts in a cluster. Toolbox commands must be able to connect to each host in the cluster via SSH, and as one of the following:

The user that runs memsqld
The Linux root user
A Linux user with sudo privileges

Toolbox requires the following information to operate:

A list of hosts in a cluster
The credentials for each host, such as Linux username and SSH key

Toolbox stores the set of registered hosts and their credentials in the Toolbox state file, toolbox-state.hcl. The path to this file can be obtained by calling the env sub-command of a Toolbox command, such as sdb-admin env or sdb-report env.

Contrary to SingleStore's legacy management tool, MemSQL Ops, Toolbox does not actively manage a cluster. When a Toolbox command is invoked, it connects to each host in the cluster via SSH and executes a memsqlctl command which, in turn, issues the command to each node in the cluster. Toolbox does not actively engage with the cluster once the command finishes.

More than one Toolbox instance can be used to manage a single cluster, and Toolbox can be manually reconfigured to manage a different cluster.

`memsqlctl`

The memsqlctl command is a low-level tool that is used to control and manage nodes on a host. As memsqlctl is a part of the SingleStore server package, it is installed along with the SingleStore database engine on each host in the cluster, where it employs the following files when manipulating the set of nodes:

memsql.cnf: The node configuration file; also stores engine variables
memsqlctl.hcl: The memsqlctl configuration file; can be used to override the default engine variable settings for the entire cluster; contains the location of the memsqlctl state file, nodes.hcl
nodes.hcl: The memsqlctl state file, also referred to as the node metadata file; the file where memsqlctl stores information about the nodes that reside on a host; contains the location of the node configuration file, memsql.cnf

Refer to Cluster Config Files for more detailed information.

Several administrative tasks supported by memsqlctl can be accomplished via a SQL interface. However, memsqlctl helps avoid the manual configurations involved when performing certain tasks, thereby minimizing human error.

For example, to create a node manually, one must:

Create a new memsql.cnf file
Start memsqld, specifying all of the required memsqld command-line arguments

As starting memsqld this way can be error-prone, memsqlctl can (and should) be used instead. With memsqlctl, these actions are performed by reading information about the nodes on a host from the memsqlctl configuration file, memsqlctl.hcl. Refer to the memsqlctl command reference and Cluster Config Files for more information.