Skip to content

Configuration Management

This feature enables administrators to define, apply, and monitor configurations for entire clusters or individual database nodes, ensuring consistency and compliance with best practices. With configuration management, users can automate updates, track configuration changes, and revert to previous versions if needed, simplifying maintenance and reducing the risk of misconfigurations that could impact performance or security.

Access the configuration management section

Log in to your ClusterControl GUI → choose a database cluster → Manage → Configurations. This will bring up a panel where you can view and edit configurations.

For CLI, the context of the configuration management is bounded at the node level. Hence, the --nodes flag is mandatory with a proper <host>:<port> value.

  • List all database configuration options for a MySQL database node, 192.168.99.3:

    s9s node --list-config --cluster-id=36 --nodes=192.168.99.3:3306

  • List all database configuration options for a PostgreSQL database node, 192.168.99.6:

    s9s node --list-config --cluster-id=37 --nodes=192.168.99.6:5432

Refresh configuration files

Click on Refresh config to get the latest configuration files from all nodes managed by ClusterControl. This will trigger a job to pull the latest configuration files from all nodes. The configuration files output listed will be refreshed after the job is successfully executed.

Suppose the cluster ID is 36, and wait for the refresh configuration job to finish:

s9s cluster --import-config --cluster-id=36 --wait

View and edit configuration files

  1. In the Configuration Management panel, you will see a list of configuration files for the selected database technology (e.g., my.cnf for MySQL, postgresql.conf for PostgreSQL, proxysql.cnf for ProxySQL).
  2. Select a configuration file to view its current parameters. Selecting a configuration will appear as a new tab in the editor area.
  3. ClusterControl allows you to edit configurations directly within this interface, similar to a text editor. Make your changes as needed, adjusting parameters to meet your performance, security, or operational needs.

  4. Click Save to apply the change. ClusterControl will push the changes into the configuration file on the corresponding database node. If you would like to change a configuration across all nodes in the cluster, use the Edit params button as explained in the next section.

    Info

    Editing the configuration file with the text editor will only push the configurations to the database configuration file, and not the database runtime. Restart the database service to apply those changes into runtime, or use the Edit params button.

For CLI, the context of the configuration management is bounded at the node level. Hence, the --nodes flag is mandatory with a proper <host>:<port> value.

  • Change a MySQL configuration option for a MySQL database node 192.168.99.3 called max_connections which is located under the [mysqld] section:

    s9s node \
    --change-config \
    --cluster-id=36 \
    --nodes='192.168.99.3:3306' \
    --opt-group=mysqld \
    --opt-name=max_connections \
    --opt-value=300

  • Change a PostgreSQL configuration option for a PostgreSQL database node, 192.168.99.6 called log_line_prefix:

    s9s node \
    --change-config \
    --cluster-id=37 \
    --nodes='192.168.99.6:5432' \
    --opt-name=log_line_prefix \
    --opt-value='%m '

Compare new configuration with existing configuration

Use Show diff button to compare the new configuration with the existing configuration before hitting the Save button. ClusterControl will open a new panel to compare these two configuration versions side-by-side before and after changes.

The left panel displays the existing configuration (changes are highlighted in red) while the right-panel displays the currently modified (yet to apply) configuration (changes are highlighted in green).

Click Revert Changes to rollback and discard the change, or click Save to commit and push the new configuration to the database node. ClusterControl will perform a file-system replace to the existing configuration file on the database node with the new version.

Note

ClusterControl does not store configuration changes history so there is no file versioning after saving. Only one version exists at one time on the managed node.

Apply configuration changes across nodes

Use Edit params if you want to change a specific configuration option across database nodes in the cluster.

  1. Click on Edit params button and ClusterControl will load all configuration options in a table format.
  2. Look up the configuration option in the filtering field and you can edit the corresponding configuration option by clicking on the pencil icon.
  3. After making changes, press Enter and the configuration will be pushed to all database nodes' configuration file and runtime (only if applicable).

For CLI, the command must be repeated multiple times for every database node.

  • Change a MySQL configuration option for multiple MySQL database nodes in cluster ID 36 (192.168.99.3, 192.168.99.4, 192.168.99.5) called max_connections which is located under the [mysqld] section:

    s9s node \
    --change-config \
    --cluster-id=36 \
    --nodes='192.168.99.3:3306' \
    --opt-group=mysqld \
    --opt-name=max_connections \
    --opt-value=300

s9s node \
    --change-config \
    --cluster-id=36 \
    --nodes='192.168.99.4:3306' \
    --opt-group=mysqld \
    --opt-name=max_connections \
    --opt-value=300

s9s node \
    --change-config \
    --cluster-id=36 \
    --nodes='192.168.99.5:3306' \
    --opt-group=mysqld \
    --opt-name=max_connections \
    --opt-value=300

  • Change a PostgreSQL configuration option for multiple PostgreSQL database nodes in cluster ID 37, (192.168.99.6, 192.168.99.7) called log_line_prefix:

    s9s node \
    --change-config \
    --cluster-id=37 \
    --nodes='192.168.99.6:5432' \
    --opt-name=log_line_prefix \
    --opt-value='%m '

s9s node \
    --change-config \
    --cluster-id=37 \
    --nodes='192.168.99.7:5432' \
    --opt-name=log_line_prefix \
    --opt-value='%m '

Monitor configuration consistency

ClusterControl allows you to monitor and verify that configurations are consistent across your cluster. Go to ClusterControl GUI → choose a database cluster → Performance → DB Variables to identify configuration drift (differences in configurations between nodes).

Entries highlighted in red indicate the configuration options are not identical across nodes. Note that some configuration options may be distinct across nodes and does not necessary mean a poor configuration.

To compare output between two commands, we can use diff -y with side-by-side output.

  • Compare the current database configurations (from the configuration file) for two MySQL database nodes, 192.168.99.3 and 192.168.99.4:
diff -y <(s9s node --list-config --nodes=192.168.99.3:3306) <(s9s node --list-config --nodes=192.168.99.4:3306)
  • Compare the current database configurations (from the configuration file) for two PostgreSQL database nodes, 192.168.99.7 and 192.168.99.8:
diff -y <(s9s node --list-config --nodes=192.168.99.7:5432) <(s9s node --list-config --nodes=192.168.99.8:5432)

Configuration template

All services configured by ClusterControl use a base configuration template available under /usr/share/cmon/templates on the ClusterControl node. You can directly modify the file to suit your deployment policy however, this directory will be replaced after a package upgrade.

To make sure your custom configuration template files persist across upgrades, store your template files under the /etc/cmon/templates directory (ClusterControl 1.6.2 and later). When ClusterControl loads up the template files for deployment, files under /etc/cmon/templates will always have higher priority over the files under /usr/share/cmon/templates. If two files having identical names exist on both directories, the one located under /etc/cmon/templates will be used.

Here is an example of how one would create a custom configuration template file:

# on the ClusterControl node, as privileged user
mkdir -p /etc/cmon/templates
cp /usr/share/cmon/templates/my.cnf.repl80 /etc/cmon/templates/my.cnf.repl80-custom
vi /etc/cmon/templates/my.cnf.repl80-custom     # make your changes and save

Go to the ClusterControl GUI → Deploy a cluster → Create a database cluster and start deploying a database cluster. Choose the created configuration file above from the Configuration template dropdown.

Dynamic variables

Inside the provided template files, many configuration variables are configurable dynamically (depending on the detected host specifications and user's input in the deployment wizard) by ClusterControl during deployment. These variables are represented with a capital letter enclosed by @, for example, @DATADIR@. The following shows the list of variables supported by the ClusterControl, grouped by the cluster type:

Variable Description
@BASEDIR@ The default is /usr. Value specified during cluster deployment takes precedence.
@DATADIR@ The default is /var/lib/mysql. Value specified during cluster deployment takes precedence.
@MYSQL_PORT@ The default is 3306. Value specified during cluster deployment takes precedence.
@BUFFER_POOL_SIZE@ Automatically configured based on the host’s RAM.
@LOG_FILE_SIZE@ Automatically configured based on the host’s RAM.
@LOG_BUFFER_SIZE@ Automatically configured based on the host’s RAM.
@BUFFER_POOL_INSTANCES@ Automatically configured based on the host’s CPU.
@SERVER_ID@ Automatically generated based on member’s server-id.
@SKIP_NAME_RESOLVE@ Automatically configured based on MySQL variables.
@MAX_CONNECTIONS@ Automatically configured based on the host’s RAM.
@ENABLE_PERF_SCHEMA@ The default is disabled. Value specified during cluster deployment takes precedence.
@WSREP_PROVIDER@ Automatically configured based on the Galera vendor.
@HOST@ Automatically configured based on hostname/IP address.
@GCACHE_SIZE@ Automatically configured based on disk space.
@SEGMENTID@ The default is 0. Value specified during cluster deployment takes precedence.
@WSREP_CLUSTER_ADDRESS@ Automatically configured based on members in the cluster.
@WSREP_SST_METHOD@ Automatically configured based on the Galera vendor.
@BACKUP_USER@ Default is backupuser.
@BACKUP_PASSWORD@ Automatically generated and configured for backupuser.
@GARBD_OPTIONS@ Automatically configured based on garbd options.
@READ_ONLY@ Automatically configured based on replication role.
@SEMISYNC@ The default is disabled. Value specified during cluster deployment takes precedence.
@NDB_CONNECTION_POOL@ Automatically configured based on the host’s CPU.
@NDB_CONNECTSTRING@ Automatically configured based on members in the MySQL cluster.
@LOCAL_ADDRESS@ Automatically configured based on the host’s address.
@GROUP_NAME@ Default is grouprepl. Value specified during cluster deployment takes precedence.
@PEERS@ Automatically configured based on members in the Group Replication cluster.
Variable Description
@DATADIR@ The default is /var/lib/mongodb. Value specified during cluster deployment takes precedence.
@MONGODB_PORT@ The default is 27017, 27018, 27019 (depending on the cluster type). Value specified during cluster deployment takes precedence.
@LOGDIR@ Automatically configured based on vendor.
@HOST@ Automatically configured based on hostname/IP address.
@SMALLFILES@ Automatically configured based on disk space.
@PIDFILEPATH@ Automatically configured based on MongoDB data directory.
@REPLICASET_NAME@ The default is my_mongodb_N. Value specified during cluster deployment takes precedence.
Variable Description
@BIND_ADDRESS@ Automatically configured based on the host’s address.
@PORT@ The default is 6379. Value specified during cluster deployment takes precedence.
@DATADIR@ The default is /var/lib/redis. Value specified during cluster deployment takes precedence.
@REPLICATION_PASSWORD@ Automatically configured based on the value specified during the deployment.
@REPLICA_OF@ Automatically configured based on members in the topology.
@CLUSTER_CONFIG_FILE@ Automatically configured based on cluster type.
@CLUSTER_NODE_TIMEOUT@ The default is 15000 in milliseconds. Value specified during cluster deployment takes precedence.
@CLUSTER_BUS_PORT@ The default is 16379. Value specified during cluster deployment takes precedence.
@CLUSTER_REPLICA_VALIDITY_FACTOR@ The default is 10. Value specified during cluster deployment takes precedence.
@ACL_DB_ADMIN_USER@ Automatically configured based on members in the topology.
@SENTINEL_PASSWORD@ Automatically configured based on the value specified during the deployment.
@PASSWORD@ Automatically configured based on the value specified during the deployment.
@MAXMEMORY_BYTES@ Automatically configured based on the host’s RAM.
@MAXMEMORY_POLICY@ The default is allkeys-lru.
@CLUSTER_ENABLED@ Automatically configured based on cluster type.
Variable Description
@CLUSTER_NAME@ Automatically configured based on the value specified during the deployment.
@NODE_NAME@ Automatically configured based on hostname/IP address.
@NODE_ROLES@ Automatically configured based on node's role.
@DATADIR@ The default is /var/lib/elasticsearch. Value specified during cluster deployment takes precedence.
@SNAPSHOTS_LOCATION@ Automatically configured based on the value specified during the deployment.
@BIND_ADDRESS@ Automatically configured based on hostname/IP address.
@PUBLISHED_ADDRESS@ Automatically configured based on hostname/IP address.
@HTTP_PORT@ The default is 9200. Value specified during cluster deployment takes precedence.
@DISCOVERY_SEED_HOSTS@ Automatically configured based on hostname/IP address of the members in the topology.
@CLUSTER_INITIAL_MASTER_NODES@ Automatically configured based on members in the topology.
@SECURITY_ENABLED@ Automatically configured based on the value specified during the deployment.
Copyright © 2014-2025 Severalnines AB. All rights reserved.

Severalnines and ClusterControl are registered trademarks in the US, UK, and EU. The 3rd-party trademarks on this site are property of their respective owners and are used for referential purposes only.

Made with Material for MkDocs