Elasticsearch configuration settings

Elasticsearch provides enterprise-scale deployments with optimized search performance and prevents performance degradation and timeouts. Learn more about Elasticsearch in our product documentation.

Configure the Elasticsearch environment in which Mattermost is deployed by going to System Console > Environment > Elasticsearch, 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.

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 Elasticsearch indexing

Available in legacy Enterprise Edition E10/E20

New posts can be automatically indexed.

true: Indexing of new posts occurs automatically.
false: (Default) Elasticsearch indexing is disabled and new posts are not indexed.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.EnableIndexing: false",
Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING

Note:

If indexing is disabled and re-enabled after an index is created, we recommend you purge and rebuild the index to ensure complete search results.
Search queries will use database search until Elasticsearch for search queries is enabled.

Server connection address

Available in legacy Enterprise Edition E10/E20

The address of the Elasticsearch server.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.ConnectionUrl",
Environment variable: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL

Skip TLS verification

Available in legacy Enterprise Edition E10/E20

The certificate step for TLS connections can be skipped.

true: Skips the certificate verification step for TLS connections.
false: (Default) Mattermost does not skip certificate verification.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.SkipTLSVerification: false",
Environment variable: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION

Server username

Available in legacy Enterprise Edition E10/E20

(Optional) The username to authenticate to the Elasticsearch server.

String input.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.UserName",
Environment variable: MM_ELASTICSEARCHSETTINGS_USERNAME

Server password

Available in legacy Enterprise Edition E10/E20

(Optional) The password to authenticate to the Elasticsearch server.

String input.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.Password",
Environment variable: MM_ELASTICSEARCHSETTINGS_PASSWORD

Enable cluster sniffing

Available in legacy Enterprise Edition E10/E20

Automatically find and connect to all data nodes in a cluster.

true: Sniffing finds and connects to all data nodes in your cluster automatically.
false: (Default) Cluster sniffing is disabled .

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.Sniff: false",
Environment variable: MM_ELASTICSEARCHSETTINGS_SNIFF

Select the Test Connection button in the System Console to validate the connection between Mattermost and the Elasticsearch server.

Bulk indexing

Available in legacy Enterprise Edition E10/E20

Start a bulk index of all existing posts in the database.

Select the Index Now button in the System Console to start a bulk index of all posts. If the indexing process is canceled, the index and search results will be incomplete.

System Config path: Environment > Elasticsearch
config.json setting: N/A
Environment variable: N/A

Purge indexes

Available in legacy Enterprise Edition E10/E20

Purge the entire Elasticsearch index. Typically only used if the index has corrupted and search isn’t behaving as expected.

Select the Purge Indexes button in the System Console to purge the index. After purging the index, create a new index with the Index Now button.

System Config path: Environment > Elasticsearch
config.json setting: N/A
Environment variable: N/A

Enable Elasticsearch for search queries

Available in legacy Enterprise Edition E10/E20

Use the latest index for all search queries.

true: Elasticsearch will be used for all search queries using the latest index. Search results may be incomplete until a bulk index of the existing post database is finished.
false: (Default) Database search is used for search queries.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.EnableSearching:false",
Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING

Enable Elasticsearch for autocomplete queries

Available in legacy Enterprise Edition E10/E20

Elasticsearch can use the latest index for all autocompletion queries on users and channels.

true: Elasticsearch will be used for all autocompletion queries on users and channels using the latest index.
false: (Default) Database autocomplete is used.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.EnableAutocomplete: false",
Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE

Note: Autocompletion results may be incomplete until a bulk index of the existing users and channels database is finished.

Post index replicas

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each post index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.PostIndexReplicas: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS

Important: If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.

Post index shards

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each post index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.PostIndexShards: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS

Important: If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.

Channel index replicas

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each channel index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.ChannelIndexReplicas: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS

Channel index shards

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each channel index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.ChannelIndexShards: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS

User index replicas

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each user index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.UserIndexReplicas: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS

User index shards

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each user index.

Numerical input. Default is 1.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.UserIndexShards: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS

Aggregate search indexes

Available in legacy Enterprise Edition E10/E20

Elasticsearch indexes older than the age specified by this setting, in days, will be aggregated during the daily scheduled job.

Numerical input. Default is 365 days.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.AggregatePostsAfterDays: 365",
Environment variable: MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS

Note: If you’re using data retention and Elasticsearch, configure this with a value greater than your data retention policy.

Post aggregator start time

Available in legacy Enterprise Edition E10/E20

Index prefix

Available in legacy Enterprise Edition E10/E20

Prefix added to the Elasticsearch index name.	System Config path: N/A `config.json` setting: `".Elasticsearchsettings.IndexPrefix",` Environment variable: `MM_ELASTICSEARCHSETTINGS_INDEXPREFIX`
Note: When this setting is used, all Elasticsearch indexes created by Mattermost are given this prefix. You can set different prefixes so that multiple Mattermost deployments can share an Elasticsearch cluster without the index names colliding.

Live indexing batch size

Available in legacy Enterprise Edition E10/E20

Determines how many new posts are batched together before they are added to the Elasticsearch index.

Numerical input. Default is 1.

System Config path: N/a
config.json setting: ".Elasticsearchsettings.LiveIndexingBatchSize: 1",
Environment variable: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE

Note: It may be necessary to increase this value to avoid hitting the rate limit of your Elasticsearch cluster on installs handling multiple messages per second.

Bulk indexing time window

Available in legacy Enterprise Edition E10/E20

Determines the maximum time window for a batch of posts being indexed by the Bulk Indexer. This setting serves as a performance optimization for installs with over ~10 million posts in the database.

Numerical input in seconds. Default is 3600 seconds (1 hour). Approximate this value based on the average number of seconds for 2,000 posts to be added to the database on a typical day in production.

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.BulkIndexingTimeWindowSeconds: 3600",
Environment variable: MM_ELASTICSEARCHSETTINGS_BULKINDEXINGTIMEWINDOWSECONDS

Note: Setting this value too low will cause Bulk Indexing jobs to run slowly.

Request timeout

Available in legacy Enterprise Edition E10/E20

Timeout in seconds for Elasticsearch calls.

Numerical input in seconds. Default is 30 seconds.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.RequestTimeoutSeconds:30",
Environment variable: MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS

Trace

Available in legacy Enterprise Edition E10/E20

Options for printing Elasticsearch trace errors.

error: Creates the error trace when initializing the Elasticsearch client and prints any template creation or search query that returns an error as part of the error message.
all: Creates the three traces (error, trace and info) for the driver and doesn’t print the queries because they will be part of the trace log level of the driver.
not specified: (Default) No error trace is created.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.Trace",
Environment variable: MM_ELASTICSEARCHSETTINGS_TRACE