Page tree
Skip to end of metadata
Go to start of metadata

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 leveraging 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.

OptionDescription
-C, --use-cacheUse cached cluster information, do not attempt to query the database for this information.
-h, --helpShow 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_USERLogin user for SQL connections to the local node. [default: root]
-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.  

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.

shell> clx [options] cache

Command-Specific Option Exceptions

-n NODE, --node=NODEOption 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
clx cmd 'ls -l /data/clustrix | df -h'

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: /root/.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: root]

-P, --parallelExecute on all nodes simultaneously.
-p SSH_PORT, --ssh-port=SSH_PORTPort 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-passwdDo not attempt password SSH authentication.

cp

Executes a control port command on nodes.

shell> clx [options] cp <cp cmd>

Command-Specific Options

-P, --parallelExecute 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=TIMEOUTSpecify 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=TIMEOUTSpecify 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=TIMEOUTSpecify 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=TIMEOUTSpecify 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=CPTHREADSSpecify how many cp commands to dump in parallel [default: 5 threads]
--overwrite=OVERWRITEOverwrite 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=TIMEOUTSpecify the timeout before failing a Telnet connection (in seconds).
-v, --verboseDisplay 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 one stdout or logfile, then tar and compress. 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: /root/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USERLogin account for SSH connections to other nodes.
Note: non-root users cannot currently use SSH Hostbased Authentication. [default: root]
-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,240 kB]

-N, --no-sortDisable sorting log files together by time, print just one at a time.
-p SSH_PORT, --ssh-port=SSH_PORTPort to use for SSH connections to other nodes. Uses environment variable $CLX_SSH_PORT, if specified. [default: 22]
-s START, --start=STARTSpecify 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-passwdDo 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, --parallelExecute 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=TIMEOUTSpecify the timeout before failing a Telnet connection (in seconds).

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_KEYSSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: /root/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USERLogin account for SSH connections to other nodes.
Note: non-root users cannot currently use SSH Hostbased Authentication. [default: root]
-p SSH_PORT, --ssh-port=SSH_PORTPort 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-passwdDo 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_KEYSSH Key file to use for private-key auth to other nodes. Uses environment variable $CLX_SSH_KEY, if specified. [default: /root/.ssh/id_rsa]
-l SSH_USER, --ssh-user=SSH_USERLogin account for SSH connections to other nodes.
Note: non-root users cannot currently use SSH Hostbased Authentication. [default: root]
-p SSH_PORT, --ssh-port=SSH_PORTPort 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-passwdDo not attempt password SSH authentication.

slave

Displays replication slave information.

shell> clx [options] slave [slave name]

Command-Specific Option Exceptions

-n NODE, --node=NODEOption 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, --verboseDisplay more details.
  • No labels