Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space ML1 and version 9.2

Table of Contents
maxLevel1
stylenone

Overview

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

Tip

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

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]
Note

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. Functions which rely on database information will not work normally.
-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: 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)

Tip

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.  

Table of Contents
maxLevel2
minLevel2
typeflat

Anchor
alters
alters
alters

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

Anchor
cache
cache
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=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.

Anchor
cmd
cmd
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, --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.

Anchor
cp
cp
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).

Anchor
dbrestart
dbrestart
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).

Anchor
dbstart
dbstart
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).

Anchor
dbstop
dbstop
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).

Anchor
debugdump
debugdump
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.

Anchor
disk
disk
disks

Displays disk information for the cluster.

shell> clx [options] disks

help

Displays help output for clx functions.

shell> clx [options] help [command]

Anchor
logdump
logdump
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_USERLogin 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-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.

Anchor
logfreq
logfreq
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-sensitiveInclude 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_USERLogin account for SSH connections to other nodes.
Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-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.


Anchor
logsearch
logsearch
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-sensitiveInclude 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_USERLogin account for SSH connections to other nodes.
Note: non-root users cannot currently use SSH Hostbased Authentication. [default: current user]
-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.

Anchor
nanny
nanny
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).

Anchor
pubkeyinstall
pubkeyinstall
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.

Anchor
pull
pull
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: ~/.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: current user]
-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.

Anchor
push
push
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: ~/.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: current user]
-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.

Anchor
slave
slave
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.

Anchor
space
space
space

Displays storage utilization information for the cluster.

shell> clx [options] space

Anchor
status
status
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.