Configuration Options for MariaDB Xpand

This page is part of MariaDB's Documentation.

The parent of this page is: Reference for MariaDB Xpand

Overview

This page describes how to configure MariaDB Xpand.

Configuration File

The default path to the MariaDB Xpand configuration file depends on the version of MariaDB Xpand:

In MariaDB Xpand 5.3, the configuration file is named clxnode.conf and is located in the /etc/clustrix/ directory by default
In MariaDB Xpand 6.0 and 6.1, the configuration file is named xpdnode.conf and is located in the /etc/xpand/ directory by default

Each Xpand node has its own configuration file. When changing a configuration option, the configuration file must be updated on each Xpand node, except in cases where the configuration change is node-specific.

Configuration Syntax

MariaDB Xpand's configuration syntax adheres to standard bash conventions. The configuration file should only contain:

Lines that set configuration options to specific values, without any extraneous spaces
Lines containing comments
Blank lines

For example:

# this is a comment
# followed by a blank line

# no extra spaces in
# OPTION=VALUE
CPU_CORES=4

Set Configuration Options During Installation

Some configuration options can be set during the installation process using the xpdnode_install.py wizard.

When configuration options are set during the installation process, they are written to the configuration file.

Change Configuration Options After Installation

Some configuration options can be changed after the installation process.

To change configuration options after the installation process:

On each Xpand node, change the configuration option's value in the configuration file.
Restart Xpand:
```
$ /opt/clustrix/bin/clx dbrestart
```

Configuration Options Set by Default

The configuration options listed below are set by default in the configuration file.

The values of many of these configuration options can be changed after installation using the proper process.

For additional information, see "Change Configuration Options After Installation".

`NODE_MEMORY`

Memory to use for Xpand, in MiB. Default is auto detected.

To modify this option:

On each Xpand node, edit the configuration file and uncomment (if commented out) the line #NODE_MEMORY and change the value to the desired amount.
Stop Xpand, restart hugetlb, and then start Xpand on all Xpand nodes simultaneously by running the following command from any Xpand node:
```
$ sudo clx -P cmd 'systemctl stop clustrix; systemctl restart hugetlb; systemctl start clustrix'
```

`MAX_REDO`

Maximum Xpand Redo Space, in MiB. Defaults to 1024.

Only modify this variable with guidance from MariaDB Support.

`CPU_CORES`

Number of CPU cores Xpand uses. Defaults to all CPU cores.

To modify:

Edit the value in the configuration file for every node.
Stop/Start all Xpand services.

The default setting of All will make use of all available cores in the system. If you would like to limit the number of cores utilized by Xpand you must modify the value for CPU_CORES to specify the number of cores that should be used. Xpand licensing will base its enforcement on the number of cores being utilized in the system as specified by CPU_CORES.

`DATA_PATH`

Database storage path for Xpand tables. Defaults to /data/clustrix.

To modify:

Stop all Xpand services.
On each node:
1. Move the directory to the desired location.
2. Modify the value of DATA_PATH in the configuration file to reflect the new location.
Start all Xpand services.

`DATA_ALLOCATE`

Storage space to pre-allocate to Xpand. Defaults to 80% of free space on $DATA_PATH volume.

To modify:

This value here is used for initialization only. To allocate more space on an node that already has Xpand installed, see ALTER CLUSTER RESIZE DEVICES

`LOG_PATH`

Logs path for the Xpand service. Defaults to /data/clustrix/log.

To modify:

Stop all Xpand services.
On each node:
1. Move the directory to the desired location.
2. Create a symbolic link in /data/clustrix/ pointing to the new log folder.
  
  Example:
```
$ sudo ln -s /log /data/clustrix/log/
```
Start all Xpand services.

`UI_LOGDIR`

Xpand WebUI Logs Path. Defaults to /data/clustrix/log/clustrix_ui.

To modify:

Stop all Xpand services.
On each node:
1. Move the directory to the desired location.
2. Create a symbolic link in /data/clustrix/log pointing to the new log folder.
```
$ sudo ln -s /log/clustrix_ui /data/clustrix/log/clustrix_ui
```
Start all nodes.

`UI_CACHEDIR`

Xpand WebUI Cache Path. Defaults to /var/cache/clustrix/django.

Only modify this variable with guidance from MariaDB Support.

`UNIX_SOCKET_PATH`

Xpand MariaDB protocol Unix socket. Defaults to /var/lib/mysql/mysql.sock.

Only modify this variable with guidance from MariaDB Support.

`LISTEN_ADDR`

Xpand service listen address (front-end IP) interface. Defaults to 0.0.0.0.

`MYSQL_PORT`

Xpand service MariaDB port. Defaults to 3306.

`BACKEND_ADDR`

Xpand service private back-end IP interface. Default is auto-detected.

To modify:

Modify the BACKEND_ADDR entry in the configuration file with the new IP.
Modify /data/clustrix/broadcast_nodes file with the new IP addresses on all nodes.

Note

Specifying port 24378 is not necessary unless you're using a non-default configuration.
Run the clx command, on any node, to ensure it has cached the IP address of each node:
```
$ sudo /opt/clustrix/bin/clx cmd 'clx cache'
```
Stop all Xpand services (per above).
Change the backend interface IP address on each node.
Modify iptables as needed.
Start all Xpand services (per above).

`BACKEND_PORT`

Xpand service network port. Defaults to 24378.

It is not recommended to modify the default value for the Xpand Network port.

`HEALTHMON_PORT`

The port used for the Xpand health monitor. Defaults to 3581.

To modify:

Edit the value in the configuration file.
Stop/Start all Xpand services.

`HTTP_PORT`

Xpand WebUI HTTP port. Defaults to 80.

To modify:

Edit the value in the configuration file.
Stop/Start all Xpand services.

`NANNY_PORT`

Xpand service nanny port. Defaults to 2424.

It is not recommended to modify the default value for the Xpand nanny port.

`CONTROL_PORT`

Xpand service control port. Defaults to 2048.

It is not recommended to modify the default value for the Xpand service control port.

`CLX_USER`

Xpand OS user. Defaults to root.

Do not modify this value after installation.

`MANAGE_USER`

Xpand service manager user. Defaults to root.

Do not modify this value after installation.

`WRITE_HOSTS`

Allows Xpand to modify sshd_config and /etc/hosts.

This used by root installations only, for inter-node communication for administrative tasks, including upgrades.

The option is commented out by default. To modify:

Remove comment on each node and set variable to any string.
Stop/Start all Xpand services.

`HUGE_TLB_ENABLE`

Xpand service enables HugeTLB memory allocation for faster startup.

Note

This causes instability on some systems (particularly certain virtual machines).

Required for non-root installations that have more than 20GiB of $NODE_MEMORY

Contact MariaDB Support before changing from default. True

To modify:

On each node, comment out to disable this option. (i.e., #HUGE_TLB_ENABLE)
Stop/Start all Xpand services.

`MONITOR_PORT`

The TCP port on which to expose Prometheus metrics. Defaults to 8123.

`INFLUXDB_URL`

If specified, metrics will be exported automatically to the specified InfluxDB URL. The specified URL must use the form SCHEME://USER:PASSWORD@HOST:PORT, where SCHEME must be http or https. If the port is unspecified, InfluxDB's default HTTP API port (8086) is used.

`INFLUXDB_DATABASE`

If specified, metrics will be exported to the specified InfluxDB database. Defaults to xpand.

`INFLUXDB_UPDATE_FREQUENCY`

How often, in seconds, to export metrics to InfluxDB when configured. Defaults to 30.

Additional Configuration Options

The configuration options listed below are not set by default in the configuration file, but they can be added at the end of the file.

The values of these configuration options can be set after installation using the normal process.

For additional information, see "Change Configuration Options After Installation".

`DISABLE_MULTIPORT`

When this option is present, the multi-port feature is disabled.

This option is not set in the configuration file by default, which means that the multi-port feature is enabled by default.

To disable the multi-port feature:
```
DISABLE_MULTIPORT=Y.
```
To enable the multi-port feature, remove or comment out DISABLE_MULTIPORT.

`MULTIPAGE_ALLOC`

Bytes reserved for multi-page allocators.

This option is not set in the configuration file by default. By default, Xpand will use 1GiB.

If you plan to set this option, you should ask MariaDB Support to provide a recommended value for your workload.

To set this configuration option, use the normal process.

For additional information, see "Change Configuration Options After Installation".

`USE_DNS_HOSTNAMES`

Enables cluster membership tracking using the hostname of each node, instead of using the IP address of each node.

This option is not set in the configuration file by default. By default, Xpand will use the IP address of each node for cluster membership tracking.

To set this configuration option, use the normal process.

For additional information, see "Change Configuration Options After Installation".