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.
| Option | Description | ||
|---|---|---|---|
| -C, --use-cache | Use cached cluster information, do not attempt to query the database for this information. | ||
| -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: 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. (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=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'
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. | ||
| -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 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_USER | Login 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-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). | ||
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: /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 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: /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 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. | ||