Overview

Clustrix provides a utility called clx to administer its distributed ClustrixDB database.

Add /opt/clustrix/bin to your user PATH to simplify access to clx

The primary uses for the utility are:

Display status of the nodes, disks, or replication slave.
Execute bash or shell commands on node(s) in the cluster.
Copy data to/from a local file to node(s) in the cluster.
Issue commands to each node's overseeing nanny process.
Shutdown the cluster.
Start or stop the database.
Communicate with a database that’s not online in emergency situations.

If you receive this message, Using cached node details, clx is relying on cached information that may not reflect the current state of your cluster. Contact Clustrix Support if this is unexpected or raises concerns.

Syntax

To run the clx utility:

shell> clx [options] <command> [command arguments]

Clustrix recommends configuring passwordless ssh for all users who will use clx.

General Options

Many of the clx commands allow options to be specified that refine a process. The following options are shared by all commands except as noted.

Option	Description
-C, --use-cache	Use cached cluster information, do not attempt to query the database for this information. Functions which rely on database information will not work normally.
-h, --help	Show this help message and exit.
-n NODE, --node=NODE	Run on a specific node, not the entire cluster. May be specified more than once to select multiple nodes. Accepts nodeid or hostname. (Not presently supported for clx slave and clx cache)
-U DB_USER, --db-user=DB_USER	Login user for SQL connections to the local node. [default: logged in OS user]
-X EXCLUDE, --exclude=EXCLUDE	Exclude a specific node from this command. May be specified more than once to exclude multiple nodes. Accepts nodeid or hostname. Supersedes the -n option, if the same node is specified for both. (Not presently supported for clx slave and clx cache)

To display all the clx commands use: clx help
To display the options supported for a given command use: clx help [command]

Commands

clx is a multi-purpose tool that you will likely use the most frequently of all the ClustrixDB's tools. Because clx is multi-purpose, the options and arguments needed to accomplish each command vary. The specifics for each clx command are described below.

alters

Provides the status of ALTER statements in progress based on system.alter_progress.

cache

Immediately updates the filesystem cache with node information. Providing this command is typically not necessary as the filesystem cache is saved automatically each time clx connects to a database with all nodes in quorum.

shell> clx [options] cache

Command-Specific Option Exceptions

-n NODE, --node=NODE	Option to run on a specific node has no effect for this command.
-X EXCLUDE, --exclude=EXCLUDE	Option to exclude a specific node has no effect for this command.

cmd

Executes shell command(s) on nodes. Multiple commands may be supplied if enclosed in quotation marks and separated by a semicolon (;) or a pipe (|) character.

shell> clx [options] cmd <shell cmd>

Example(s)

clx cmd date
clx cmd 'df -h | grep clustrix'

Command-Specific Options

-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-P, --parallel	Execute on all nodes simultaneously.
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. Uses environment variable $CLX_SSH_PORT, if specified. [default: 22]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

cp

Executes a control port command on nodes.

shell> clx [options] cp <cp cmd>

Command-Specific Options

-P, --parallel	Execute on all nodes simultaneously.
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-T TIMEOUT, --timeout=TIMEOUT	Specify the timeout before failing a Telnet connection (in seconds).

dbrestart

Stops then starts the database process (clxnode) on nodes.

shell> clx [options] dbrestart

Command-Specific Options

-T TIMEOUT, --timeout=TIMEOUT

Specify the timeout before failing a Telnet connection (in seconds).

dbstart

Starts the database process (clxnode) on nodes.

shell> clx [options] dbstart

Command-Specific Options

-T TIMEOUT, --timeout=TIMEOUT

Specify the timeout before failing a Telnet connection (in seconds).

dbstop

Stops the database process (clxnode) on nodes. This effectively shuts down the cluster.

shell> clx [options] dbstop

Command-Specific Options

-T TIMEOUT, --timeout=TIMEOUT

Specify the timeout before failing a Telnet connection (in seconds).

debugdump

Gathers detailed debug information from the cluster to aid troubleshooting by Clustrix Support and Engineering. ClustrixDB assigns an output file if none is specified and displays the name assigned at the end of the process.

shell> clx [options] debugdump [outfile]

Command-Specific Options

--cp-threads=CPTHREADS	Specify how many cp commands to dump in parallel [default: 5 threads]
--overwrite=OVERWRITE	Overwrite an existing file if one exists at the output path.
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-T TIMEOUT, --timeout=TIMEOUT	Specify the timeout before failing a Telnet connection (in seconds).
-v, --verbose	Display more details.

disks

Displays disk information for the cluster.

shell> clx [options] disks

help

Displays help output for clx functions.

shell> clx [options] help [command]

logdump

Dumps log files from the cluster. Specify ‘all’ to show clustrix.log, query.log, nanny.log, and debug.log, or list the Clustrix and/or system logs that you’d like to see.

logdump also allows ClustrixDB messages file to be selected. If no log file is specified, logdump defaults to clustrix.log. The .log suffix is optional.

shell> clx [options] logdump [log files]

Example(s)

clx logdump all
clx logdump clustrix messages
clx logdump query
clx --start= '2016-09-13' --end= '2016-09-14' logdump
clx --start= '2016-09-13 06' --end= 0 logdump
clx --start= '2016-09-14' --end= -8 logdump
clx --no-sort --skip-down-nodes --limit= 2000 logdump

Command-Specific Options

-a, --archive	Collect individual logfiles into a tar file. This option disables the --limit value and captures everything between --start and --end.
-e END, --end=END	Specify log end time offset in hours after --start (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 (default) to use no end time boundary and read until the end of file. [default: 0 hours]
-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-L LIMIT, --limit=LIMIT	Specify the maximum amount (in kB) to collect from each log file. If any file hits this size limit before the specified --start time, the first line from that log will be used in place of the start time, so all logs will be collected from the same time range. Specify a value of 0 to disable this limit. [default: 10 MiB]. Disabling this limit or setting it too high can starve other processes.
-N, --no-sort	Disable sorting log files together by time, print just one at a time.
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. Uses environment variable $CLX_SSH_PORT, if specified. [default: 22]
-s START, --start=START	Specify log start time offset in hours (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 to use no start time boundary and just use the -L size limit. [default: 3 hours]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

logfreq

Prints a count of matching log lines from the cluster.

shell> clx [options] logfreq search_string [log files]

If no log files are specific, this will default to clustrix.log.

command-specific options

--case-sensitive	Include this option for case sensitive matching.
-e END, --end=END	Specify log end time offset in hours after --start (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 (default) to use no end time boundary and read until the end of file. [default: 0 hours]
-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-N, --no-sort	Disable sorting log files together by time, print just one at a time.
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. Uses environment variable $CLX_SSH_PORT, if specified. [default: 22]
-s START, --start=START	Specify log start time offset in hours (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 to use no start time boundary and just use the -L size limit. [default: 3 hours]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

logsearch

Search log files from the cluster.

shell> clx [options] logsearch search_string [log files]

If no log files are specific, this will default to clustrix.log.

command-specific options

--case-sensitive	Include this option for case sensitive matching.
-e END, --end=END	Specify log end time offset in hours after --start (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 (default) to use no end time boundary and read until the end of file. [default: 0 hours]
-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-N, --no-sort	Disable sorting log files together by time, print just one at a time.
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. Uses environment variable $CLX_SSH_PORT, if specified. [default: 22]
-s START, --start=START	Specify log start time offset in hours (decimals accepted,) or a timestamp string like '2016-02-14 22:51:48' or '2016-02-14 22' (units left off will be zeroed.) Use a value of 0 to use no start time boundary and just use the -L size limit. [default: 3 hours]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

nanny

Executes a nanny command on nodes. For the description of the nanny process and the individual nanny commands available, please see the Overview of Nanny.

nanny ensures that all jobs needed for the successful function of ClustrixDB are running. The nanny process is launched automatically by the system init process.

shell> clx [options] nanny <nanny cmd>

Example

clx nanny show_jobs

Command-Specific Options

-P, --parallel	Execute on all nodes simultaneously.
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-T TIMEOUT, --timeout=TIMEOUT	Specify the timeout before failing a Telnet connection (in seconds).

pubkeyinstall

Uses password auth to generate public keypairs on each node and add them to each node's authorized_keys file. For more information, see Configure SSH Authentication.

pull

Copies files from nodes to local. This command is only available to root users. If no destination is specified, the current directory name will be used. The nodeid or hostname is appended to the retrieved name.

shell> clx [options] pull <remote source> [dest]

Example(s)

clx pull bar
clx pull /var/log/messages ./cluster-logs

Command-Specific Options

-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. [default: 22]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

push

Copies a file from local to nodes. If no destination is specified, the current directory name will be used on all nodes.

shell> clx [options] push <local source> [dest]

Example(s)

clx push bar
clx push /etc/motd /etc

Command-Specific Options

-i SSH_KEY, --ssh-key=SSH_KEY	SSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: ~/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USER	Login account for SSH connections to other nodes. Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-p SSH_PORT, --ssh-port=SSH_PORT	Port to use for SSH connections to other nodes. [default: 22]
-S, --skip-down-nodes	Skip nodes that are offline or unavailable instead of aborting when one or more nodes does not respond.
-w, --no-passwd	Do not attempt password SSH authentication.

slave

Displays replication slave information.

shell> clx [options] slave [slave name]

Command-Specific Option Exceptions

-n NODE, --node=NODE	Option to run on a specific node has no effect for this command.
-X EXCLUDE, --exclude=EXCLUDE	Option to exclude a specific node has no effect for this command.

space

Displays storage utilization information for the cluster.

shell> clx [options] space

status or stat

Displays general status for the cluster.

shell> clx [options] status

Example(s)

clx --node=1 status
clx -n clxdb003 stat
clx status

Command-Specific Options

-v, --verbose

Display more details.