How to use c4
This section describes the basics of how to use the Exasol Deployment Tool (c4) command-line tool 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.
If you add the path to the c4 binary to your PATH variable, you will not have to prefix c4 commands with the path. For information about how to modify PATH, refer to the documentation for your Linux distribution. In the following examples, the c4 commands are run without a path prefix.
To view the general help in c4, use c4 --help. To get help for a specific command, use c4 <command> --help.
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.
Create a Deployment
To deploy Exasol as an application on Linux hosts, use c4 host play. For more information, see Install Exasol.
Monitor Deployment Status
To see all your current deployments, use c4 ps.
$ c4 ps
N PLAY_ID NODE MEDIUM INSTANCE EXTERNAL_IP INTERNAL_IP STAGE STATE UPTIME TTL
┌─ 1 3a4a7d8d 11 host c5d.2xlarge 203.0.113.11 10.0.0.11 d running 04:35:16 +∞
│ 1 3a4a7d8d 12 host c5d.2xlarge 203.0.113.12 10.0.0.11 d running 04:35:16 +∞
└─ 1 3a4a7d8d 13 host c5d.2xlarge 203.0.113.13 10.0.0.13 d running 04:35:15 +∞The following information is displayed for each node and deployment:
| Column | Description |
|---|---|
| N | The number of the deployment in the current c4 ps table. |
| 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 | External IP address |
| INTERNAL_IP | Internal IP address |
| 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) |
During creation and/or startup, each node goes through the following deployment stages:
When a node is created it will be in one of the following states:
| 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 the c4 ps command, use c4 ps --help.
Connect to a Deployment
To connect to a deployment, use c4 connect -t <NUM>[.<NODE>][/<SUBSYSTEM>] where <NUM> is the deployment number N shown in c4 ps, <NODE> is the node ID NODE, and <SUBSYSTEM> is the subsystem to connect to. The subsystems are explained in the following table.
-
If you do not specify a node, c4 will connect to the first active node in the cluster.
-
If you do not specify a subsystem, c4 will connect to the database if it is online.
| Subsystem | Description | Examples |
|---|---|---|
/cos
|
Connect to EXAClusterOS on the target |
c4 connect -t 1/cos c4 connect -t 1.12/cos |
/host
|
Connect to the host Linux OS on the target |
c4 connect -t 1/host c4 connect -t 1.12/host |
/db
|
Connect to the database on the target (using a built-in SQL client) |
c4 connect -t 1 c4 connect -t 1/db c4 connect -t 1.12/db |
To disconnect, use Control+D.
For more details about the c4 connect command, use c4 connect --help.
Connecting to a target during an ongoing deployment process will show the deployment logs. This can be valuable for troubleshooting.
The built-in SQL client in c4 always runs in autocommit mode.
Start Nodes
If the access node is offline, you can use c4 to 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. This command can be used to start all nodes when the database access node is offline.
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.
