How to use c4
This article explains how to use Exasol Deployment Tool (c4) to create and manage Exasol deployments.
Introduction
For information about how to install c4, see Install c4.
To run c4 commands, enter <path_to_c4_binary>/c4 <command> in a Linux terminal.
To get help in c4, use c4 --help. To get help for a specific command, use c4 <command> --help.
To avoid the need to prefix c4 commands with the path to the binary, add the path to your PATH variable. For information about how to modify PATH, refer to the documentation for your Linux distribution.
Configuration parameters
Configuration parameters for c4 can be specified in a configuration file and/or on the command line when creating a deployment. For general information about the c4 configuration parameters, see Parameters in c4.
Do not change configuration parameters that are not described in this documentation without consulting Exasol Support.
Create a deployment
To deploy Exasol as an application on Linux hosts, use c4 host play. For more information, see Install Exasol - step by step.
Monitor deployments
To see all your current deployments, use c4 ps.
./c4 ps
N PLAY_ID NODE MEDIUM INSTANCE DB_VERSION EXTERNAL_IP INTERNAL_IP STAGE STATE UPTIME TTL
┌─ 1 c3275f84 11 awscf r5d.large 8.27.0 203.0.113.11 10.0.0.11 d running 03:50:12 +∞
│ 1 c3275f84 12 awscf r5d.large 8.27.0 203.0.113.12 10.0.0.12 d running 03:50:13 +∞
│ 1 c3275f84 13 awscf r5d.large 8.27.0 203.0.113.13 10.0.0.13 d running 03:50:13 +∞
└─ 1 c3275f84 14 awscf r5d.large 8.27.0 203.0.113.14 10.0.0.14 d running 03:50:13 +∞
The following information is displayed for each node and deployment:
| Column | Description |
|---|---|
| N | The session index of the deployment |
| PLAY_ID | Unique identifier for the deployment |
| NODE | Node ID (if available) |
| MEDIUM | The medium that was used to create the deployment. |
| INSTANCE | Instance type for the node |
| EXTERNAL_IP | IP address of the node in the public network |
| INTERNAL_IP | IP address of the node in the private network |
| STAGE | The current deployment stage of the node, see Deployment stage |
| STATE | The current state of the node, see Node state |
| UPTIME | Time lapsed since the node was created |
| TTL | Time for the deployment to live (+∞ if unlimited/TTL unset) |
| Node state | Description |
|---|---|
| creating | Node is being created. |
| pending | Node is preparing to enter the running state. |
| running | Node is running at the indicated stage, see Deployment stage |
| stopped | Node is shut down and cannot be used. |
| rollingback | Node creation failed and is rolling back. |
| succeeded |
The previous deployment operation succeeded. NOTE: This node state does not indicate that the node is running, it only means that the last operation succeeded. In most cases, this node state indicates that node creation failed and was successfully rolled back. |
| failed | The previous deployment operation failed. |
The deployment is finished when all the database nodes have reached stage d and are in the running state.
For more details about how to use the c4 ps command, use c4 ps --help.
Troubleshooting c4 ps
In some cases c4 ps may time out while waiting for an instance to respond during the deployment process. This can for example be the case if there is a large geographical distance between the system running c4 ps and the instances. If the instance does not respond within the timeout period, c4 ps will consider the instance to be unreachable and report it as being in deployment stage a, even if the instance has booted up and services are running on the node.
You can increase the time limit for c4 ps to wait for instances to respond by setting a higher value in the CCC_USER_PS_REMOTE_TIMEOUT parameter in the c4 configuration. The default value is 3000 ms. For example, to set the timeout to 10 seconds:
CCC_USER_PS_REMOTE_TIMEOUT=10000
For more information on how to set configuration parameters in c4, see Parameters in c4.
Connect to a deployment
To connect to the nodes in a deployment, you can use c4 connect with either of the following syntax formats:
c4 connect -i PLAY_ID [-n NODE] [-s SUBSYSTEM]
c4 connect -t NUM[.NODE][/SUBSYSTEM]
| Variable | Description |
|---|---|
PLAY_ID
|
The unique identifier of a deployment. This is the safest way to indicate the target deployment in a command. |
NUM
|
The number of the deployment ( This number is dynamic and may change if you add or delete deployments. |
NODE
|
The cluster node ID ( If you do not specify a node, c4 will connect to the first active node in the deployment. |
SUBSYSTEM
|
The subsystem to connect to in the deployment (cos, host, or db). If you do not specify a subsystem, c4 will connect to the database (if it is online). |
| Subsystem | Description | Examples |
|---|---|---|
/host
|
Connect to the host OS on the node |
|
/cos
|
Connect to EXAClusterOS |
|
/db
|
Connect to the database (using the built-in SQL client) |
|
To disconnect from the deployment, use Control+D.
Connect using single-line command syntax
The c4 connect command supports a single-line command syntax that allows you to directly pass the command to be executed on the selected node. Instead of connecting to the node and returning the shell to the user, c4 connect will run the command and return the result, and will then disconnect from the node.
You can use the single-line syntax to pass a command to a subsystem in several different ways. The passed command must be enclosed in quotes ('COMMAND') unless it is a single command without options, such as ls.
If the passed command includes any CLI options, the command must be preceded by -- to prevent those options to be parsed by c4 connect itself. For example, if you enter the command line c4 connect -i c3275f84 -s host ls -t, the -t option for ls will be interpreted as the -t flag of c4 connect.
Alternatively, you can pass the command using standard input in Bash with <<<:
You can also create a script that contains one or several commands and redirect the script to stdin of c4 connect:
If the commands are in a script, do not prefix them with -- .
Examples
To learn about all the available options for the c4 connect command, use c4 connect --help.
If you connect using c4 connect -i PLAY_ID during an ongoing deployment process, c4 will output the deployment log in the terminal. This can be useful for troubleshooting.
The built-in SQL client in c4 always runs in autocommit mode.
Start nodes
To start all nodes of a deployment, use c4 up PLAY_ID. You can also specify only starting certain nodes in the deployment with the --nodes option. For example, c4 up --nodes 12 f7fdff8e starts node 12 in deployment f7fdff8e.
Stop nodes
To stop all nodes of a deployment, use c4 down PLAY_ID. You can also specify only stopping certain nodes in the deployment with the --nodes option. For example, c4 down --nodes 12 f7fdff8e stops node 12 in deployment f7fdff8e.
To prevent a risk of data loss, always stop the database before using the c4 down command.
c4 down will not safely shut down the database and may leave the database in a corrupted state. For this reason you should always stop the database before using this command. For information on how to safely shut down a database or cluster, see Stop a Database.
