High availability server configuration settings

You can configure Mattermost as a high availability environment by going to System Console > Environment > High Availability, or by editing the config.json file as described in the following table. Changes to configuration settings in this section require a server restart before taking effect.

In a Mattermost high availability cluster deployment, the System Console is set to read-only, and settings can only be changed by editing the config.json file directly. However, to test a high availability environment, you can disable ClusterSettings.ReadOnlyConfig in the config.json file by setting it to false. This allows changes applied using the System Console to be saved back to the configuration file.

Tip

Each configuration value below includes a JSON path to access the value programmatically in the config.json file using a JSON-aware tool. For example, the SiteURL value is under ServiceSettings.

  • If using a tool such as jq, you’d enter: cat config/config.json | jq '.ServiceSettings.SiteURL'

  • When working with the config.json file manually, look for the key ServiceSettings, then within that object, find the key SiteURL.

Enable high availability mode

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

You can enable high availability mode.

  • true: The Mattermost server will attempt inter-node communication with the other servers in the cluster that have the same cluster name. This sets the System Console to read-only mode to keep the servers’ config.json files in sync.

  • false: (Default) Mattermost high availability mode is disabled.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.Enable",

  • Environment variable: MM_CLUSTERSETTINGS_ENABLE

Cluster name

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The cluster to join by name in a high availability environment.

Only nodes with the same cluster name will join together. This is to support blue-green deployments or staging pointing to the same database.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.ClusterName",

  • Environment variable: MM_CLUSTERSETTINGS_CLUSTERNAME

Override hostname

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

You can override the hostname of this server.

  • This property can be set to a specific IP address if needed; however, we don’t recommend overriding the hostname unless it’s necessary.

  • If left blank, Mattermost attempts to get the hostname from the operating system or uses the IP address.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.OverrideHostname",

  • Environment variable: MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME

See the high availability cluster documentation for details.

Use IP address

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

You can configure your high availability environment to communicate using the hostname instead of the IP address.

  • true: (Default) The cluster attempts to communicate using the IP address specified.

  • false: The cluster attempts to communicate using the hostname.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.UseIPAddress: true",

  • Environment variable: MM_CLUSTERSETTINGS_USEIPADDRESS

Use gossip

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

All cluster traffic uses the gossip protocol.

  • true: (Default) The server attempts to communicate via the gossip protocol over the gossip port specified.

  • false: The server attempts to communicate over the streaming port.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.UseExperimentalGossip: true",

  • Environment variable: MM_CLUSTERSETTINGS_USEEXPERIMENTALGOSSIP

Notes:

  • From Mattermost Server v5.36, gossip clustering can no longer be disabled.

  • The gossip port and gossip protocol are used to determine cluster health even when this setting is set to false.

Enable experimental gossip encryption

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

Gossip encryption uses AES-256 by default, and this value isn’t configurable by design.

  • true: All communication through the cluster using the gossip protocol will be encrypted.

  • false: (Default) All communication using gossip protocol remains unencrypted.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.EnableExperimentalGossipEncryption: false”,

  • Environment variable: MM_CLUSTERSETTINGS_ENABLEEXPERIMENTALGOSSIPENCRYPTION

Note: Alternatively, you can manually set the ClusterEncryptionKey row value in the Systems table. A key is a byte array converted to base64. Set this value to either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 respectively.

Enable gossip compression

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

Once all servers in a cluster are upgraded to Mattermost v5.33 or later, we recommend that you disable this configuration setting for better performance.

  • true: (Default) All communication through the cluster uses gossip compression. This setting is enabled by default to maintain compatibility with older servers.

  • false: All communication using the gossip protocol remains uncompressed.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.EnableGossipCompression: true”,

  • Environment variable: MM_CLUSTERSETTINGS_ENABLE GOSSIPCOMPRESSION

Gossip port

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The port used for the gossip protocol. Both UDP and TCP should be allowed on this port.

Numerical input. Default is 8074.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.GossipPort: 8074”,

  • Environment variable: MM_CLUSTERSETTINGS_GOSSIPPORT

Streaming port

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The port used for streaming data between servers.

Numerical input. Default is 8075.

  • System Config path: Environment > High Availability

  • config.json setting: ".ClusterSettings.StreamingPort: 8075",

  • Environment variable: MM_CLUSTERSETTINGS_STREAMINGPORT

Read only config

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

  • true: (Default) Changes made to settings in the System Console are ignored.

  • false: Changes made to settings in the System Console are written to config.json.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.ReadOnlyConfig: true,

  • Environment variable: MM_CLUSTERSETTINGS_READONLYCONFIG

Network interface

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

An IP address used to identify the device that does automatic IP detection in high availability clusters.

String input.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.NetworkInterface: "",

  • Environment variable: MM_CLUSTERSETTINGS_NETWORKINTERFACE

Bind address

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

An IP address used to bind cluster traffic to a specific network device.

This setting is used primarily for servers with multiple network devices or different Bind Address and Advertise Address like in deployments that involve NAT (Network Address Translation).

String input.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.BindAddress: "",

  • Environment variable: MM_CLUSTERSETTINGS_BINDADDRESS

Maximum idle connections

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The maximum number of idle connections held open from one server to all others in the cluster.

Numerical input. Default is 100.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.MaxIdleConns: 100,

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNS

Maximum Idle Connections per Host

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The maximum number of idle connections held open from one server to another server in the cluster.

Numerical input. Default is 128.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.MaxIdleConnsPerHost: 128",

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNSPERHOST

Idle Connection Timeout

Available in the Mattermost Enterprise subscription plan. Available for Mattermost Self-Hosted deployments.

Available in legacy Enterprise Edition E20

The amount of time, in milliseconds, to leave an idle connection open between servers in the cluster.

Numerical input. Default is 90000.

  • System Config path: N/A

  • config.json setting: ".ClusterSettings.IdleConnTimeoutMilliseconds: 90000",

  • Environment variable: MM_CLUSTERSETTINGS_IDLECONNTIMEOUTMILLISECONDS