1. Home
  2. Docs
  3. ClusterControl
  4. Components
  5. ClusterControl Controller
  6. Configuration Options

Configuration Options

Values that consist of special characters must be enclosed with a single-quote. Any value change to the configuration options that shall be applied to the CMON configuration file or indirectly via UI (see Runtime Configuration) or through s9s command, requires a service restart before they are applied. The configuration options can be divided into the following categories:

  1. General Cluster
  2. CMON
  3. Operating System
  4. SSH
  5. ClusterControl Recovery
  6. Monitoring and Thresholds
  7. Query Monitor
  8. Backup
  9. MySQL/MariaDB Nodes
  10. MongoDB Nodes
  11. PostgreSQL/TimescaleDB Nodes

Following is the list of configuration options inside the CMON configuration file. You can also see them by using --help-config the parameter in the terminal:

$ cmon --help-config

Applying changes to CMON configuration options

It is worth noting that CMON configuration options can be set in multiple ways. This can be done by the following approaches:

  • Editing the file /etc/cmon.d/cmon_X.cnf, where X is the cluster id of your cluster. Although this approach is not recommendable and strongly discourage.
  • Via the web UI by going to ClusterControl → DB cluster → Settings → Runtime Configuration. Then search for the desired option you plan to change.
  • Using s9s cluster command. e.g.
$ s9s cluster --change-config --cluster-id=252 --opt-name=replication_pre_failover_script --opt-value=""

There are certain variables that upon changes via runtime, shall reflect immediately. However, it is strongly recommended that you have to restart the cmon daemon whenever you apply changes to the configuration options.

General Cluster

Option Description
cluster_id=<integer>
  • Cluster identifier. This will be used by CMON to indicate which cluster to provision. It must be unique, two clusters can not share the same ID.
  • Example: cluster_id=1
name=<string>
  • Cluster name. The cluster name configured under ClusterControl → DB cluster → Settings → CMON Settings → Cluster Name precedes this.
  • Example: name='Galera Cluster'
  • Another alias: cluster_name
type=<string>
  • Cluster type. Supported values are “galera”, “mysql_single”, “mysqlcluster”, “mongodb”, “postgresql_single”, “replication”, “group_replication”.
  • Example: type=galera
  • Another alias: cluster_type
tags=<string>
  • A set of strings the user can specify to tag a cluster.
  • Example: tag="production;galera;MySQL;app1"
created_by_job=<integer>
  • The ID of the job created this cluster. This is usually automatically generated by ClusterControl.
  • Example: created_by_job=13
vendor=<string>
  • Database vendor name. ClusterControl needs to know this in order to distinguish the vendor’s relevant naming convention especially for package name, daemon name, deployment steps, recovery procedures, and lots more.
  • Supported value at the moment is “oracle”, “percona”, “codership”, “mariadb”, “10gen”.
  • Example: vendor=percona
use_internal_repos=<boolean integer>
  • Setting which disabled the 3rd party repository to be set up. Default is 0 (false).
enable_html_emails=<boolean integer>
  • Enables sending of HTML e-mails. Default is 1 (true).
frontend_url=<url>
  • The ClusterControl URL to be embedded inside e-mail notifications. The URL sent in the emails to direct the recipient to the ClusterControl UI.
  • Example: frontend_url='https://monitor.domain.com/clustercontrol'
error_report_dir=<path>
  • The storage location of error reports on the controller node.
ops_report_retention=<integer>
  • How many days to keep operational reports. Operational Reports matching retention period are removed. Default is 31.

CMON

Option Description
hostname=<string>
  • Hostname or IP address of the controller host.
  • Example: hostname=192.168.0.10
controller_id=<integer>
  • An arbitrary identifier string of this controller instance.
  • Example: controller_id=1
mode=<string>
  • CMON role. Supported values are “controller”, “dual”, “hostonly”.
  • Example: mode=controller
agentless=<boolean integer>
  • CMON controller mode (deprecated). Agents are no longer supported. 0 for agent-based or 1 for agentless (default).
  • Example: agentless=1
logfile=<path>
  • CMON log file location. This is where CMON logs its activity. The file will be automatically generated if it doesn’t exist. CMON will write to Syslog by default.
  • Example: logfile=/var/log/cmon.log
pidfile=<path>
  • CMON process identifier file directory. Keep the default value is recommended.
  • Example: pidfile=/var/run
mysql_hostname=<string>
  • The MySQL hostname or IP address where the CMON database resides. Using an IP address is recommended. Default is 127.0.0.1.
  • Example: mysql_hostname=192.168.0.5
  • Other aliases: cmon_mysql_hostname, cmondb_hostname,local_mysql_hostname, cmon_local_mysql_hostname.
mysql_password=<string>
  • The MySQL password for user cmon to connect to CMON database.
  • Example: mysql_password='cM%^nP4ss
  • Other aliases: cmon_mysql_password, cmondb_password
mysql_port=<integer>
  • The MySQL port used by CMON to connect to the CMON database.
  • Example: mysql_port=3306
  • Other aliases: cmon_mysql_port, cmondb_port
mysql_socket=<boolean integer>
  • The local UNIX socket file to be used for MySQL connection (if set, TCP will not be used).
  • Example: mysql_socket=/var/lib/mysql/mysqld.sock
mysql_basedir=<path>
  • The MySQL base directory used by CMON to find MySQL client-related binaries.
  • Example: mysql_basedir=/usr
  • Another alias: basedir
mysql_bindir=<path>
  • The MySQL binary directory used by CMON to find MySQL client-related binaries.
  • Another alias: bindir
  • Example: mysql_bindir=/usr/bin
mysql_scriptdir=<path>
  • The scripts dir of MySQL installation.
config_file_path=<path>
  • The config file path (read-only) for CMON instance.
cmon_db=<string>
  • CMON database name. Default to “cmon”.
  • Example: cmon_db=cmon
  • Another alias: cmondb_database
cmon_user=<string>
  • The username for the CMON database. Default to “cmon”.
  • Example: cmon_user=cmon
  • Another alias: cmondb_user
cmondb_ssl_key=<path>
  • Path to SSL key, for SSL encryption between the CMON process and the CMON database.
  • Example: cmondb_ssl_key=/etc/ssl/mysql/client-key.pem
cmondb_ssl_cert=<path>
  • Path to SSL certificate, for SSL encryption between the CMON process and the CMON database.
  • Example: cmondb_ssl_cert=/etc/ssl/mysql/client-cert.pem
cmondb_ssl_ca=<path>
  • Path to SSL CA, for SSL encryption between the CMON process and the CMON database.
  • Example: cmondb_ssl_ca=/etc/ssl/mysql/ca-cert.pem
cluster_ssl_key=<path>
  • Path to SSL key, for SSL encryption between the CMON process and managed MySQL Servers.
  • Example: cluster_ssl_key=/etc/ssl/mysql/client-key.pem
cluster_ssl_cert=<path>
  • Path to SSL certificate, for SSL encryption between the CMON process and managed MySQL Servers.
  • Example: cluster_ssl_cert=/etc/ssl/mysql/client-cert.pem
cluster_ssl_ca=<path>
  • Path to SSL CA, for SSL encryption between CMON and managed MySQL Servers.
  • Example: cluster_ssl_ca=/etc/ssl/mysql/ca-cert.pem
cluster_certs_store=<path>
  • Directory path to store SSL-related files. This is required when you want to add a new node in an encrypted Galera cluster.
  • Example: cluster_certs_store=/etc/ssl/galera/cluster_1
cluster_ssl_enforce=<boolean integer>
  • If set to 1 (true), then SSL is required. Default is 0 (false).
  • CMON is going to raise a critical alarm if an SSL connection can not be made to the node.
  • Example: cluster_ssl_enforce=1
rpc_key=<string>
  • Unique secret token for authentication. To interact with individual clusters via CMON RPC interface (port 9500), one must use this key, or else you would get ‘HTTP/1.1 403 Access denied’. ClusterControl UI needs this key stored as RPC API Token to communicate with the CMON RPC interface.
  • Each cluster should be configured with a differentrpc_key value. This value is automatically generated when a new cluster/server is created or added into ClusterControl.
  • Example: rpc_key=VJZKhr5CvEGI32dP
  • Another alias: rpc_api_key
rpc_version=<string>
  • The RPC version created the cluster.
net_read_timeout=<integer>
  • Network read timeout value in seconds (DB connections). Default is 10.
net_write_timeout=<integer>
  • Network write timeout value in seconds (DB connections). Default is 10.
connect_timeout=<integer>
  • Network connect timeout value in seconds (DB connections). Default is 10.
owner=<integer>
  • The CMON user ID of the owner.
group_owner=<integer>
  • The CMON group ID of the group owner.
cdt_path=<string>
  • The location in the CMON Directory Tree (CDT). See s9s-tree.
acl=<string>
  • The Access Control List is a string controlling the access to the cluster object. See ACL Text Forms.
staging_dir=<path>
  • Staging path for temporary files.
  • Example: staging_dir=/home/ubuntu/s9s_tmp
  • Another alias: stagingdir
plugin_dir=<path>
  • Directory path for CMON plugins. Default to /var/cmon/plugins
  • Another alias: plugin_path
cmon_use_mail=<boolean integer>
  • Setting to use the mail command for sending out emails. Default is 0 (false).
  • Example: cmon_use_mail=1
cmon_mail_sender=<email>
cmon_pool_size=<integer>
  • The connection pool size to the cmon database. Default is 64.
  • Example: cmon_pool_size=32
cmon_ha_heartbeat_interval_millis=<integer>
  • CMON HA heartbeat interval measured in milliseconds. Default is 1000.
cmon_ha_heartbeat_millis_rand_max=<integer>
  • CMON HA timeout random component max value. Default is 2500.
cmon_ha_heartbeat_network_timeout=<integer>
  • CMON HA heartbeat network connection timeout measured in seconds. Default is 5.
cmon_ha_heartbeat_timeout_millis=<integer>
  • CMON HA timeout for heartbeats in milliseconds. Default is 5000.
cmon_ha_max_send_retry=<integer>
  • CMON HA log send maximum retry count. Default is 15.
cmon_ha_send_retry_delay=<integer>
  • CMON HA log send retry delay in seconds. Default is 3.
vault_addr=<URI>
vault_auto_migrate=<boolean integer>
  • Enable this to auto-move all the secrets to the configured Vault instance. Default is 0 (false). See Hashicorp Vault Integration.
  • Example: vault_auto_migrate=1
vault_path=<path>
  • The secrets path prefix for ClusterControl credentials. Default value is clustercontrol. The controller is going to store the data within this path, e.g clustercontrol/controller_UUID/cluster_ID/mysql_password. Each ClusterControl instance and controller, and cluster can have its unique namespace. See Hashicorp Vault Integration.
  • Example: vault_path="staging/clustercontrol"
vault_token=<string>
  • A token used by the controller to authorize itself against the Vault server. The Vault token is created by the Vault server. When the vault_token is present credentials for new clusters will be stored in Vault and not in the cmon configuration files. See Hashicorp Vault Integration.

Operating System

Option Description
os=<string>
  • The operating system distribution runs across the cluster, including ClusterControl host. ‘redhat’ for RedHat-based distributions (CentOS/Red Hat Enterprise Linux/Oracle Linux) or ‘debian’ for Debian-based distributions (Debian/Ubuntu).
  • Example: os=redhat
osuser=<string>
  • Operating system user that will be used by CMON to perform automation tasks like cluster recovery, backups and upgrades. This user must be able to perform super-user activities. Using root is recommended.
  • Example: os_user=root
  • Other aliases: os_user, ssh_user
sudo=<command>
  • The command used to obtain superuser permissions. If sudo user requires a password, specify the sudo command with sudo password here. The sudo command must be trimmed by redirecting stderr to somewhere else. Therefore, it is compulsory to have -S 2>/dev/null appended in the sudo command.
  • Example: sudo="echo 'My5ud0' | sudo -S 2>/dev/null"
  • Another alias: sudo_opts
osuser_home=<path>
  • The home directory of the user used on nodes.
  • Example: osuser_home=/home/ubuntu/
  • Other aliases: os_user_home, ssh_user_home
software_packagedir=<path>
  • This is the storage location of software packages, i.e, all necessary files to successfully install a node, if there is no yum/apt repository available, must be placed here. Applies mainly to MySQL Cluster or older Codership/Galera installations.
local_repo_name=<string>
  • The used local repository names for cluster deployment.
  • Example: local_repo_name=epel
init_name=<string>
  • The OS service name used for starting/stopping the database servers.
  • Another alias: init_service_name
  • Example: init_name=postgresql-9.6
disable_numa=<boolean integer>
  • Not to use NUMA support dependent features. Default is 1 (enabled).

SSH

Description

Option Description
ssh_identify=<path>
  • The SSH key or key pair file will be used by CMON to connect managed nodes (including ClusterControl node) passwordless. If undefined, CMON will use the home directory of os_user and look for .ssh/id_rsa file.
  • Example: ssh_identity=/root/.ssh/id_rsa
  • Other aliases: ssh_keypath, identity_file
ssh_port=<integer>
  • The SSH port used by CMON to connect to managed nodes. If undefined, default to 22.
  • Example: ssh_port=22
ssh_acquire_tty=<boolean integer>
  • Setting for libssh – should it acquire a remote tty. Default is 1 (true).
  • Example: ssh_acquire_tty=1
ssh_password=<string>
  • The SSH password used for connection to nodes. This is not recommended, hence ClusterControl enforces the passwordless SSH instead.
ssh_timeout=<integer>
  • Network timeout value in seconds for SSH connections. Default is 30.
  • Example: ssh_timeout=30
  • Another alias: libssh_timeout=<integer>
libssh_loglevel=<integer>
  • Setting for libssh logging verbosity to stdout. Accepted values are 0 (NONE), 1 (WARN), 2 (INFO), 3 (DEBUG), 4 (TRACE).
  • Example: libssh_loglevel=2
slow_ssh_warning=<integer>
  • A warning alarm will be raised if it takes longer than the specified time to set up an SSH connection (secs). Default is 6 seconds.
  • Example: slow_ssh_warning=6
slow_ssh_critical=<integer>
  • A critical alarm will be raised if it takes longer than the specified time to set up an SSH connection (secs). Default is 12 seconds.
  • Example: slow_ssh_critical=12

ClusterControl Recovery

Option Description
enable_cluster_autorecovery=<boolean integer>
  • If undefined, CMON defaults to 0 (false) and will NOT perform automatic recovery if it detects cluster failure. The supported value is 1 (cluster recovery is enabled) or 0 (cluster recovery is disabled).
enable_node_autorecovery=<boolean integer>
  • If undefined, CMON defaults to 0 (false) and will NOT perform automatic recovery if it detects node failure. The supported value is 1 (node recovery is enabled) or 0 (node recovery is disabled).
enable_autorecovery=<boolean integer>
  • If undefined, CMON defaults to 0 (false) and will NOT perform automatic recovery if it detects node or cluster failure.
  • The supported value is 0 (cluster and node recovery are disabled) or 1 (cluster and node recovery are enabled). This setting will internally set enable_node_autorecovery and  enable_cluster_autorecovery to the specified value.
node_recovery_lock_file=<path>
  • Specify a lock file and if present on a node, the node will not recover. The administrator is responsible to create/remove the file.
  • Example: node_recovery_lock_file=/root/do_not_recover
node_recovery_timeout=<integer>
  • Stop the recovery process after it reaches this timeout. Default is 28800 seconds (8 hours).
  • Another alias: add_node_timeout
add_cluster_timeout=<integer>
  • The timeout value for cluster starts during deployment (currently NDB only) in seconds. Default is 28800 seconds (8 hours).
send_clear_cluster_failure=<boolean integer>
  • Send notification email if a cluster failure event is cleared (meaning the cluster is recovered). Default is true.
  • Another alias: send_clear_alarm

Monitoring and Thresholds

Option Description
monitored_mountpoints=<paths>
  • The MySQL/MongoDB/PostgreSQL data directory used by database nodes for disk performance in a comma-separated list.
  • Example: monitored_mountpoints=/var/lib/mysql,/mnt/data/mysql.
  • Another alias: monitored_mount_points
monitored_nics=<string>
  • List of network interface names to be monitored for network performance in a comma-separated list.
  • Example: monitored_nics=eth1,eth2
db_stats_collection_interval=<integer>
  • Database metrics sampling interval in seconds. The lowest value is 1. Default is 30 seconds.
  • Example: db_stats_collection_interval=30
host_stats_collection_interval=<integer>
  • Host metrics sampling interval in seconds. The lowest value is 1. Default is 30 seconds.
  • Example: host_stats_collection_interval=30
host_stats_window_size=<integer>
  • Setting the window size (in seconds) to examine (CPU, memory..) stats to raise/clear host stats alarms. The default is 180 seconds.
  • Example: host_stats_window_size=300
lb_stats_collection_interval=<integer>
  • Load balancer stats collection interval. Default is 15.
  • Example: lb_stats_collection_interval=30
db_schema_stats_collection_interval=<integer>
  • How often database growth and table checks are performed in seconds. This translates to information_schema queries. Default is 10800 seconds (3 hours). 0 means disabled.
  • Example: db_schema_stats_collection_interval=10800
db_proc_stats_collection_interval=<integer>
  • Setting for database process stats collection interval. The default is 3 seconds. The minimum allowed value is 1 second.
  • Example: db_proc_stats_collection_interval=5
db_log_collection_interval=<integer>
  • Database log files collection interval. Default is 600.
  • Example: db_log_collection_interval=600
db_deadlock_check_interval=<integer>
  • How often to check for deadlocks in seconds. Deadlock detection will affect CPU usage on database nodes. Default is 0, which means disabled.
  • Example: db_deadlock_check_interval=600
db_schema_max_objects=<integer>
  • The maximum number of database objects that ClusterControl will pull from monitored database nodes. If the number of schema objects (tables, triggers, views) is greater than this then no schema analysis will be done.
  • Example: db_schema_max_objects=500
db_exporter_user=<string>
  • Database user for Prometheus exporter. Default is db_exporter_user=cmonexporter
db_exporter_password=<string>
  • Password for db_exporter_user
  • Example: db_exporter_password=myS3cret
db_exporter_use_nonlocal_address=<boolean integer>
  • Specifies if Prometheus exporter should connect to the non-local address of the DB services, instead of 127.0.0.1. Default is 0 (false).
  • Example: db_exporter_use_nonlocal_address=1
db_hourly_stats_collection_interval=<integer>
  • Database statistic collections interval in seconds. Default is 5.
  • Example: db_hourly_stats_collection_interval=5
enable_mysql_timemachine=<boolean integer>
  • This determines whether ClusterControl should enable MySQL time machine status and variable collections. The status time machine allows you to select the status variable for a time range and compare the values at the start and end of that range from ClusterControl UI. Default is 0, meaning it is disabled.
  • Example: enable_mysql_timemachine=1
swap_warning=<integer>
  • Warning alarm threshold for swap usage. Default is 5. Also configurable at ClusterControl → {cluster_id} → Settings → Thresholds.
  • Example: swap_warning=20
swap_critical=<integer>
  • Critical alarm threshold for swap usage. Default is 20. Also configurable at ClusterControl → {cluster_id} → Settings → Thresholds.
  • Example: swap_critical=40
swap_inout_period=<integer>
  • The interval for swap I/O alarms in seconds. 0 means disabled. Default is 600 (10 minutes).
  • Example:swap_inout_period=120
swap_inout_warning=<integer>
  • The number of pages swapped I/O for warning in the specified swap_inout_period. The default is 10240. To determine the page size for the host, use getconf PAGESIZE
  • Example: swap_inout_warning=51200
swap_inout_critical=<integer>
  • The number of pages swapped I/O for critical in the specified swap_inout_period. The default is 102400. To determine the page size for the host, use getconf PAGESIZ
  • Example: swap_inout_critical=102400
save_history_days=<integer>
  • How many days the controller shall keep data. Default is 7. 0 means disabled.
mysqlmemory_warning=<integer>
  • Warning alarm threshold for MySQL memory. Default is 80.
mysqlmemory_critical=<integer>
  • Critical alarm threshold for MySQL memory. Default is 90.
ram_warning=<integer>
  • Warning alarm threshold for RAM usage. Default is 80.
ram_critical=<integer>
  • Critical alarm threshold for RAM usage. Default is 90.
diskspace_warning=<integer>
  • Warning alarm threshold for disk usage. Default is 80.
diskspace_critical=<integer>
  • Critical alarm threshold for disk usage. Default is 90.
cpu_warning=<integer>
  • Warning alarm threshold for CPU usage. Default is 80.
cpu_critical=<integer>
  • Critical alarm threshold for CPU usage. Default is 90.
cpu_steal_warning=<integer>
  • Warning alarm threshold for CPU steal. Default is 10.
cpu_steal_critical=<integer>
  • Critical alarm threshold for CPU steal. Default is 20.
cpu_iowait_warning=<integer>
  • Warning alarm threshold for CPU IO Wait. Default is 50.
cpu_iowait_critical=<integer>
  • Critical alarm threshold for CPU IO Wait. Default is 60.
monitor_cpu_temperature=<boolean integer>
  • Whether to monitor CPU temperature. Default is 0 (false).
redobuffer_warning=<integer>
  • Warning alarm threshold for redo buffer usage. Default is 80.
redobuffer_critical=<integer>
  • Critical alarm threshold for redo buffer usage. Default is 90.
indexmemory_warning=<integer>
  • Warning alarm threshold for index memory usage. Default is 80.
indexmemory_critical=<integer>
  • Critical alarm threshold for index memory usage. Default is 90.
datamemory_warning=<integer>
  • Warning alarm threshold for data memory usage. Default is 80.
datamemory_critical=<integer>
  • Critical alarm threshold for data memory usage. Default is 90.
tablespace_warning=<integer>
  • Warning alarm threshold for table space buffer memory usage. Default is 80.
tablespace_critical=<integer>
  • Critical alarm threshold for table space buffer memory usage. Default is 90.
redolog_warning=<integer>
  • Warning alarm threshold for redo log usage. Default is 80.
redolog_critical=<integer>
  • Critical alarm threshold for redo log usage. Default is 90.
enable_is_queries=<boolean integer>
  • Specifies whether queries to the information_schema will be executed or not. Queries to the information_schema may not be suitable when having many schema objects (100s of databases, 100s of tables in each database, triggers, users, events, sprocs).
  • If disabled, the query that would be executed will be logged so it can be determined if the query is suitable in your environment. Default is 1 (enabled). Disable with 0.
max_replication_lag=<integer>
  • Max allowed replication lag in seconds before sending an Alarm. Default is 10.
enable_icmp_ping=<boolean integer>
  • Toggles if the controller shall measure the ICMP ping times to the host. Default is 1 (true).

Query Monitor

Option Description
long_query_time=<float>
  • The threshold value for slow query checking. Default 0.5.
  • Example: long_query_time=0.0003
log_queries_not_using_indexes=<boolean integer>
  • Set query monitor to detect queries not using indexes. Default is 0 (false).
query_monitor_use_local_settings=<boolean integer>
  • Don’t override the local settings of MySQL’s long_query_time and log_queries_not_using_indexes. Default is 0 (false).
db_long_query_time_alarm=<integer>
  • If a query takes longer than db_long_query_time_alarm to execute, an alarm will be raised containing detailed information about blocked and long-running transactions. Default is 0 (disabled).
  • Example: db_long_query_time_alarm=5
enable_query_monitor=<integer>
  • Setting for query monitor interval in seconds. Default is 1 means enabled. -1 means disable.
  • Another alias: query_monitor_enabled
enable_query_monitor_auto_purge_ps=<boolean integer>
  • If enabled the Performance_Schema table events_statements_summary_by_digest will be auto-purged (using TRUNCATE TABLE) every hour. By default, this is disabled (false). Enable by setting it to ‘1’ (true).
  • Another alias: query_monitor_auto_purge_ps
query_monitor_long_running_query_ms=<integer>
  • Raises an alarm if a query executes for longer than this value in milliseconds. The default is 10000. The minimum value is 1000.
query_monitor_alert_long_running_query=<boolean integer>
  • Raises an alarm if a query executes for longer than query_monitor_long_running_query_ms. Default is 0 (disabled). Enable with 1.
query_monitor_kill_long_running_query=<boolean integer>
  • Kill the query if the query executes for longer than query_monitor_long_running_query_ms. Default is 0 (Disabled). Enable with 1.
query_monitor_long_running_query_matching_info=<regex>
  • Match only queries with an ‘Info’ only matching this regex. No default value means match any Info.
  • Example: query_monitor_long_running_query_matching_info=(?i)(^SELECT.*|^UPDATE.*)
query_monitor_long_running_query_matching_info_negate=<regex>
  • The opposite matching of query_monitor_long_running_query_matching_info.
  • Example: query_monitor_long_running_query_matching_info_negate=(?i)(^ALTER TABLE.*|^RENAME TABLE.*)
query_monitor_long_running_query_matching_host=<regex>
  • Match only queries with a ‘Host’ only matching this regex. No default value means match any Host.
  • Example: query_monitor_long_running_query_matching_host=(192\.168\.10\..*|app1.domain.com)
query_monitor_long_running_query_matching_db=<regex>
  • Match only queries with a ‘Db’ only matching this regex. No default value means match any Database.
  • Example: query_monitor_long_running_query_matching_db=^joomla\_.*
query_monitor_long_running_query_matching_user=<regex>
  • Match only queries with a ‘User’ only matching this regex. No default value means match any User.
  • Example: query_monitor_long_running_query_matching_user=(dbuser1|app_user1|app_user2)
query_monitor_long_running_query_matching_user_negate=<regex>
  • The opposite matching of query_monitor_long_running_query_matching_user.
  • Example: query_monitor_long_running_query_matching_user_negate=(monitoring_user|replication_usr)
query_monitor_long_running_query_matching_command=<regex>
  • Match only queries with a ‘Command’ only matching this regex. Defaults to ‘Query’.
  • Example: query_monitor_long_running_query_matching_command=(?i)(QUERY|CONNECT)

Backup

Option Description
netcat_port=<string>
  • List of netcat/socat ports and port ranges used to stream backups. The first value before a comma is the preferred port. The next value is a port range where ClusterControl should pick on. Defaults to ‘9999,9990-9998’ which means port 9999 will be preferred if available, otherwise pick the next available port in the defined range.
  • Example: netcat_port=9999,9990-9998
backup_user=<string>
  • The database username for managing backups.
  • Example: backup_user=backupuser.
backup_user_password=<string>
  • The database password for the backup_user.
  • Example: backup_user_password=MyS3cret
backup_encryption_key=<string>
backupdir=<path>
  • The default backup directory, to be pre-filled in ClusterControl UI.
  • Example:backupdir=/storage/backup
backup_subdir=<string>
  • Set the name of the backup subdirectory. For more details on the formatting, see Backup Subdirectory Variables. Default is “BACKUP-%I”.
  • Example: backup_subdir=BACKUP-%I-%D
backup_retention=<integer>
  • How many days to keep the backups. Backups matching retention period are removed. Default is 31.
  • Example: backup_retention=15
backup_cloud_retention=<integer>
  • How many days to keep the uploaded backups to the cloud. Backups matching retention period are removed. Default is 180.
  • Example= backup_cloud_retention=90
backup_n_safety_copies=<integer>
  • How many completed full backups will be kept regardless of their retention status. Default is 1.
  • Example: backup_n_safety_copies=3
datadir_backup_path=<path>
  • During restore/rebuild operations a backup (filesystem copy) of the existing data directory (datadir) may be performed (user decides). Unless specified, the default data directory backup location is DATADIR_bak, e.g /var/lib/mysql_bak if the datadir is /var/lib/mysql
disable_backup_email=<boolean integer>
  • This setting controls if emails are sent or not if a backup finished or failed. This feature is disabled by default, meaning backup emails are sent.
  • Example: disable_backup_email=1
  • Another alias: disable_backup_emails
backup_create_hash=<boolean integer>
  • Configures CMON if it has to calculate MD5 checksum on the created backup files and verify them. Default is 1 (true).
  • Checksumming is a resource-intensive process and disabling this process might save some resources, especially on a huge backup.
  • Example: backup_create_hash=0

MySQL/MariaDB Nodes

Option Description
mysql_server_addresses=<string>
  • A comma-separated list of MySQL hostnames or IP addresses (with or without port is supported). For MySQL Cluster, this should be the list of MySQL API node IP addresses. In the case of Galera Cluster, you can add?slave or ?bvs (backup verification server) to the URL so ClusterControl will register the node accordingly.
  • Example: mysql_server_addresses=192.168.0.11:3306,192.168.0.12:3306,192.168.0.13:3306,192.168.0.14:3306?slave
monitored_mysql_port=<integer>
  • MySQL port for the managed cluster. ClusterControl assumes all DB nodes are listening on the same port. Default is 3306.
  • Example: monitored_mysql_port=3306
  • Other aliases: cmon_local_mysql_port,local_mysql_port
monitored_mysql_root_user=<string>
  • MySQL root user for the managed cluster. ClusterControl assumes all DB nodes are using the same root user. The user must have the same privileges as root (SUPER with GRANT OPTION). This is required when you want to scale your cluster by adding a new DB node or replication slave. Default is “root”.
  • Example: monitored_mysql_root_user=dbadmin
monitored_mysql_root_password=<string>
  • MySQL root password for the managed cluster. ClusterControl assumes all DB nodes are using the same root password. This is required when you want to scale your cluster by adding a new DB node or replication slave.
  • Example: monitored_mysql_root_password='[email protected]^%sw0rd
skip_name_resolve=<boolean integer>
  • Setting to disable name resolution. Default is 1 means skip_name_resolve is enabled.
mysql_version=<string>
  • The MySQL/MariaDB major version.
  • Example: mysql_version=5.7.
  • Other alias: server_version
galera_port=<integer>
  • Exclusive for Galera Cluster. The Galera communication port to be used when adding nodes/garbd, and constructing wsrep_cluster_address. Default is 4567.
galera_version=<string>
  • Exclusive for Galera Cluster. The Galera API major version number.
  • Example: galera_version=3.x
galera_vendor=<string>
  • Exclusive for Galera Cluster. The database vendor name. Supported values are “percona”, “codership” and “mariadb”.
  • Example: galera_vendor=mariadb
repl_user=<string>
  • The MySQL replication user.
  • Example: repl_user=repluser
repl_password=<string>
  • Password for repl_user
  • Example: repl_password='ZG04Z2Jnk0MUWAZK
replication_failover_whitelist=<string>
  • A comma-separated list of MySQL slaves that should be used as potential master candidates. If no server on the whitelist is available (up/connected) the failover will fail. If this variable is set, only those hosts will be considered. This parameter takes precedence over replication_failover_blacklist
  • Example: replication_failover_whitelist=192.168.1.11,192.168.1.12
replication_failover_blacklist=<string>
  • A comma-separated list of MySQL slaves will never be considered a master candidate. You can use it to list slaves that are used for backups or analytical queries. If the hardware varies between slaves, you may want to put here the slaves which use slower hardware. replication_failover_whitelist takes precedence over this parameter if it is set.
  • Example: replication_failover_blacklist=192.168.1.101,192.168.1.102
replication_skip_apply_missing_txs=<boolean integer>
  • Default is 0. Skip the check process for additional missing transactions before promoting a slave to a master and just use the most advanced slave. Such a process may result in a serious problem though – if an errant transaction is found, replication may be broken.
  • Example: replication_skip_apply_missing_txs=1
replication_stop_on_error=<boolean integer>
  • Default is 1. ClusterControl will perform the MySQL master switch only once and will be aborted immediately if the switchover fails unless the controller is restarted or you specify this variable to 0.
  • Example: replication_stop_on_error=0
replication_failover_wait_to_apply_timeout=<integer>
  • The candidate waits up to this many seconds to apply outstanding relay log events (retrieved_gtids) before failing over. Default is -1, which means ClusterControl will wait indefinitely for it to apply all missing transactions from its relay logs.
  • This is safe, but, if for some reason, the most up-to-date slave is lagging badly, failover may take hours to complete. If set to 0, failover happens immediately, no matter if the master candidate is lagging or not. Default -1 seconds (wait forever). A value higher than 0 means ClusterControl will wait for the specified seconds before failover happens.
  • Example: replication_failover_wait_to_apply_timeout=0
replication_stop_on_error=<boolean integer>
  • Failover/switchover procedures will fail if errors are encountered that may cause data loss. Enabled by default. 0 means disable, default is 1 (true).
  • Example: replication_stop_on_error=0
replication_auto_rebuild_slave=<boolean integer>
  • If the SQL THREAD is stopped and the error code is non-zero then the slave will be automatically rebuilt. 1 means enable, default is 0 (false).
  • Example: replication_auto_rebuild_slave=1
replication_onfail_failover_script=<path>
  • Path to the failover script on ClusterControl node. This script executes as soon as it has been discovered that failover is needed. If the script returns non-zero it will force the failover to abort. If the script is defined but not found, the failover will be aborted.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_onfail_failover_script=/usr/local/bin/failover_script.sh
replication_pre_failover_script=<path>
  • Path to the failover script on ClusterControl node. This script executes before the failover happens, but after a candidate has been elected and it is possible to continue the failover process. If the script returns non-zero it will force the failover to abort. If the script is defined but not found, the failover will be aborted.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: pre_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_pre_failover_script=/usr/local/bin/pre_failover_script.sh
replication_post_failover_script=<path>
  • Path to the failover script on ClusterControl node. This script executes after the failover has happened. If the script returns non-zero, a warning will be written in the job log. The script must be accessible and executable on the controller.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: post_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_post_failover_script=/usr/local/bin/post_failover_script.sh
replication_post_unsuccessful_failover_script=<path>
  • Path to the script on the ClusterControl node. This script is executed after the failover attempt failed. If the script returns non-zero a Warning will be written in the job log. The script must be accessible on the controller and executable.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: post_fail_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_post_unsuccessful_failover_script=post_fail_failover_script.sh
replication_failed_reslave_failover_script=<path>
  • Path to the script on the ClusterControl node. This script is executed after that a new master has been promoted and if the enslaving of the slaves to the new master fails. If the script returns non-zero a Warning will be written in the job log. The script must be accessible on the controller and executable.
  • Example: replication_failed_reslave_failover_script=/usr/local/bin/fail_reslave_failover_script.sh
replication_pre_switchover_script=<path>
  • Path to the switchover script on ClusterControl node. This script executes before the switchover happens. If the script returns non-zero it will force the switchover to fail. If the script is defined but not found, the switchover will be aborted. The script must be accessible on the controller and executable.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: pre_switchover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example:replication_pre_switchover_script=/usr/local/bin/pre_switchover_script.sh
replication_post_switchover_script=<path>
  • Path to the switchover script on ClusterControl node. This script executes after the switchover happened. If the script returns non-zero a Warning will be written in the job log. The script must be accessible on the controller and executable.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: post_switchover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_post_switchover_script=/usr/local/bin/post_switchover_script.sh
replication_check_external_bf_failover=<boolean integer>
  • Before attempting a failover, perform extended checks by checking the slave status to detect if the master is truly down, and also check if ProxySQL (if installed) can still see the master. If the master is detected to be functioning, then no failover will be performed. Default is 0 (false) meaning the checks are disabled. 1 means enable.
  • Example: replication_check_external_bf_failover=0
replication_check_binlog_filtration_bf_failover=<boolean integer>
  • Before attempting a failover, verify filtration (binlog_do/ignore_db) and replication_* are identically configured on the candidate and the slaves. Default is 0 (false) meaning the checks are disabled. 1 means enable.
  • Example: replication_check_binlog_filtration_bf_failover=1
replication_failover_events=<boolean integer>
  • Automatically failover events (SLAVESIDE_DISABLED) and enable the event_scheduler after a replication failover/switchover action. Default is disabled. Enabled by setting it to 1.
  • Example: replication_failover_events=1
auto_manage_readonly=<boolean integer>
  • Enable/Disable automatic management of the MySQL server read_only variable. Default is 1 (true), which means ClusterControl will set the read_only=ON if the MySQL replication role is a slave. Default is 1 (enabled).
  • Example: auto_manage_readonly=0
schema_change_detection_address=<string>
  • This option must be defined to use “Operational Report for Schema Change”. Creating a report of thousands of database objects (schemas, tables, etc) will take some time (about 5-10 minutes) depending on the hardware. It’s recommended to configure a specific host to run this job for example on a replication slave or an asynchronous slave connected to e.g a Galera or Group Replication Cluster. For NDB this option should be set to a MySQL server used for admin purposes.
  • Example: schema_change_detection_address=192.168.111.53
schema_change_detection_pause_time_ms=<integer>
  • Throttle the detection process by pausing every this value, in milliseconds. For example, if defined as 3000, ClusterControl will pause the operation for every 3 seconds.
  • Example: schema_change_detection_pause_time_ms=3000
schema_change_detection_databases=<string>
  • A comma-separated string of database names and also supports wildcards. For example ‘DB%’, will evaluate all databases starting with “DB”.
  • Example:schema_change_detection_databases=mydb%,shops_db,mymonitoring
datanode_addresses=<string>
  • Exclusive for MySQL Cluster. Comma-separated list of data node hostnames or IP addresses.
  • Example: datanode_addresses=192.168.0.41,192.168.0.42
mgmnode_addresses=<string>
  • Exclusive for MySQL Cluster. Comma-separated list of management node hostnames or IP addresses.
  • Example: mgmnode_addresses=192.168.0.51,192.168.0.5.2
ndb_connectstring=<string>
  • Exclusive for MySQL Cluster. NDB connection string for the cluster.
  • Example: ndb_connectstring=192.168.0.51:1186,192.168.0.52:1186
ndb_binary=<string>
  • Exclusive for MySQL Cluster. NDB binary for data node. Supported values are ndbd or ndbmtd.
  • Example: ndb_binary=ndbmtd
ndbd_datadir=<path>
  • Exclusive for MySQL Cluster. The datadir of the NDBD nodes.
  • Example: ndbd_datadir=/var/lib/mysqlcluster
mgmd_datadir=<path>
  • Exclusive for MySQL Cluster. The datadir of the NDB MGMD nodes.
  • Example: mgmd_datadir=/var/lib/mysql
db_configdir=<string>
  • Exclusive for MySQL Cluster. The datadir of the NDB MGMD nodes.
  • Example: db_configdir=/etc/mysql-cluster

MongoDB Nodes

Option Description
mongodb_server_addresses=<string>
  • Comma-separated list of MongoDB shard or replica IP addresses with port.
  • Example: mongodb_server_addresses=192.168.0.11:27017,192.168.0.12:27017,192.168.0.13:27017
mongoarbiter_server_addresses=<string>
  • Comma-separated list of MongoDB arbiter IP addresses with port.
  • Example: mongoarbiter_server_addresses=192.168.0.11:27019,192.168.0.12:27019,192.168.0.13:27019
mongocfg_server_addresses=<string>
  • Comma-separated list of MongoDB config server IP addresses with port.
  • Example: mongocfg_server_addresses=192.168.0.11:27019,192.168.0.12:27019,192.168.0.13:27019
mongos_server_addresses=<string>
  • Comma-separated list of MongoDB mongos IP addresses with port.
  • Example: mongos_server_addresses=192.168.0.11:27017,192.168.0.12:27017,192.168.0.13:27017
mongodb_basedir=<path>
  • Location MongoDB base directory to find the client-related binaries.
  • Example: mongodb_basedir=/usr
mongodb_user=<string>
  • MongoDB admin/root username.
  • Example: mongodb_user=root
mongodb_password=<string>
  • Password for mongodb_user
  • Example: mongodb_password='kPo123^^#*'
mongodb_authdb=<string>
  • The database containing user information to use for authentication. Default is admin.
  • Example: mongodb_authdb=admin
mongodb_cluster_key=<path>
  • The cluster’s nodes authenticating to each other using this key.
  • Example: mongodb_cluster_key=/etc/repl.key
server_selection_timeout_ms=<integer>
  • Mongo connection URI option. Defines the timeout value in milliseconds till the mongo driver should try to do a successful server selection operation. The default is 30000.
  • Example: server_selection_timeout_ms=40000
server_selection_try_once=<boolean integer>
  • Mongo connection URI option. Defines if server selection should be repeated on failure until a server selection timeout expires, or just return with failure at once. Default is 1 (true).
  • Example: server_selection_try_once=0

PostgreSQL/TimescaleDB Nodes

Option Description
postgresql_server_addresses=<string>
  • Comma separated list of PostgreSQL instances with port.
  • Example: postgresql_server_addresses=192.168.10.100:5432,192.168.10.101:5432.
  • Other alias: postgre_server_addresses
postgresql_user=<string>
  • The PostgreSQL admin user name. Default is Postgres.
  • Example: postgresql_user=postgres
  • Other alias: postgre_user
postgresql_password=<string>
  • The PostgreSQL admin password.
  • Example: postgresql_password='p4s$^#0rd123‘.
  • Other alias: postgre_password
wal_retention_hours=<boolean integer>
  • Retention hours to erase old WAL archive logs for PITR. Default is 0, which means WAL archive logs are kept forever.
  • Other alias: pitr_retention_hours
auto_manage_readonly=<boolean integer>
  • Enable/Disable automatic management of the PostgreSQL server transaction_read_only variable. Default is 1 (true), which means ClusterControl will set thetransaction_read_only=ON if the PostgreSQL replication role is slave. Default is 1 (enabled).
  • Example: auto_manage_readonly=0
replication_auto_rebuild_slave=<boolean integer>
  • If the SQL THREAD is stopped and the error code is non-zero then the slave will be automatically rebuilt. 1 means enable, default is 0 (false).
  • Example: replication_auto_rebuild_slave=1
repl_user=<string>
  • The PostgreSQL replication user.
  • Example: repl_user=repluser
repl_password=<string>
  • Password for repl_user
  • Example: repl_password='ZG04Z2Jnk0MUWAZK
replication_failover_whitelist=<string>
  • Comma-separated list of PostgreSQL slaves which should be used as potential master candidates. If no server on the whitelist is available (up/connected) the failover will fail. If this variable is set, only those hosts will be considered. This parameter takes precedence over replication_failover_blacklist.
  • Example: replication_failover_whitelist=192.168.1.11,192.168.1.12
replication_failover_blacklist=<string>
  • Comma-separated list of PostgreSQL slaves which will never be considered a master candidate. You can use it to list slaves that are used for backups or analytical queries. If the hardware varies between slaves, you may want to put here the slaves which use slower hardware. replication_failover_whitelist takes precedence over this parameter if it is set.
  • Example:  replication_failover_blacklist=192.168.1.101,192.168.1.102
replication_pre_failover_script=<path>
  • Path to the failover script on ClusterControl node. This script executes before the failover happens, but after a candidate has been elected and it is possible to continue the failover process. If the script returns non-zero it will force the failover to abort. If the script is defined but not found, the failover will be aborted.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: pre_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_pre_failover_script=/usr/local/bin/pre_failover_script.sh
replication_post_failover_script=<path>
  • Path to the failover script on ClusterControl node. This script executes after the failover has happened. If the script returns non-zero, a warning will be written in the job log. The script must be accessible and executable on the controller.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: post_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_post_failover_script=/usr/local/bin/post_failover_script.sh
replication_post_unsuccessful_failover_script=<path>
  • Path to the script on the ClusterControl node. This script is executed after the failover attempt failed. If the script returns non-zero a Warning will be written in the job log. The script must be accessible on the controller and executable.
  • 4 arguments are supplied to the script:
    • arg1=”All servers in the replication”
    • arg2=”The failed master”
    • arg3=”Selected candidate”
    • arg4=”Slaves of old master”
  • The arguments will be passed like this: post_fail_failover_script.sh "arg1" "arg2" "arg3" "arg4". The script must be accessible on the controller and executable.
  • Example: replication_post_unsuccessful_failover_script=post_fail_failover_script.sh
Was this article helpful to you? Yes No