Basic Use of c4

Exasol Deployment Tool (c4) is a command-line interface for creating and managing Exasol deployments. This section describes the most common use cases with c4.


To get general help for c4, use c4 --help. To get help for a specific command, use c4 <command> --help.

Configuration Parameters

The configuration parameters for c4 can be specified in a configuration file and/or on the command line when creating a deployment. For more information on how to specify parameters, see Parameters in c4.

For a description of the c4 parameters that are specific to AWS deployments, see Configure c4 for AWS.

Monitor Deployments

To list all your deployments in the currently specified AWS region, use c4 ps.

$ c4 ps
  ┌─  1  3a4a7d8d  10    awscf   c5d.large    c      running    04:35:15  +∞
  │   1  3a4a7d8d  11    awscf   c5d.2xlarge    d      running    04:35:16  +∞
  │   1  3a4a7d8d  12    awscf   c5d.2xlarge    d      running    04:35:16  +∞
  └─  1  3a4a7d8d  13    awscf   c5d.2xlarge    d      running    04:35:15  +∞

By default, c4 ps shows the deployments in the region specified in the CCC_AWS_REGION parameter. To quickly view deployments in other regions, you can specify a different region in the command. For example: CCC_AWS_REGION=eu-central-1 c4 ps.

The following information is displayed for each node and deployment:

Column Description
N Deployment number in the ps table
PLAY_ID Unique identifier for the deployment
NODE Node ID (if available)
MEDIUM Medium where the deployment was started (awscf = AWS CloudFormation)
INSTANCE Instance type for the node
EXTERNAL_IP External IP address
INTERNAL_IP Internal IP address
STAGE Current deployment stage of the node, see Deployment Stage
STATE 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:

Deployment Stage Description
a/a1 Cloud instance creation is in progress. No services are reachable at this stage.
b/b1 Host is booting up. The node can be accessed with SSH on port 22, and the c4 service is running.
c EXAClusterOS services are running and reachable.
d Database is running and reachable.
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.

The previous deployment operation succeeded.

This node state does not indicate that the node is running, only that the last operation (rollingback) succeeded.

failed The previous deployment operation failed.

For more details about the c4 ps command, use c4 ps --help.

Connect to 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.

Subsystem Description Examples
/cos Connect to EXAClusterOS on the target instance

c4 connect -t 1/cos

c4 connect -t 1.12/cos

/host Connect to the host Linux OS on the target instance

c4 connect -t 1/host

c4 connect -t 1.12/host

/db Connect to the database on the target instance. When the database is online, not specifying a subsystem opens an SQL Client connecting to the Database

c4 connect -t 1

c4 connect -t 1/db

c4 connect -t 1.12/db

Connecting to a target during a deployment will show the logs for that deployment.

For more details about the c4 connect command, use c4 connect --help.

To disconnect from the deployment, use Control+D.

Refresh MFA Token

If your organization uses MFA, you may need to refresh your AWS token occasionally. To refresh your token, use c4 aws token -f. You will be asked to enter your MFA token and can see the expiration date after the token is entered.

$ c4 aws token -f
Enter TOTP for device arn:aws:iam::12345678910:mfa/FirstnameLastname: 123456
Session token acquired - it expires on Fri, 20 Jan 2023 15:08:18 CET

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 10 abc123 starts the node 10 in deployment abc123. This command can be used to start all nodes when the database access node is offline.

c4 up is the equivalent of starting EC2 instances in the AWS console. The database is not started with this command. To start the database, see Start a Database

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 10 abc123 stops the node 10 in deployment abc123. This command can be used to stop the access node in a deployment.

To prevent a risk of data loss, always stop the database before using c4 down. This command is the equivalent of stopping EC2 instances in the AWS console, which will not safely shut down the database and may leave it in a corrupted state. To safely shut down a database or cluster, see Stop a Database or Stop a Cluster.

Remove Deployment

To remove a deployment, use c4 rm <PLAY_ID>.

$ c4 rm f7fdff8e

The rm command will destroy the deployment without any possible recovery.