ConfD

This section describes the ConfD API in Exasol.

ConfD is a low-level API that can be used to perform all administrative actions in an Exasol system. You can interact with ConfD directly by connecting to a node in the cluster and using the confd_client command-line tool, or from an external tool using XML-RPC.

ConfD abstracts the administration and configuration tasks into jobs that can take various parameters. You submit a job by connecting to a node directly on the command line or using XML-RPC. The jobs are then orchestrated into a scheduler that executes them asynchronously.

In the ConfD scheduler, each job has its own pipeline in which several stages are defined. The scheduler saves the result for the job at each stage. The client that submitted the job can do additional actions while the pipeline is being executed.

The final stage depends on whether the job modifies the database or if it is a read-only job. The job is marked as finished when the final stage has completed. The client can then query the result using its job ID.

Some settings have no dedicated ConfD jobs and are instead managed with the general_settings job. To know more about these settings, use the settings_list job.

Authentication

ConfD supports basic authentication with a user and password. When you deploy a new Exasol instance, the deployment process creates the user admin with the password specified in the CCC_PLAY_ADMIN_PASSWORD parameter in the c4 configuration. You can change this password using the ConfD job user_passwd.

You can also create a new user to interact with ConfD. For more information about creating users, see Add Users.

The new user must be assigned to the exaadm group.

If you created a new user, we recommend using confd_client instead of XML-RPC to avoid having to authenticate with a new user.

How to use ConfD

ConfD is available on all nodes. You can interact with ConfD directly on a node using the command line tool confd_client, or indirectly using XML-RPC to connect to the access node. The names of the ConfD jobs and parameters are the same regardless of if you use confd_client or XML-RPC.

The code examples in the Administration section of this documentation usually show how to submit jobs using confd_client. If you want to use XML-RPC to carry out an administration task, refer to the respective job descriptions in the ConfD reference (this section) for guidance.

confd_client

The command-line tool confd_client is available on all nodes and allows you to interact directly with ConfD in a terminal after connecting to a node.

ConfD jobs are executed with the user that is logged in to the node, which in most cases is root. There is no extra authentication step when using confd_client in this way.

To use confd_client, connect to the deployment using c4 connect, then run confd_client in the cos environment.

c4 connect -t1/cos

To get more details about how to use confd_client, use confd_client --help when you have connected to the node.

confd_client --help

Syntax of confd_client commands

To run a job using confd_client you can use different syntax formats. In most cases, you can use any of the syntax formats for a command. For more information about the correct syntax for a specific ConfD job, refer to the job description in this reference.

In the following examples, the job db_start is executed with the parameter db_name using three different formats:

confd_client -c db_start -a 'db_name: Exasol'
# this format can only be used for jobs that only have a single parameter

confd_client -c db_start -a '{db_name: Exasol}'

confd_client db_start db_name: Exasol

XML-RPC using Python

You can interact with ConfD using an XML-RPC interface in Python. By default, the XML-RPC interface is available on port 20003 on the access node.

XML-RPC can only be used on the access node, not on a database node.

When using XML-RPC, you must authenticate with a user. For more details, see Authentication.

Example:

import xmlrpc.client
import requests, urllib3, ssl
import sys
import json
import pprint

# Disable SSL warnings
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# Enter the IP address of the database access node and the COS port (default port: 20003)
database_host = '203.0.113.78:20003'

# Enter the username and password you are connecting with.
user = 'admin' 
pw = 'exasol'

connection_string = f'https://{user}:{pw}@{database_host}'

sslcontext = ssl._create_unverified_context()

# Establish connection 
conn = xmlrpc.client.ServerProxy(connection_string, context = sslcontext, allow_none=True)

Once you are connected, you can execute a job:

# Choose the job you want to run
job_name = 'db_start'

# Set the parameters for the chosen job
params = {'db_name': 'Exasol'}

# Execute the job and wait for it to finish and return the result
conn.job_exec(job_name, {'params': params})

For more examples on how you can interact with ConfD using XML-RPC, see the confd_xmlrpc script on GitHub.

ConfD jobs

BucketFS jobs

Database jobs

Group jobs

Infrastructure jobs

License jobs

Node jobs

Object Volume Jobs

Other jobs

Plugin jobs

Remote volume jobs

Storage jobs

User jobs