Environment Configuration Settings

import useBaseUrl from '@docusaurus/useBaseUrl'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

import Inc0_push_notification_server_configuration_settings from './push-notification-server-configuration-settings.mdx'; import Inc1_rate_limiting_configuration_settings from './rate-limiting-configuration-settings.mdx';

Review and manage the following environmental configuration options in the System Console by selecting the Product <img src={useBaseUrl('/img/ui/products_E82F.svg')} alt="Navigate between Channels, collaborative playbooks, and boards using the product menu icon." className="theme-icon" /> menu, selecting System Console, and then selecting Environment:

• Web server
• Database
• Enterprise search
• File storage
• Image proxy
• SMTP
• Push notification server
• High availability
• Rate limiting
• Logging
• Session lengths
• Performance monitoring
• Developer
• Mobile security
• config.json-only settings

System admins managing a self-hosted Mattermost deployment can edit the config.json file as described in the following tables. 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 an object such as ServiceSettings, then within that object, find the key SiteURL.

Web server

With self-hosted deployments, you can configure the network environment in which Mattermost is deployed by going to System Console > Environment > Web Server, or by updating the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Site URL

The URL that users use to access Mattermost. The port number is required if it’s not a standard port, such as 80 or 443. This field is required. Select the Test Live URL button in the System Console to validate the Site URL.

System Config path: Environment > Web Server config.json setting: ServiceSettings > SiteURL Environment variable: MM_SERVICESETTINGS_SITEURL

• The URL may contain a subpath, such as https://example.com/company/mattermost.
• If you change the Site URL value, log out of the Desktop App, and sign back in using the new domain.
• If Site URL is not set:
• Email notifications will contain broken links, and email batching will not work.
• Authentication via OAuth 2.0, including GitLab, Google, and Entra ID, will fail.
• Plugins may not work as expected.

Maximum URL length

The longest URL, in characters, including query parameters, accepted by the Mattermost server. Longer URLs are rejected, and API calls fail with an error. Numeric value. Default is 2048 characters.

System Config path: N/A config.json setting: ServiceSettings > MaximumURLLength > 2048 Environment variable: MM_SERVICESETTINGS_MAXIMUMURLLENGTH

Web server listen address

The address and port to which to bind and listen. Specifying :8065 will bind to all network interfaces. Specifying 127.0.0.1:8065 will only bind to the network interface having that IP address. If you choose a port of a lower level (called “system ports” or “well-known ports”, in the range of 0-1023), you must have permissions to bind to that port.

System Config path: Environment > Web Server config.json setting: ServiceSettings > ListenAddress Environment variable: MM_SERVICESETTINGS_LISTENADDRESS

Web server uses address:port (e.g., ":8065"), while Metrics uses a port number only (e.g., 8067).

Forward port 80 to 443

Forward insecure traffic from port 80 to port 443. true: Forwards all insecure traffic from port 80 to secure port 443. false: (Default) When using a proxy such as NGINX in front of Mattermost this setting is unnecessary and should be set to false.

System Config path: Environment > Web Server config.json setting: ServiceSettings > Forward80To443 > false Environment variable: MM_SERVICESETTINGS_FORWARD80TO443

Web server connection security

Connection security between Mattermost clients and the server. Not specified: Mattermost will connect over an unsecure connection. TLS: Encrypts the communication between Mattermost clients and your server.

System Config path: Environment > Web Server config.json setting: ServiceSettings > ConnectionSecurity Environment variable: MM_SERVICESETTINGS_CONNECTIONSECURITY

See the setting up TLS for Mattermost for details.

TLS certificate file

The path to the certificate file to use for TLS connection security. String input.

System Config path: Environment > Web Server config.json setting: ServiceSettings > TLSCertFile Environment variable: MM_SERVICESETTINGS_TLSCERTFILE

TLS key file

The path to the TLS key file to use for TLS connection security. String input.

System Config path: Environment > Web Server config.json setting: ServiceSettings > TLSKeyFile Environment variable: MM_SERVICESETTINGS_TLSKEYFILE

Use Let's Encrypt

Enable the automatic retrieval of certificates from Let’s Encrypt. true: The certificate will be retrieved when a client attempts to connect from a new domain. This will work with multiple domains. false: (Default) Manual certificate specification based on the TLS Certificate File and TLS Key File specified above.

System Config path: Environment > Web Server config.json setting: ServiceSettings > UseLetsEncrypt > false Environment variable: MM_SERVICESETTINGS_USELETSENCRYPT

See the setting up TLS for Mattermost for details on setting up Let's Encrypt.

Let's Encrypt certificate cache file

The path to the file where certificates and other data about the Let’s Encrypt service will be stored. File path input.

System Config path: Environment > Web Server config.json setting: ServiceSettings > LetsEncryptCertificateCacheFile Environment variable: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE

Read timeout

Maximum time allowed from when the connection is accepted to when the request body is fully read. Numerical input in seconds. Default is 300 seconds.

System Config path: Environment > Web Server config.json setting: ServiceSettings > ReadTimeout > 300 Environment variable: MM_SERVICESETTINGS_READTIMEOUT

Write timeout

If using HTTP (insecure), this is the maximum time allowed from the end of reading the request headers until the response is written. If using HTTPS, it's the total time from when the connection is accepted until the response is written. Numerical input in seconds. Default is 300 seconds.

System Config path: Environment > Web Server config.json setting: ServiceSettings > WriteTimeout > 300 Environment variable: MM_SERVICESETTINGS_WRITETIMEOUT

Idle timeout

Set an explicit idle timeout in the HTTP server. This is the maximum time allowed before an idle connection is disconnected. Numerical input in seconds. Must be greater than 0. Default is 300 seconds.

System Config path: Environment > Web Server config.json setting: ServiceSettings > IdleTimeout > 300 Environment variable: MM_SERVICESETTINGS_IDLETIMEOUT

Webserver mode

We recommend gzip to improve performance unless your environment has specific restrictions, such as a web proxy that distributes gzip files poorly. gzip (gzip): (Default) The Mattermost server will serve static files compressed with gzip to improve performance. gzip compression applies to the HTML, CSS, Javascript, and other static content files that make up the Mattermost web client. Uncompressed (uncompressed): The Mattermost server will serve static files uncompressed. Disabled (disabled): The Mattermost server will not serve static files.

System Config path: Environment > Web Server config.json setting: ServiceSettings > WebserverMode > "gzip" Environment variable: MM_SERVICESETTINGS_WEBSERVERMODE

Enable channel viewed WebSocket messages

Determine whether channel_viewed WebSocket events are sent. These events synchronize unread notifications across a user's clients and devices. true: (Default) channel_viewed WebSocket events are sent. false: channel_viewed WebSocket events aren't sent.

System Config path: Environment > Web Server config.json setting: ServiceSettings > EnableChannelViewedMessages > true Environment variable: MM_SERVICESETTINGS_ENABLECHANNELVIEWEDMESSAGES

Disabling this configuration setting in larger deployments may improve server performance in the following areas:

• Reduced database load: When channel_viewed events are disabled, the server no longer needs to log these events in the database. This reduces the number of write and update operations, which can be substantial in a busy server with many users frequently switching channels.
• Decreased network traffic: Disabling these events means there are fewer messages sent between the server and clients. This reduction in network traffic can lower latency and improve the overall responsiveness of the server, especially for users with slower connections.
• Lower server CPU usage: Processing channel_viewed events requires CPU resources to handle database transactions and network communication. Without these events, the server's CPU can be utilized more efficiently for other tasks, improving the overall performance.
• Improved user experience: With reduced server load and network traffic, users may experience faster loading times and a more fluid interaction with the application.

However, disabling this configuration setting affects some functionality, such as accurate tracking of read and unread messages in channels. It's important to balance performance improvements with the needs of your organization and users.

Enable insecure outgoing connections

Configure Mattermost to allow insecure outgoing connections. true: Outgoing HTTPS requests, including S3 clients, can accept unverified, self-signed certificates. For example, outgoing webhooks to a server with a self-signed TLS certificate, using any domain, will be allowed, and will skip TLS verification. false: (Default) Only secure HTTPS requests are allowed.

System Config path: Environment > Web Server config.json setting: ServiceSettings > EnableInsecureOutgoingConnections > false Environment variable: MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS

Enabling this feature makes these connections susceptible to man-in-the-middle attacks.

Enable hardened mode

Configure Mattermost to run in a hardened mode that makes user experience trade-offs in the interest of security. true: Hardened mode is enabled. false: (Default) Hardened mode is disabled.

System Config path: Environment > Web Server config.json setting: ServiceSettings > EnableHardenedMode > false Environment variable: MM_SERVICESETTINGS_ENABLEHARDENEDMODE

This setting was called ServiceSettings.ExperimentalEnableHardenedMode until Mattermost v11.11. On first start after upgrading, the server automatically migrates the old key to ServiceSettings.EnableHardenedMode and removes it from config.json.

Changes made when hardened mode is enabled:

• Failed login returns a generic error message instead of a specific message for username and password.
• If multi-factor authentication (MFA) is enabled, the route to check if a user has MFA enabled always returns true. This causes the MFA input screen to appear even if the user does not have MFA enabled. The user may enter any value to pass the screen. Note that hardened mode does not affect user experience when MFA is enforced.
• Password reset does not inform the user that they can not reset their SSO account through Mattermost and instead claims to have sent the password reset email.
• Mattermost sanitizes all 500 errors before returned to the client. Use the supplied request_id to match user-facing errors with the server logs.

Post identity and display-override props (from_webhook, from_bot, override_username, override_icon_url, and related keys) are always stripped from caller-supplied create/update payloads for non-integration authors and re-applied only under verified integration authority. On update, stripping removes values the caller sent; existing identity props already stored on the post are preserved so a normal edit cannot wipe or replace a bot or webhook identity. That behavior is independent of hardened mode.

Managed resource paths

A comma-separated list of paths within the Mattermost domain that are managed by a third party service instead of Mattermost itself. Links to these paths will be opened in a new tab/window by Mattermost apps. For example, if Mattermost is running on https://mymattermost.com, setting this to conference will cause links such as https://mymattermost.com/conference to open in a new window.

System Config path: Environment > Web Server config.json setting: ServiceSettings > ManagedResourcePaths Environment variable: MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS

When using the Mattermost Desktop App, additional configuration is required to open the link within the Desktop App instead of in a browser. See the desktop managed resources documentation for details.

Reload configuration from disk

You must change the database line in the config.json file, and then reload configuration to fail over without taking the server down. Select the Reload configuration from disk button in the System Console after changing your database configuration. Then, go to Environment > Database and select Recycle Database Connections to complete the reload.

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

Purge all caches

Purge all in-memory caches for sessions, accounts, and channels. Select the Purge All Caches button in the System Console to purge all caches.

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

Purging the caches may adversely impact performance. high availability cluster-based deployments will attempt to purge all the servers in the cluster.

Websocket URL

You can configure the server to instruct clients on where they should try to connect websockets to. String input.

System Config path: N/A config.json setting: ServiceSettings > WebsocketURL > "" Environment variable: MM_SERVICESETTINGS_WEBSOCKETURL

We strongly recommend configuring a single websocket URL that matches the Site URL configuration setting.

License file location

The path and filename of the license file on disk. On startup, if Mattermost can't find a valid license in the database from a previous upload, it looks in this path for the license file. String input. Can be an absolute path or a path relative to the mattermost directory.

System Config path: N/A config.json setting: ServiceSettings > LicenseFileLocation > "" Environment variable: MM_SERVICESETTINGS_LICENSEFILELOCATION

TLS minimum version

The minimum TLS version used by the Mattermost server. Accepted values are 1.0, 1.1, 1.2, and 1.3. The default is 1.2.

System Config path: N/A config.json setting: ServiceSettings > TLSMinVer > 1.2 Environment variable: MM_SERVICESETTINGS_TLSMINVER

This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy layer, such as NGINX.

Trusted proxy IP header

Specified headers that will be checked, one by one, for IP addresses (order is important). All other headers are ignored. String array input consisting of header names, such as ["X-Forwarded-For", "X-Real-Ip"].

System Config path: N/A config.json setting: ServiceSettings > TrustedProxyIPHeader > [] Environment variable: MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER

• The default value of [] means that no header will be trusted.
• We recommend keeping the default setting when Mattermost is running without a proxy to avoid the client sending the headers and bypassing rate limiting and/or the audit log.
• For environments that use a reverse proxy, this issue does not exist, provided that the headers are set by the reverse proxy. In those environments, only explicitly whitelist the header set by the reverse proxy and no additional values.

Enable Strict Transport Security (HSTS)

true: Adds the Strict Transport Security (HSTS) header to all responses, forcing the browser to request all resources via HTTPS. false: (Default) No restrictions on TLS transport. Strict Transport Security (HSTS) header isn't added to responses.

System Config path: N/A config.json setting: ServiceSettings > TLSStrictTransport > false Environment variable: MM_SERVICESETTINGS_TLSSTRICTTRANSPORT

See the Strict-Transport-Security documentation for details.

Secure TLS transport expiry

The time, in seconds, that the browser remembers a site is only to be accessed using HTTPS. After this period, a site can't be accessed using HTTP unless TLSStrictTransport is set to true. Numerical input. Must be 0 or greater. Default is 63072000 (2 years).

System Config path: N/A config.json setting: ServiceSettings > TLSStrictTransportMaxAge > 63072000 Environment variable: MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE

See the Strict-Transport-Security documentation for details.

TLS cipher overwrites

Set TLS ciphers overwrites to meet requirements from legacy clients which don't support modern ciphers, or to limit the types of accepted ciphers. If none specified, the Mattermost server assumes a set of currently considered secure ciphers, and allows overwrites in the edge case. String array input.

System Config path: N/A config.json setting: ServiceSettings > TLSOverwriteCiphers > [] Environment variable: MM_SERVICESETTINGS_TLSOVERWRITECIPHERS

• This setting only takes effect if you are using the built-in server binary directly and not using a reverse proxy layer, such as NGINX.
• See the ServerTLSSupportedCiphers variable in /model/config.go for a list of ciphers considered secure.

Goroutine health threshold

Set a threshold on the number of goroutines when the Mattermost system is considered to be in a healthy state. When goroutines exceed this limit, a warning is returned in the server logs. Numeric input. Default is -1 which turns off checking for the threshold.

System Config path: N/A config.json setting: ServiceSettings > GoroutineHealthThreshold > -1 Environment variable: MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD

Allow cookies for subdomains

true: (Default) Allows cookies for subdomains by setting the domain parameter on Mattermost cookies. false: Cookies aren't allowed for subdomains.

System Config path: N/A config.json setting: ServiceSettings > AllowCookiesForSubdomains > true Environment variable: MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS

Cluster log timeout

Define the frequency, in milliseconds, of cluster request time logging for performance monitoring. Numerical input. Must be greater than 0. Default is 2000 milliseconds (2 seconds).

System Config path: N/A config.json setting: ServiceSettings > ClusterLogTimeoutMilliseconds > 2000 Environment variable: MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS

See the performance monitoring documentation for details.

Maximum payload size

The maximum payload size in bytes for all APIs except APIs that receive a file as an input. For example, the upload attachment API or the API to upload a custom emoji. Numerical value. Default is 300000 (300 kB).

System Config path: N/A config.json setting: ServiceSettings > MaximumPayloadSizeBytes > 300000 Environment variable: MM_SERVICESETTINGS_MAXIMUMPAYLOADSIZEBYTES

---

Database

With self-hosted deployments, you can configure the database environment in which Mattermost is deployed by going to System Console > Environment > Database, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Driver name

The type of database. Can be either: mysql: (Default) Enables driver to MySQL database. postgres: Enables driver to PostgreSQL database.

System Config path: N/A config.json setting: SqlSettings > DriverName Environment variable: MM_SQLSETTINGS_DRIVERNAME

Data source

The connection string to the master database. String input.

System Config path: N/A config.json setting: SqlSettings > DataSource Environment variable: MM_SQLSETTINGS_DATASOURCE

PostgreSQL databases

When Driver Name is set to postgres, use a connection string in the form of: postgres://mmuser:password@hostname_or_IP:5432/mattermost_test?sslmode=disable&connect_timeout=10

To use TLS with PostgreSQL databases

The parameter to encrypt connection against a PostgreSQL server is sslmode. The library used to interact with PostgreSQL server is pq. Currently, it's not possible to use all the values that you could pass to a standard PostgreSQL Client psql "sslmode=value" See the SSL Mode Descriptions documentation for details.

Your database admin must configure the functionality according to the supported values described below.

Short description of the sslmode parameter	Value	Example of a data source name
Don't use TLS / SSL encryption against the PostgreSQL server. Default value in file config.json	disable	postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=disable&connect_timeout=10
The data is encrypted and the network is trusted. Default value is sslmode when omitted.	require	postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=require&connect_timeout=10
The data is encrypted when connecting to a trusted server.	verify-ca	postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=verify-ca&connect_timeout=10
The data is encrypted when connecting to a trusted server.	verify-full	postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=verify-full&connect_timeout=10

MySQL Databases

When Driver Name is set to mysql, we recommend using collation over using charset.

To specify collation:

"SqlSettings": {
    "DataSource": "<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8&collation=utf8mb4_general_ci",
    [...]
}

If collation is omitted, the default collation, utf8mb4_general_ci is used:

"SqlSettings": {
  "DataSource": "<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8",
  [...]
}

If you’re using MySQL 8.0 or later, the default collation has changed to utf8mb4_0900_ai_ci. See our Database Software Requirements documentation for details on MySQL 8.0 support.

To use TLS with MySQL Databases

The parameter to encrypt connection against a MySQL server is tls.

The library used to interact with MySQL is Go-MySQL-Driver.

For the moment, it's not possible to use all the values that you could pass to a standard MySQL Client mysql --ssl-mode=value. See Connection-Encryption Option Summary documentation for a version 8.0 example.

Your database admin must configure the functionality according to supported values described below.

Short description of the tls parameter	Value	Example of a data source name
Don't use TLS / SSL encryption against MySQL server.	false	"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=false"
Use TLS / SSL encryption against MySQL server.	true	"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=true"
Use TLS / SSL encryption with a self-signed certificate against MySQL server.	skip-verify	"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify"
Use TLS / SSL encryption if server advertises a possible fallback; unencrypted if it's not advertised.	preferred	"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=preferred"

AWS High Availablity RDS cluster deployments

For an AWS High Availability RDS cluster deployment, point this configuration setting to the write/read endpoint at the cluster level to benefit from the AWS failover handling. AWS takes care of promoting different database nodes to be the writer node. Mattermost doesn't need to manage this. See the high availability database configuration documentation for details.

Maximum open connections

The maximum number of open connections to the database. Numerical input. Default is 100.

System Config path: Environment > Database config.json setting: SqlSettings > MaxOpenConns > 100 Environment variable: MM_SQLSETTINGS_MAXOPENCONNS

This limit applies per data source, per Mattermost server node - not as a cluster-wide total. Each server node opens its own connection pool, sized to this value, for the master database (DataSource) and separately for each entry configured under read replicas and search replicas.

To size max_connections on the database (or any connection-pooling proxy in front of it), first count the data sources per node - the master database counts as 1, then add the number of read replicas and the number of search replicas. Multiply that count by MaxOpenConns, then multiply again by the number of app server nodes (when deployed as a high availability cluster):

MaxOpenConns x (data sources per node) x (number of app nodes)

For example, in a 3-node HA cluster where each node is configured with 1 read replica and 1 search replica, at the default MaxOpenConns of 100, each node has 3 data sources, so that's 3 x 3 x 100 = 900 possible connections across the cluster.

Maximum idle connections

The maximum number of idle connections held open to the database. Numerical input. Default is 50. A 2:1 ratio with MaxOpenConns is recommended.

System Config path: Environment > Database config.json setting: SqlSettings > MaxIdleConns > 50 Environment variable: MM_SQLSETTINGS_MAXIDLECONNS

Query timeout

The amount of time to wait, in seconds, for a response from the database after opening a connection and sending the query. Numerical input in seconds. Default is 30 seconds.

System Config path: Environment > Database config.json setting: SqlSettings > QueryTimeout > 30 Environment variable: MM_SQLSETTINGS_QUERYTIMEOUT

Maximum connection lifetime

Maximum lifetime for a connection to the database, in milliseconds. Use this setting to configure the maximum amount of time a connection to the database may be reused Numerical input in milliseconds. Default is 3600000 milliseconds (1 hour).

System Config path: Environment > Database config.json setting: SqlSettings > ConnMaxLifetimeMilliseconds > 3600000 Environment variable: MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS

Maximum connection idle timeout

Maximum time a database connection can remain idle, in milliseconds. Numerical input in milliseconds. Default is 300000 (5 minutes).

System Config path: Environment > Database config.json setting: SqlSettings > ConnMaxIdleTimeMilliseconds > 300000 Environment variable: MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS

Minimum hashtag length

Minimum number of characters in a hashtag. This value must be greater than or equal to 2.

System Config path: Environment > Database config.json setting: SqlSettings > MinimumHashtagLength > 3 Environment variable: MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH

MySQL databases must be configured to support searching strings shorter than three characters. See the MySQL documentation for details.

SQL statement logging

Executed SQL statements can be written to the log for development. true: Executing SQL statements are written to the log. false: (Default) SQL statements aren't written to the log.

System Config path: Environment > Database config.json setting: SqlSettings > Trace > false Environment variable: MM_SQLSETTINGS_TRACE

Recycle database connections

Select the Recycle Database Connections button to manually recycle the connection pool by closing the current set of open connections to the database within 20 seconds, and then creating a new set of connections. To fail over without stopping the server, change the database line in the config.json file, select Reload Configuration from Disk via Environment > Web Server, then select Recycle Database Connections.

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

Disable database search

When enterprise-scale search, | - System Config path: Environment > Database database search can be disabled from performing searches. | - config.json setting: SqlSettings > DisableDatabaseSearch > false | | - Environment variable: MM_SQLSETTINGS_DISABLEDATABASESEARCH | - true: Disables the use of the database to perform | | searches. If another search engine isn't configured, | | setting this value to true will result in empty search | | results. | | - false: (Default) Database search isn't disabled. | |

Search behavior in Mattermost depends on which search engines are enabled:

• When Elasticsearch or AWS OpenSearch is enabled, Mattermost will try to use it first.
• If Elasticsearch fails or is disabled, Mattermost will attempt to use Bleve search, if enabled. Bleve search has been deprecated in Mattermost v11.0. We recommend using Elasticsearch or OpenSearch for enterprise search capabilities.
• If these fail or are disabled, Mattermost tries to search the database directly, if this is enabled.
• If all of the above methods fail or are disabled, the search results will be empty.

Disabling this configuration setting in larger deployments may improve server performance in the following areas:

• Reduced Database Load: When database search is enabled, every search query executed by users needs to interact with the database, leading to additional load on the database server. By disabling database search, you can avoid these queries, thereby reducing the database load.
• Improved Response Time: Database searches can be time-consuming, especially with large datasets. Disabling database search can result in faster response times because the system no longer spends time fetching and processing search results from the database.
• Offloading Search to Indexing Services: Disabling database search often means that searches are offloaded to specialized indexing services like Elasticsearch, which are optimized for search operations. These services can provide faster and more efficient search capabilities compared to traditional database searches.
• Lower Resource Consumption: Running search queries directly against the database can be resource-intensive (using CPU and memory). With database search disabled, these resources can be allocated to other critical functions, improving overall system performance.
• Enhanced Scalability: As the number of users and data volume grow, database search can become less efficient. Specialized search services are designed to scale more effectively, enhancing overall system scalability and performance.

However, the ability to perform database searches in Mattermost is a critical feature for many users, particularly when other search engines aren't enabled. Disabling this feature will result in users seeing an error if they attempt to use the Mattermost Search box. It’s important to balance performance improvements with the needs of your organization and users.

Applied schema migrations

A list of all migrations that have been applied to the data store based on the version information available in the db_migrations table. Select About Mattermost from the Product <img src={useBaseUrl('/img/ui/products_E82F.svg')} alt="Navigate between Channels, collaborative playbooks, and boards using the product menu icon." className="theme-icon" /> menu to review the current database schema version applied to your deployment.

Active search backend

Read-only display of the currently active backend used for search. Values can include none, database, elasticsearch, or bleve.

Read replicas

Specifies the connection strings for the read replica databases.

System Config path: N/A config.json setting: SqlSettings > DataSourceReplicas > [] Environment variable: MM_SQLSETTINGS_DATASOURCEREPLICAS

• Each database connection string in the array must be in the same form used for the Data source setting.
• Space separate multiple read replicas in the array to allow Mattermost to load balance read queries across multiple database instances. For example, MM_SQLSETTINGS_DATASOURCEREPLICAS=dc-1 dc-2
• Each entry added here opens its own connection pool, sized to MaxOpenConns, on every Mattermost server node - it does not share a pool with the other entries. See that setting's note for the full cluster-wide sizing calculation before adding replicas.

AWS High Availability RDS cluster deployments

For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the write traffic). Mattermost has its own method of balancing the read-only connections and can also balance those queries to the data source/write+read connection should those nodes fail. See the high availability database configuration documentation for details.

Search replicas

Specifies the connection strings for the search replica databases. A search replica is similar to a read replica, but is used only for handling search queries.

System Config path: N/A config.json setting: SqlSettings > DataSourceSearchReplicas > [] Environment variable: MM_SQLSETTINGS_DATASOURCESEARCHREPLICAS

• Each database connection string in the array must be in the same form used for the Data source setting.
• Each entry added here opens its own connection pool, sized to MaxOpenConns, on every Mattermost server node - it does not share a pool with the other entries. See that setting's note for the full cluster-wide sizing calculation before adding search replicas.

AWS High Availability RDS cluster deployments

For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the write traffic). Mattermost has its own method of balancing the read-only connections and can also balance those queries to the data source/write+read connection should those nodes fail. See the high availability database configuration documentation for details.

Replica lag settings

String array input specifies a connection string and user-defined SQL queries on the database to measure replica lag for a single replica instance. These settings monitor absolute lag based on binlog distance/transaction queue length, and the time taken for the replica to catch up. String array input consists of: DataSource: The database credentials to connect to the database instance. QueryAbsoluteLag: A plain SQL query that must return a single row. The first column must be the node value of the Prometheus metric, and the second column must be the value of the lag used to measure absolute lag. QueryTimeLag: A plain SQL query that must return a single row. The first column must be the node value of the Prometheus metric, and the second column must be the value of the lag used to measure the time lag.

System Config path: N/A config.json setting: SqlSettings > ReplicaLagSettings > [] Environment variable: MM_SQLSETTINGS_REPLICALAGSETTINGS

• The QueryAbsoluteLag and QueryTimeLag queries must return a single row.
• To properly monitor this, you must set up performance monitoring for Mattermost.

1. Configure the replica lag metric based on your database type. See the following tabs for details on configuring this for each database type.

Add the configuration highlighted below to your SqlSettings.ReplicaLagSettings array. You only need to add this once because replication statistics for AWS Aurora nodes are visible across all server instances that are members of the cluster. Be sure to change the DataSource to point to a single node in the group.

For more information on Aurora replication stats, see the AWS Aurora documentaion.

Example

{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "replica-1",
            "QueryAbsoluteLag": "select server_id, highest_lsn_rcvd-durable_lsn as bindiff from aurora_global_db_instance_status() where server_id=<>",
            "QueryTimeLag": "select server_id, visibility_lag_in_msec from aurora_global_db_instance_status() where server_id=<>"
        &#125;
      ]
  &#125;
&#125;

Add the configuration highlighted below to your SqlSettings.ReplicaLagSettings array. You only need to add this once because replication statistics for all nodes are shared across all server instances that are members of the MySQL replication group. Be sure to change the DataSource to point to a single node in the group.

For more information on group replication stats, see the MySQL documentation.

Example

{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "replica-1",
            "QueryAbsoluteLag": "select member_id, count_transactions_remote_in_applier_queue FROM performance_schema.replication_group_member_stats where member_id=<>",
            "QueryTimeLag": ""
        &#125;
      ]
  &#125;
&#125;

1. Add the configuration highlighted below to your SqlSettings.ReplicaLagSettings array. This query should run against the primary node in your cluster, to do this change the DataSource to match the SqlSettings.DataSource setting you have configured.

For more information on pg_stat_replication, see the PostgreSQL documentation.

Example:

{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10.",
            "QueryAbsoluteLag": "select usename, pg_wal_lsn_diff(pg_current_wal_lsn(),replay_lsn) as metric from pg_stat_replication;",
            "QueryTimeLag": ""
        }
      ]
  }
}

1. Grant permissions to the database user for pg_monitor. This user should be the same user configured above in the DataSource string.

For more information on roles, see the PostgreSQL documentation.

sudo -u postgres psql
postgres=# GRANT pg_monitor TO mmuser;

1. Save the config and restart all Mattermost nodes.
2. Navigate to your Grafana instance monitoring Mattermost and open the Mattermost Performance Monitoring v2 dashboard.
3. The QueryTimeLag chart is already setup for you utilizing the existing Replica Lag chart. If using QueryAbsoluteLag metric clone the Replica Lag chart and edit the query to use the below absolute lag metrics and modify the title to be Replica Lag Absolute.

mattermost_db_replica_lag_abs{instance=~"$server"}

Replica monitor interval (seconds)

Specifies how frequently unhealthy replicas will be monitored for liveness check. Mattermost will dynamically choose a replica if it's alive. Numerical input. Must be greater than 0. Default is 5 seconds.

System Config path: N/A config.json setting: SqlSettings > ReplicaMonitorIntervalSeconds > 5 Environment variable: MM_SQLSETTINGS_REPLICAMONITORINTERVALSECONDS

This configuration setting is applicable to self-hosted deployments only.

---

Enterprise search

Core database search happens in a relational database and is intended for deployments under about 2–3 million posts and file entries. Beyond that scale, enabling enterprise search with Elasticsearch or AWS OpenSearch is highly recommended for optimum search performance before reaching 3 million posts.

For self-hosted deployments with over 3 million posts, Elasticsearch or AWS OpenSearch is required to avoid significant performance issues, such as timeouts, with message searches and @mentions.

You can configure Mattermost enterprise search by going to System Console > Environment > Elasticsearch. The following configuration settings apply to both Elasticsearch and AWS OpenSearch. You can also edit the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Enable Elasticsearch indexing

Configure Mattermost to index new posts automatically. true: Indexing of new messages occurs automatically. false: (Default) Indexing of new messages is disabled, and new messages aren't indexed.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > EnableIndexing > false Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING

If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results.

Backend type

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

The type of search backend. elasticsearch - (Default) opensearch - Required for AWS OpenSearch.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > Backend > "elasticsearch" Environment variable: MM_ELASTICSEARCHSETTINGS_BACKEND

Learn more about enterprise search version support.

Server connection address

The address of the Elasticsearch or AWS OpenSearch server.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > ConnectionUrl Environment variable: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL

CA path

Optional path to the Custom Certificate Authority certificates for the Elasticsearch or AWS OpenSearch server.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > CA Environment variable: MM_ELASTICSEARCHSETTINGS_CA

• Available from Mattermost v7.8. The certificate path should be /opt/mattermost/data/elasticsearch/ or /opt/mattermost/data/opensearch and configured in the System Console as ./elasticsearch/cert.pem or ./opensearch/cert.pem.
• Can be used in conjunction with basic authentication credentials or can replace them. Leave this setting blank to use the default Certificate Authority certificates for the operating system.

Client certificate path

Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Optional client certificate for the connection to the Elasticsearch or AWS OpenSearch server in the PEM format.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > ClientCert Environment variable: MM_ELASTICSEARCHSETTINGS_CLIENTCERT

Client certificate key path

Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Optional key for the client certificate in the PEM format.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > ClientKey Environment variable: MM_ELASTICSEARCHSETTINGS_CLIENTKEY

Skip TLS verification

The certificate step for TLS connections can be skipped. true: Skips the certificate verification step for TLS connections. false: (Default) Mattermost requires certificate verification.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > SkipTLSVerification > false Environment variable: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION

Server username

(Optional) The username to authenticate to the Elasticsearch or AWS OpenSearch server. String input.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > UserName Environment variable: MM_ELASTICSEARCHSETTINGS_USERNAME

Server password

(Optional) The password to authenticate to the Elasticsearch or AWS OpenSearch server. String input.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > Password Environment variable: MM_ELASTICSEARCHSETTINGS_PASSWORD

Enable cluster sniffing

Configure Mattermost to 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. Do not enable cluster sniffing when using cloud-hosted search providers such as Amazon OpenSearch Service.

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 or AWS OpenSearch server.

Bulk indexing

Configure Mattermost to start a bulk index of all existing posts in the database, from oldest to newest.

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

• Always purge indexes before bulk indexing.
• Select the Index Now button in the System Console to start a bulk index of all posts, and review all index jobs in progress.
• Elasticsearch or AWS OpenSearch is available during indexing, but search results may be incomplete until the indexing job is complete.
• If an in-progress indexing job is canceled, the index and search results will be incomplete.

Rebuild channels index

Purge the channels index adn re-index all channels in the database, from oldest to newest.

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

Select the Rebuild Channels Index button in the System Console to purge the channels index. Ensure no other indexing jobs are in progress via the Bulk Indexing table before starting this process. During indexing, channel auto-complete is available, but search results may be incomplete until the indexing job is complete.

Purge indexes

Purge the entire Elasticsearch index.

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

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

Indexes to skip while purging

Specify index names to ignore while purging indexes. Separate multiple index names with commas. Use an asterisk (*) to match a sequence of index name characters.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > IgnoredPurgeIndexes Environment variable: MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES

Enable Elasticsearch for search queries

Configure Mattermost to use Elasticsearch or AWS OpenSearch for all search queries using the latest index. true: Elasticsearch or AWS OpenSearch is used for all search queries using the latest index. Search results may be incomplete until a bulk index of the existing message database is completed. 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

If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results.

Enable Elasticsearch for autocomplete queries

Configure Mattermost to use Elasticsearch or AWS OpenSearch for all autocompletion queries on users and channels using the latest index. true: Elasticsearch or AWS OpenSearch 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

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

Allow searching public channels without membership

Allow users to search for messages in public channels they have not joined. When enabled for the first time, existing posts are updated in the background with channel type information. This backfill process is throttled to ~10,000 posts per second to avoid impacting search performance. true: Users can find messages in public channels they haven't joined, scoped to teams they belong to. false: (Default) Users can only search messages in channels they are a member of.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > EnableSearchPublicChannelsWithoutMembership > false Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHPUBLICCHANNELSWITHOUTMEMBERSHIP

This setting has no effect when Compliance Mode is enabled. When Compliance Mode is active, search results are always restricted to channels the user is a member of.

Enable file indexing

Configure whether Mattermost indexes file attachments in Elasticsearch or AWS OpenSearch. true: (Default) New and updated file attachments are indexed, and bulk indexing jobs include files. false: New or updated file attachments aren't indexed, and bulk indexing jobs skip files. File search continues to return previously indexed files, and files deleted from Mattermost are still removed from the index.

System Config path: Environment > Elasticsearch config.json setting: ElasticsearchSettings > EnableFileIndexing > true Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEFILEINDEXING

Files uploaded while this setting is false don't appear in file search results. After setting it back to true, run a bulk index from System Console > Environment > Elasticsearch to make those files searchable.

Post index replicas

The number of replicas to use for each post index. Numerical input. Must be 0 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > PostIndexReplicas > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS

• 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.
• If there are n data nodes, the number of replicas per shard for each index should be n-1.
• If the number of nodes in an Elasticsearch or AWS OpenSearch cluster changes, this configuration setting, as well as Channel Index Replicas and User Index Replicas must also be updated accordingly.

Post index shards

The number of shards to use for each post index. Numerical input. Must be 1 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > PostIndexShards > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS

If this configuration 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

The number of replicas to use for each channel index. Numerical input. Must be 0 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > ChannelIndexReplicas > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS

If there are n data nodes, the number of replicas per shard for each index should be n-1. If the number of nodes in an Elasticsearch or AWS OpenSearch cluster changes, this configuration setting, as well as Post Index Replicas and User Index Replicas must also be updated accordingly.

Channel index shards

The number of shards to use for each channel index. Numerical input. Must be 1 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > ChannelIndexShards > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS

User index replicas

The number of replicas to use for each user index. Numerical input. Must be 0 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > UserIndexReplicas > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS

If there are n data nodes, the number of replicas per shard for each index should be n-1. If the number of nodes in an Elasticsearch or AWS OpenSearch cluster changes, this configuration setting, as well as Post Index Replicas and User Index Replicas must also be updated accordingly.

User index shards

The number of shards to use for each user index. Numerical input. Must be 1 or greater. Default is 1.

System Config path: N/A config.json setting: ElasticsearchSettings > UserIndexShards > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS

Aggregate search indexes

Elasticsearch or AWS OpenSearch 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

If you’re using data retention and enterprise search, configure this with a value greater than your data retention policy.

Post aggregator start time

The start time of the daily scheduled aggregator job. Must be a 24-hour time stamp in the form HH:MM based on the local time of the server. Default is 03:00 (3 AM)

System Config path: N/A config.json setting: ElasticsearchSettings > PostsAggregatorJobStartTime > "03:00" Environment variable: MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME

Index prefix

The prefix added to the Elasticsearch or AWS OpenSearch index name.

System Config path: N/A config.json setting: ElasticsearchSettings > IndexPrefix Environment variable: MM_ELASTICSEARCHSETTINGS_INDEXPREFIX

When this setting is used, all Elasticsearch or AWS OpenSearch indexes created by Mattermost are given this prefix. You can set different prefixes so that multiple Mattermost deployments can share an Elasticsearch or AWS OpenSearch cluster without the index names colliding.

Global search prefix

Enable global search across multiple Elasticsearch indices with the same index prefix. This is helpful for setups with multiple data centers where Elasticsearch instances share data using cross-cluster replication. It allows for easier and unified searching across distributed indices. Value must be a prefix of IndexPrefix.

System Config path: N/A config.json setting: ElasticsearchSettings > GlobalSearchPrefix Environment variable: MM_ELASTICSEARCHSETTINGS_GLOBALSEARCHPREFIX

Live indexing batch size

The number of new posts needed before those posts are added to the Elasticsearch or AWS OpenSearch index. Once added to the index, the post becomes searchable. On servers with more than 1 post per second, we suggest setting this value to the average number of posts over a 20 second period of time. Numerical input. Default is 1. Every post is indexed synchronously as they are created.

System Config path: N/A config.json setting: ElasticsearchSettings > LiveIndexingBatchSize > 1 Environment variable: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE

It may be necessary to increase this value to avoid hitting the rate limit or resource limit of your Elasticsearch or AWS OpenSearch cluster on installs handling more than 1 post per second.

What exactly happens when I increase this value?

The primary impact is that a post will be indexed into Elasticsearch or AWS OpenSearch after the threshold of posts is met, which then makes the posts searchable within Mattermost. So, if you set this based on recommendations for larger servers, and you make a post, you cannot find it via search for ~10–20 seconds, on average. Realistically, no users should see or feel this impact due to the limited number of users who are actively searching for a post this quickly. You can set this value to a lower or higher average depending on your Elasticsearch or AWS OpenSearch server specifications.

During busy periods, this delay will be faster as more traffic is occurring, causing more posts and a quicker time to hit the index number. During slower periods, expect the reverse.

How to find the right number for your server

1. You must understand how many posts your server makes every minute. Run the query below to calculate your server's average posts per minute.

   Note that this query can be heavy, so we recommend that you run it during non-peak hours. Additionally, you can adjust the WHERE clause to see the posts per minute over a different time period. Right now 31536000000 represents the number of milliseconds in a year.

   SELECT
     AVG(postsPerMinute) as averagePostsPerMinute
   FROM (
     SELECT
       count(*) as postsPerMinute,
       date_trunc('minute', to_timestamp(createat/1000))
     FROM posts
     WHERE createAt > ( (extract(epoch from now()) * 1000 )  - 31536000000)
     GROUP BY date_trunc('minute', to_timestamp(createat/1000))
   ) as ppm;
   

2. Decide the acceptable index window for your environment, and divide your average posts per minute by that. We suggest 10-20 seconds. Assuming you have 600 posts per minute on average, and you want to index every 20 seconds (60 seconds / 20 seconds = 3) you would calculate 600 / 3 to come to the number 200`. After 200 posts, Mattermost will index the posts into Elasticsearch or AWS OpenSearch. So, on average, there would be a 20-second delay in searchability.

3. Edit the config.json or run mmctl to modify the LiveIndexingBatchSize setting

   In the ``config.json``

   {
     "ElasticsearchSettings": {
       "LiveIndexingBatchSize": 200
     }
   }
   

   Via mmctl

   mmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200
   

   Via an environment variable

   MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200
   

4. Restart the Mattermost server.

Batch size

The number of posts for a single batch during a bulk indexing job. Numerical input. Default is 10000.

System Config path: N/A config.json setting: ElasticsearchSettings > BatchSize > 10000 Environment variable: MM_ELASTICSEARCHSETTINGS_BATCHSIZE

Request timeout

The timeout, in seconds, for Elasticsearch or AWS OpenSearch 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

Options for printing Elasticsearch or AWS OpenSearch trace errors. error: Creates the error trace when initializing the Elasticsearch or AWS OpenSearch 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

Enable CJK analyzers

When enabled, Mattermost uses language-specific analyzer plugins to improve search results for Korean, Japanese, and Chinese content. The required analyzer plugins must be installed on the Elasticsearch or AWS OpenSearch server before enabling this setting. Supported plugins: analysis-nori (Korean) analysis-kuromoji (Japanese) analysis-smartcn (Chinese) true: CJK language-specific analyzers are enabled. false: (Default) Standard analyzers are used.

System Config path: N/A config.json setting: ElasticsearchSettings > EnableCJKAnalyzers > false Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLECJKANALYZERS

Available from Mattermost v11.6. The required analyzer plugins should be installed on the Elasticsearch or AWS OpenSearch server before enabling this setting for full analysis support. If no plugin is detected, a warning will be logged. See the Elasticsearch setup and AWS OpenSearch setup documentation for plugin installation instructions.

If you enable this setting on a server that was previously running Elasticsearch or AWS OpenSearch, you must purge and rebuild the search indexes for existing content to be properly searchable with the new analyzers. See the Elasticsearch setup documentation for instructions on purging and rebuilding indexes.

---

File storage

With self-hosted deployments, you can configure file storage settings by going to System Console > Environment > File Storage, or by editing the config.json file as described in the following tables.

Mattermost supports storing files on the local filesystem, Amazon S3 or S3-compatible containers, and Azure Blob Storage. We have tested Mattermost with Digital Ocean Spaces, but not all S3-compatible containers on the market. If you are looking to use other S3-compatible containers, we recommend completing your own testing. You can also use local storage or a network drive using NFS.

For a step-by-step walk-through covering Azure resource provisioning, System Console configuration, and verification, see Configure Azure Blob Storage as the Mattermost file store.

File storage system

The type of file storage system used. Can be Local File System, Amazon S3, or Azure Blob Storage. local: (Default) Files and images are stored in the specified local file directory. amazons3: Files and images are stored on Amazon S3 based on the access key, bucket, and region fields provided. The driver is compatible with other S3-compatible services, such as Digital Ocean Spaces. azureblob: Files and images are stored on Azure Blob Storage based on the storage account name, shared key, and container fields provided.

System Config path: Environment > File Storage config.json setting: FileSettings > DriverName > "local" Environment variable: MM_FILESETTINGS_DRIVERNAME

After saving a new file storage system, restart every Mattermost server in the deployment for the change to take effect. The file storage backend is initialized at startup and isn't rebuilt automatically when FileSettings change at runtime.

Local storage directory

The local directory to which files are written when the File storage system is set to local. Can be any directory writable by the user Mattermost is running as, and is relative to the directory where Mattermost is installed. Defaults to ./data/.

System Config path: Environment > File Storage config.json setting: FileSettings > Directory Environment variable: MM_FILESETTINGS_DIRECTORY

When File storage system is set to amazons3, this setting has no effect.

Maximum file size

The maximum file size for message attachments and plugin uploads. This value must be specified in mebibytes in the System Console, and in bytes in the config.json file. The default is 104857600 bytes (100 mebibytes).

System Config path: Environment > File Storage config.json setting: FileSettings > MaxFileSize > 104857600 Environment variable: MM_FILESETTINGS_MAXFILESIZE

• Verify server memory can support your setting choice. Large file sizes increase the risk of server crashes and failed uploads due to network disruptions.
• When uploading plugin files, a Received invalid response from the server error typically indicates that MaxFileSize isn't large enough to support the plugin file upload, and/or that proxy settings may not be sufficient.
• If you use a proxy or load balancer in front of Mattermost, the following proxy settings must be adjusted accordingly:
• For NGINX, use client_max_body_size.
• For Apache, use LimitRequestBody.

Enable document search by content

Enable users to search the contents of documents attached to messages. true: (Default) Documents are searchable by their content. false: Documents aren’t searchable by their content. When document content search is disabled, users can search for files by file name only.

System Config path: Environment > File Storage config.json setting: FileSettings > ExtractContent > true Environment variable: MM_FILESETTINGS_EXTRACTCONTENT

Enabling document search by content is required when extracting content from files. Both Mattermost file search and Mattermost Agents can access files and their content, when enabled with the necessary dependencies. Document content search results for files shared before upgrading to Mattermost Server v5.35 may be incomplete until an extraction command is executed using the mmctl. If this command is not run, users can search older files based on file name only.

You can optionally install the following dependencies to extend content searching support in Mattermost to include file formats beyond PDF, DOCX, and ODT, such as DOC, RTF, XML, and HTML:

• tidy: Used to search the contents of HTML documents.
• wv: Used to search the contents of DOC documents.
• poppler-utils: Used to significantly improve server performance when extracting the contents of PDF documents.
• unrtf: Used to search the contents of RTF documents.
• JusText: Used to search HTML documents. See the JusText Python package for deployment information.

If you choose not to install these dependencies, you’ll see log entries for documents that couldn’t be extracted. Any documents that can’t be extracted are skipped and logged so that content extraction can proceed.

Enable searching content of documents within ZIP files

Enables users to search the contents of compressed ZIP files attached to messages. true: Contents of documents within ZIP files are returned in search results. This may have an impact on server performance for large files. the specified local file directory. false: (Default) The contents of documents within ZIP files aren’t returned in search results.

System Config path: Environment > File Storage config.json setting: FileSettings > ArchiveRecursion > false Environment variable: MM_FILESETTINGS_ARCHIVERECURSION

• You can search for document content within ZIP files when using Mattermost in a web browser or the desktop app.
• Searching document contents adds load to your server.
• This setting applies only to standard ZIP files. 7zip (.7z) files are blocked for security reasons and are not searchable.
• For large deployments, or teams that share many large, text-heavy documents, we recommend you review our hardware requirements, and test enabling this feature in a staging environment before enabling it in a production environment.

Amazon S3 bucket

The name of the bucket for your S3-compatible object storage instance. A string with the S3-compatible bucket name.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3Bucket Environment variable: MM_FILESETTINGS_AMAZONS3BUCKET

Amazon S3 path prefix

The prefix you selected for your Amazon S3 bucket in AWS. A string containing the path prefix.

System Config path: N/A config.json setting: FileSettings > AmazonS3PathPrefix Environment variable: MM_FILESETTINGS_AMAZONS3PATHPREFIX

Amazon S3 region

The AWS region you selected when creating your Amazon S3 bucket in AWS. A string with the AWS region containing the bucket. If no region is set, Mattermost attempts to get the appropriate region from AWS, and sets it to us-east-1 if none found.

System Config path: Environment > File Storage config.json setting: `".FileSettings.AmazonS3Region", Environment variable: MM_FILESETTINGS_AMAZONS3REGION

For Digital Ocean Spaces or other S3-compatible services, leave this setting empty.

Amazon S3 access key ID

A string with the access key for the S3-compatible storage instance. Your EC2 administrator can supply you with the Access Key ID.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3AccessKeyId Environment variable: MM_FILESETTINGS_AMAZONS3ACCESSKEYID

This is required for access unless you are using an Amazon S3 IAM Role with Amazon S3.

Amazon S3 endpoint

The hostname of your S3-compatible instance. A string with the hostname of the S3-compatible storage instance. Defaults to s3.amazonaws.com.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3Endpoint > "s3.amazonaws.com" Environment variable: MM_FILESETTINGS_AMAZONS3ENDPOINT

For Digital Ocean Spaces, the hostname should be set to \<region>.digitaloceanspaces.com, where \<region> is the abbreviation for the region you selected when setting up the Space. It can be nyc3, ams3, or sgp1.

Amazon S3 secret access key

The secret access key associated with your Amazon S3 Access Key ID. A string with the secret access key for the S3-compatible storage instance.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3SecretAccessKey Environment variable: MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY

Enable secure Amazon S3 connections

Enable or disable secure Amazon S3 connections. true: (Default) Enables only secure Amazon S3 connections. false: Allows insecure connections to Amazon S3.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3SSL > true Environment variable: MM_FILESETTINGS_AMAZONS3SSL

Amazon S3 signature v2

By default, Mattermost uses Signature v4 to sign API calls to AWS, but under some circumstances, v2 is required. true: Use Signature v2 signing process. false: (Default) Use Signature v4 signing process.

System Config path: N/A config.json setting: FileSettings > AmazonS3SignV2 > false Environment variable: MM_FILESETTINGS_AMAZONS3SIGNV2

See the AWS documentation for information about when to use the Signature v2 signing process.

Enable server-side encryption for Amazon S3

Enable server-side encryption for Amazon S3. true: Encrypts files in Amazon S3 using server-side encryption with Amazon S3-managed keys. false: (Default) Doesn’t encrypt files in Amazon S3.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3SSE > false Environment variable: MM_FILESETTINGS_AMAZONS3SSE

This configuration setting is available for self-hosted deployments only.

Enable Amazon S3 debugging

Enable or disable Amazon S3 debugging to capture additional debugging information in system logs. true: Log additional debugging information is logged to the system logs. false: (Default) No Amazon S3 debugging information is included in the system logs. Typically set to false in production.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3Trace > false Environment variable: MM_FILESETTINGS_AMAZONS3TRACE

Select the Test Connection button in the System Console to validate the settings and ensure the user can access the server.

Amazon S3 storage class

Some Amazon S3-compatible storage solutions require the storage class parameter to be present in upload requests, otherwise they will be rejected. Configure this storage class as the storage class required by your S3-compatible solution.

The storage class to use for uploads to S3-compatible storage solutions. String input. Default is an empty string "". Select Test Connection to test the configured connection.

System Config path: Environment > File Storage config.json setting: FileSettings > AmazonS3StorageClass > "", Environment variable: MM_FILESETTINGS_AMAZONS3STORAGECLASS

Most Amazon S3-compatible storage solutions assign a default storage class of STANDARD when no storage class is provided. See the Amazon S3 storage class documentation for details about supported storage classes.

Export Amazon S3 storage class

The storage class to use for exports to S3-compatible storage solutions. String input. Default is an empty string "".

System Config path: N/A config.json setting: FileSettings > ExportAmazonS3StorageClass > "" Environment variable: MM_FILESETTINGS_EXPORTAMAZONS3STORAGECLASS

Most Amazon S3-compatible storage solutions assign a default storage class of STANDARD when no storage class is provided. See the Amazon S3 storage class documentation for details about supported storage classes.

Amazon S3 request timeout

The amount of time, in milliseconds, before requests to Amazon S3 storage time out. Default is 30000 (30 seconds).

System Config path: N/A config.json setting: FileSettings > AmazonS3RequestTimeoutMilliseconds > 30000 Environment variable: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS

Amazon S3 upload part size

The size, in bytes, of each part in a multi-part upload to Amazon S3. Numeric input of at least 5242880 bytes (5 MiB). Defaults to 5242880 bytes.

System Config path: N/A config.json setting: FileSettings > AmazonS3UploadPartSizeBytes > 5242880 Environment variable: MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES

A smaller part size can result in more requests and an increase in latency, while a larger part size can result in more memory being allocated.

Amazon S3 exported upload part size

The size, in bytes, of each part in a multi-part upload when exporting to Amazon S3. Numeric input of at least 5242880 bytes (5 MiB). Defaults to 104857600 bytes (100 MiB).

System Config path: N/A config.json setting: FileSettings > ExportAmazonS3UploadPartSizeBytes > 104857600 Environment variable: MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES

A smaller part size can result in more requests and an increase in latency, while a larger part size can result in more memory being allocated.

Amazon S3 request timeout

The amount of time, in milliseconds, before requests to Amazon S3 storage time out. Default is 30000 (30 seconds).

System Config path: N/A config.json setting: FileSettings > AmazonS3RequestTimeoutMilliseconds > 30000 Environment variable: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS

Azure Storage account

The name of your Azure Storage account. A string with the storage account name as it appears in the Azure portal. Must be 3-24 lowercase letters and numbers.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureStorageAccount Environment variable: MM_FILESETTINGS_AZURESTORAGEACCOUNT

Azure container

The name of the container in your Azure Storage account where Mattermost stores uploads. A string with the container name.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureContainer Environment variable: MM_FILESETTINGS_AZURECONTAINER

Azure path prefix

An optional path prefix to use for blobs in your Azure container. A string containing the path prefix. Leave empty to write at the container root.

System Config path: Environment > File Storage config.json setting: FileSettings > AzurePathPrefix Environment variable: MM_FILESETTINGS_AZUREPATHPREFIX

Azure authentication

Selects how Mattermost authenticates to the Azure Storage account. shared_key: (Default) Mattermost signs requests with the Storage Account access key in FileSettings.AzureAccessKey. Works for any deployment (on-premises, non-Azure cloud, local development). default_credential: Mattermost obtains an Entra ID token via the Azure SDK's DefaultAzureCredential chain (managed identity, workload identity, service-principal environment variables, or az login — in that order) and signs requests with it. FileSettings.AzureAccessKey is ignored. Recommended for deployments on Azure where the host already provides a managed identity. The identity the SDK selects must hold Storage Blob Data Contributor (or equivalent) on the storage account or container.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureAuthMode Environment variable: MM_FILESETTINGS_AZUREAUTHMODE

Azure Storage account key

The shared key for your Azure Storage account. Used only when FileSettings.AzureAuthMode is shared_key. Find this value in the Azure portal under your storage account's Security + networking > Access keys blade.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureAccessKey Environment variable: MM_FILESETTINGS_AZUREACCESSKEY

Treat the shared key as a secret. Azure provides two keys to support rotation without downtime: update Mattermost to one key, regenerate the other, then swap on the next rotation cycle.

Azure cloud

Selects which Azure cloud Mattermost connects to. The choice determines which host the Azure SDK signs requests against. commercial: (Default) Vhost-style against {'{account}'}.blob.core.windows.net. Only the storage account name is required. government: Vhost-style against {'{account}'}.blob.core.usgovcloudapi.net (Azure Government). Only the storage account name is required. custom: Mattermost uses the value of FileSettings.AzureEndpoint as the full Blob service URL. Use this for Azurite, reverse proxies, Azure China, or any other Azure cloud that doesn't have a built-in preset.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureCloud Environment variable: MM_FILESETTINGS_AZURECLOUD

Azure endpoint

Full Blob service URL, including scheme and storage account. Used only when FileSettings.AzureCloud is custom; ignored for the commercial and government clouds (which derive the URL from the storage account name). Mattermost passes this URL to the Azure SDK unchanged, so the storage account must already be embedded in the hostname (vhost-style, for example https://acmemattermost.blob.core.chinacloudapi.cn/) or in the path (path-style, for example http://localhost:10000/devstoreaccount1/ for Azurite). Shared-key auth signs against the host this URL points at, so make sure it actually serves the storage account configured in FileSettings.AzureStorageAccount.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureEndpoint Environment variable: MM_FILESETTINGS_AZUREENDPOINT

Enable secure Azure Blob Storage connections

Enable or disable secure connections to Azure Blob Storage. true: (Default) Enables only secure Azure Blob Storage connections. false: Allows insecure connections. Only set to false when pointing at a local emulator without TLS.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureSSL > true Environment variable: MM_FILESETTINGS_AZURESSL

Azure request timeout

The amount of time, in milliseconds, before requests to Azure Blob Storage time out. Default is 30000 (30 seconds). Increase only if your network needs more time for large objects.

System Config path: Environment > File Storage config.json setting: FileSettings > AzureRequestTimeoutMilliseconds > 30000 Environment variable: MM_FILESETTINGS_AZUREREQUESTTIMEOUTMILLISECONDS

Initial font

The font used in auto-generated profile pictures with colored backgrounds and username initials. A string with the font file name. Default is nunito-bold.ttf.

System Config path: N/A config.json setting: FileSettings > InitialFont > "nunito-bold.ttf" Environment variable: MM_FILESETTINGS_INITIALFONT

---

Image proxy

With self-hosted deployments, an image proxy can be used by Mattermost apps to prevent them from connecting directly to remote self-hosted servers. Configure an image proxy by going to System Console > Environment > Image Proxy, or by editing the config.json file as described in the following tables.

Enable image proxy

An image proxy anonymizes Mattermost app connections and prevents them from accessing insecure content. true: Enables an image proxy for loading external images. false: (Default) Disables the image proxy.

System Config path: Environment > Image Proxy config.json setting: ImageProxySettings > Enable > true Environment variable: MM_IMAGEPROXYSETTINGS_ENABLE

See the image proxy documentation to learn more.

Image proxy type

The type of image proxy used by Mattermost. local: (Default) The Mattermost server itself acts as the image proxy. From Mattermost v12.0, atmos/camo is no longer supported. If this setting is set to atmos/camo, the server automatically changes it to local on startup and logs a warning.

System Config path: Environment > Image Proxy config.json setting: ImageProxySettings > ImageProxyType > "local" Environment variable: MM_IMAGEPROXYSETTINGS_IMAGEPROXYTYPE

See the image proxy documentation to learn more.

---

SMTP

With self-hosted deployments, you can configure SMTP email server settings by going to System Console > Environment > SMTP, or by editing the config.json file as described in the following tables.

SMTP server

The location of the SMTP email server used for email notifications.

System Config path: Environment > SMTP config.json setting: EmailSettings > SMTPServer Environment variable: MM_EMAILSETTINGS_SMTPSERVER

SMTP server port

The port of SMTP email server. String input. Must be a port number between 1 and 65535.

System Config path: Environment > SMTP config.json setting: EmailSettings > "SMTPPort" Environment variable: MM_EMAILSETTINGS_SMTPPORT

Enable SMTP authentication

Enable or disable SMTP authentication. true: SMTP username and password are used for authenticating to the SMTP server. false: (Default) Mattermost doesn’t attempt to authenticate to the SMTP server.

System Config path: Environment > SMTP config.json setting: EmailSettings > EnableSMTPAuth > false Environment variable: MM_EMAILSETTINGS_ENABLESMTPAUTH

SMTP server username

The username for authenticating to the SMTP server. String input.

System Config path: Environment > SMTP config.json setting: EmailSettings > SMTPUsername Environment variable: MM_EMAILSETTINGS_SMTPUSERNAME

SMTP server password

The password associated with the SMTP username. String input.

System Config path: Environment > SMTP config.json setting: EmailSettings > SMTPPassword Environment variable: MM_EMAILSETTINGS_SMTPPASSWORD

SMTP connection security

Specify connection security for emails sent using SMTP. Not specified: (Default) Send email over an unsecure connection. TLS: Communication between Mattermost and your email server is encrypted. STARTTLS: Attempts to upgrade an existing insecure connection to a secure connection using TLS.

System Config path: Environment > SMTP config.json setting: EmailSettings > ConnectionSecurity Environment variable: MM_EMAILSETTINGS_CONNECTIONSECURITY

Skip server certificate verification

Configure Mattermost to skip the verification of the email server certificate. true: Mattermost won't verify the email server certificate. false: (Default) Mattermost verifies the email server certificate.

System Config path: Environment > SMTP config.json setting: EmailSettings > SkipServerCertificateVerification > false Environment variable: MM_EMAILSETTINGS_SKIPSERVERCERTIFICATEVERIFICATION

Enable security alerts

Enable or disable security alerts. true: (Default) System admins are notified by email if a relevant security fix alert is announced. Requires email to be enabled. false: Security alerts are disabled.

System Config path: Environment > SMTP config.json setting: ServiceSettings > EnableSecurityFixAlert > true Environment variable: MM_SERVICESETTINGS_ENABLESECURITYFIXALERT

See the Telemetry documentation to learn more.

SMTP server timeout

The maximum amount of time, in seconds, allowed for establishing a TCP connection between Mattermost and the SMTP server. Numerical value in seconds.

System Config path: Environment > SMTP config.json setting: EmailSettings > SMTPServerTimeout Environment variable: MM_EMAILSETTINGS_SMTPSERVERTIMEOUT

---

Push notification server

---

High availability

With self-hosted deployments, you can configure Mattermost as a high availability cluster-based deployment by going to System Console > Environment > High Availability, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

When a Mattermost high availability cluster-based deployment uses config.json for configuration, the System Console is set to read-only by default, and settings can only be changed by editing the config.json file directly. However, to test a high availability cluster-based 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. When configuration is stored in the database, ClusterSettings.ReadOnlyConfig is ignored and the System Console remains fully editable. See Store configuration in your database for details.

Enable high availability mode

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 > false Environment variable: MM_CLUSTERSETTINGS_ENABLE

Cluster name

The cluster to join by name in a high availability cluster-based deployment. 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

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-based deployment documentation for details.

Use IP address

You can configure your high availability cluster-based deployment 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

Enable gossip encryption

Gossip encryption uses AES-256 by default, and this value isn't configurable by design. 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 > EnableGossipEncryption > true Environment variable: MM_CLUSTERSETTINGS_ENABLEGOSSIPENCRYPTION

• The Gossip protocol is based on principles outlined in the SWIM protocol developed by researchers at Cornell University. The gossip protocol is a communication mechanism in distributed systems where nodes randomly exchange information to ensure data consistency across the network. It is decentralized, scalable, and fault-tolerant, making it ideal for systems with numerous nodes. Information is spread in a manner similar to social gossip, with nodes periodically "gossiping" updates to random peers until the network converges to a consistent state. Widely used in distributed databases, blockchain networks, and peer-to-peer systems, the protocol is simple to implement and resilient to node failures. However, it can suffer from redundancy and propagation delays in large networks.
• 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.
• From Mattermost v10.11, gossip encryption is enabled by default for all new deployments. For existing deployments, all communication using the gossip protocol remains unencrypted unless you manually enable encryption. Prior to v10.11, gossip encryption is enabled by default for Cloud deployments and disabled by default for self-hosted deployments.

Enable gossip compression

We recommend that you disable this configuration setting for better performance. true: (Default for self-hosted deployments) All communication through the cluster uses gossip compression. This setting is enabled by default to maintain compatibility with older servers. false: (Default for Cloud deployments) All communication using the gossip protocol remains uncompressed.

System Config path: Environment > High Availability config.json setting: ClusterSettings > EnableGossipCompression > true Environment variable: MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION

Gossip port

The port used for the gossip protocol. Both UDP and TCP should be allowed on this port. Numerical input. Must be a port number between 1 and 65535. Default is 8074.

System Config path: Environment > High Availability config.json setting: ClusterSettings > GossipPort > 8074 Environment variable: MM_CLUSTERSETTINGS_GOSSIPPORT

Read only config

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

An IP address used to identify the device that does automatic IP detection in high availability cluster-based deployments. String input.

System Config path: N/A config.json setting: ClusterSettings > NetworkInterface > "" Environment variable: MM_CLUSTERSETTINGS_NETWORKINTERFACE

Bind address

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

Advertise address

The IP address used to access the server from other nodes. This settings is used primary when cluster nodes are not in the same network and involve NAT (Network Address Translation). String input.

System Config path: N/A config.json setting: ClusterSettings > AdvertiseAddress > "" Environment variable: MM_CLUSTERSETTINGS_ADVERTISEADDRESS

---

Rate limiting

---

Logging

Mattermost provides 3 independent logging systems for self-hosted deployments that can be configured separately with separate log files and rotation policies to meet different operational and compliance needs:

• Log Settings
• Notification Log Settings
• Audit Log Settings

By default, all Mattermost editions write logs to both the console and to the mattermost.log file in a machine-readable JSON format. Mattermost Enterprise and Professional customers can additionally log directly to syslog and TCP socket destination targets.

Log settings

Configure general logging by going to System Console > Environment > Logging, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Output logs to console

Configure Mattermost to output general logs to the console. true: (Default) Output log messages are written to the console based on the console log level configuration. The server writes messages to the standard output stream (stdout). false: Output log messages aren’t written to the console.

System Config path: Environment > Logging config.json setting: LogSettings > EnableConsole > true Environment variable: MM_LOGSETTINGS_ENABLECONSOLE

From Mattermost v11.0, notification logs are automatically included in the main console logs.

Console log level

The level of detail in general log events written when Mattermost outputs log messages to the console. DEBUG: (Default) Outputs verbose detail for developers debugging issues. ERROR: Outputs only error messages. INFO: Outputs error messages and information around startup and initialization. TRACE, WARN, FATAL, and PANIC are also accepted. Values are case-insensitive, and any other value fails configuration validation.

System Config path: Environment > Logging config.json setting: LogSettings > ConsoleLevel > "DEBUG" Environment variable: MM_LOGSETTINGS_CONSOLELEVEL

Output console logs as JSON

Configure Mattermost to output general console logs as JSON. true: (Default) Logged events are written in a machine-readable JSON format. false: Logged events are written in plain text.

System Config path: Environment > Logging config.json setting: LogSettings > ConsoleJson > true Environment variable: MM_LOGSETTINGS_CONSOLEJSON

Typically set to true in a production environment.

Colorize plain text console logs

Enables system admins to display plain text general log level details in color. true: When logged events are output to the console as plain text, colorize log levels details. false: (Default) Plain text log details aren't colorized in the console.

System Config path: N/A config.json setting: LogSettings > EnableColor > false Environment variable: MM_LOGSETTINGS_ENABLECOLOR

Output logs to file

Configure Mattermost to output general console logs to a file. true: (Default) Logged events are written based on the file log level configuration to a mattermost.log file located in the directory configured via file location. false: Logged events aren’t written to a file.

System Config path: Environment > Logging config.json setting: LogSettings > EnableFile > true Environment variable: MM_LOGSETTINGS_ENABLEFILE

• From Mattermost v11.0, notification logs are automatically included in the main file logs.
• This setting is typically set to true in a production environment. When enabled, you can download the mattermost.log file locally by going to System Console > Reporting > Server Logs, and selecting Download Logs.

File log directory

The location of the general log files. String input. If left blank, log files are stored in the ./logs directory.

System Config path: Environment > Logging config.json setting: LogSettings > FileLocation > "" Environment variable: MM_LOGSETTINGS_FILELOCATION

• The path you configure must exist, and Mattermost must have write permissions for this directory.
• From Mattermost v11.4, you can use the MM_LOG_PATH environment variable to restrict log file locations to a designated root directory. This security enhancement ensures that all log files configured via LogSettings.FileLocation, LogSettings.AdvancedLoggingJSON, ExperimentalAuditSettings.FileName, or ExperimentalAuditSettings.AdvancedLoggingJSON remain within an authorized logging directory.
• If MM_LOG_PATH isn't set, the default logs directory is used. Paths outside the root directory generate error logs and are excluded from support packet downloads. See the log path restrictions documentation for details.
• By default, a path outside the root directory is only logged as an error and the configuration is still accepted. Set the EnforceLogPathRoot feature flag (MM_FEATUREFLAGS_ENFORCELOGPATHROOT=true) to reject it instead: the server refuses to start, and configuration changes that introduce such a path are rejected with an error. Enforcement is opt-in today and will become the default in a future release, so we recommend enabling it once you've confirmed every log path resolves inside MM_LOG_PATH.

File log level

The level of detail in general log events when when Mattermost outputs log messages to a file. DEBUG: Outputs verbose detail for developers debugging issues. ERROR: Outputs only error messages. INFO: (Default) Outputs error messages and information around startup and initialization. TRACE, WARN, FATAL, and PANIC are also accepted. Values are case-insensitive, and any other value fails configuration validation.

System Config path: Environment > Logging config.json setting: LogSettings > FileLevel > "INFO" Environment variable: MM_LOGSETTINGS_FILELEVEL

Output file logs as JSON

Configure Mattermost to output general file logs as JSON. true: (Default) Logged events are written in a machine-readable JSON format. false: Logged events are written in plain text.

System Config path: Environment > Logging config.json setting: LogSettings > FileJson > true Environment variable: MM_LOGSETTINGS_FILEJSON

Typically set to true in a production environment.

Enable webhook debugging

Configure Mattermost to capture the contents of general incoming webhooks to console and/or file logs for debugging. true: (Default) The contents of incoming webhooks are printed to log files for debugging. false: The contents of incoming webhooks aren’t printed to log files.

System Config path: Environment > Logging config.json setting: LogSettings > EnableWebhookDebugging > true Environment variable: MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING

Enable debug logs by changing the file log level to DEBUG to include the request body of incoming webhooks in logs.

Output logs to multiple targets

Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send general log records to multiple targets. String input can contain a filespec to another configuration file, a database DSN, or JSON.

System Config path: Environment > Logging config.json setting: LogSettings > AdvancedLoggingJSON > ": "" Environment variable: MM_LOGSETTINGS_ADVANCEDLOGGINGJSON

• See the Mattermost logging documentation for details. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed.
• Logs are recorded asynchronously to reduce latency to the caller.
• Advanced logging supports hot-reloading of logger configuration.
• From Mattermost v11.4, file paths specified in AdvancedLoggingJSON configurations should be within the directory specified by the MM_LOG_PATH environment variable. See log path restrictions for details.

Maximum field size

Enables system admins to limit the size of general log fields during logging. Numerical value. Must be 0 or greater. Default is 2048.

System Config path: N/A config.json setting: LogSettings > MaxFieldSize > 2048 Environment variable: MM_LOGSETTINGS_MAXFIELDSIZE

Enable diagnostics and error reporting

Controls whether server errors and crashes are reported to Mattermost via Sentry. true: (Default) Error and crash reports are sent to Mattermost's Sentry endpoint. false: No error or crash data is sent.

System Config path: Environment > Logging config.json setting: LogSettings > EnableDiagnostics > true Environment variable: MM_LOGSETTINGS_ENABLEDIAGNOSTICS

See the telemetry documentation for details on the information Mattermost collects.

Enable Sentry reporting

Whether or not general error reports are sent to Sentry. true: (Default) Send error reports to Sentry. Default matches the EnableDiagnostics setting. false: Error reports are not sent to Sentry.

System Config path: N/A config.json setting: LogSettings > EnableSentry > true Environment variable: MM_LOGSETTINGS_ENABLESENTRY

---

Notification logging

From Mattermost v11, notification log settings have been consolidated into the standard console logs and mattermost.log file. You can no longer disable notification logging without using advanced logging settings, as the main log level setting now controls both server and notification logs.

You can use the AdvancedLoggingJSON configuration with discrete notification log levels: NotificationError, NotificationWarn, NotificationInfo, NotificationDebug, and NotificationTrace to split notification logs into separate files and reduce troubleshooting noise. See Advanced Logging for details.

The following configuration settings apply only to Mattermost server versions prior to v11.0.

You can configure logging specifically for Mattermost notifications by editing the config.json file as described in the following tables. These settings operate independently from the main LogSettings and allow you to customize logging behavior specifically for the notification subsystem. Changes to these configuration settings require a server restart before taking effect.

Output logs to console

Configure Mattermost to output notification logs to the console. true: (Default) Output log messages are written to the console based on the console log level configuration. The server writes messages to the standard output stream (stdout). false: Output log messages aren't written to the console.

System Config path: N/A config.json setting: NotificationLogSettings > EnableConsole > true Environment variable: MM_NOTIFICATIONLOGSETTINGS_ENABLECONSOLE

Console log level

The level of detail in notification log events written when Mattermost outputs log messages to the console. DEBUG: (Default) Outputs verbose detail for developers debugging issues. ERROR: Outputs only error messages. INFO: Outputs error messages and information around startup and initialization. TRACE, WARN, FATAL, and PANIC are also accepted. Values are case-insensitive, and any other value fails configuration validation.

System Config path: N/A config.json setting: NotificationLogSettings > ConsoleLevel > "DEBUG" Environment variable: MM_NOTIFICATIONLOGSETTINGS_CONSOLELEVEL

Output console logs as JSON

Configure Mattermost to output notification console logs as JSON. true: (Default) Logged events are written in a machine-readable JSON format. false: Logged events are written in plain text.

System Config path: N/A config.json setting: NotificationLogSettings > ConsoleJson > true Environment variable: MM_NOTIFICATIONLOGSETTINGS_CONSOLEJSON

Typically set to true in a production environment.

Colorize plain text console logs

Enables system admins to display plain text notification log level details in color. true: When logged events are output to the console as plain text, colorize log levels details. false: (Default) Plain text log details aren't colorized in the console.

System Config path: N/A config.json setting: NotificationLogSettings > EnableColor > false Environment variable: MM_NOTIFICATIONLOGSETTINGS_ENABLECOLOR

Output logs to file

Configure Mattermost to output notification console logs to a file. true: (Default) Logged events are written based on the file log level configuration to a notifications.log file located in the directory configured via file location. false: Logged events aren't written to a file.

System Config path: N/A config.json setting: NotificationLogSettings > EnableFile > true Environment variable: MM_NOTIFICATIONLOGSETTINGS_ENABLEFILE

File log directory

The location of the notification log files. String input. If left blank, log files are stored in the ./logs directory.

System Config path: N/A config.json setting: NotificationLogSettings > FileLocation > "" Environment variable: MM_NOTIFICATIONLOGSETTINGS_FILELOCATION

The path you configure must exist, and Mattermost must have write permissions for this directory.

File log level

The level of detail in notification log events when Mattermost outputs log messages to a file. DEBUG: Outputs verbose detail for developers debugging issues. ERROR: Outputs only error messages. INFO: (Default) Outputs error messages and information around startup and initialization. TRACE, WARN, FATAL, and PANIC are also accepted. Values are case-insensitive, and any other value fails configuration validation.

System Config path: N/A config.json setting: NotificationLogSettings > FileLevel > "INFO" Environment variable: MM_NOTIFICATIONLOGSETTINGS_FILELEVEL

Output file logs as JSON

Configure Mattermost to output notification file logs as JSON. true: (Default) Logged events are written in a machine-readable JSON format. false: Logged events are written in plain text.

System Config path: N/A config.json setting: NotificationLogSettings > FileJson > true Environment variable: MM_NOTIFICATIONLOGSETTINGS_FILEJSON

Output logs to multiple targets

Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send notification log records to multiple targets. String input can contain a filespec to another configuration file, a database DSN, or JSON.

System Config path: N/A config.json setting: NotificationLogSettings > AdvancedLoggingJSON > ": "" Environment variable: MM_NOTIFICATIONLOGSETTINGS_ADVANCEDLOGGINGJSON

---

Audit logging

Configure audit logging by going to System Console > Compliance > Audit Logging, or by editing the config.json file as described in the following tables. These settings operate independently from the main LogSettings and allow you to customize logging behavior specifically for the audit subsystem. Changes to these configuration settings require a server restart before taking effect.

Output audit logs to file

Whether to write audit log files to disk. true: Logged events are written to the file specified by the audit file name configuration setting. false: (Default) Audit log files aren't written.

System Config path: Compliance > Audit Logging config.json setting: ExperimentalAuditSettings > FileEnabled > false Environment variable: MM_EXPERIMENTALAUDITSETTINGS_FILEENABLED

When FileEnabled is set to true, then the audit file name must be set.

Audit file name

The name of the audit log files. The path that you set to the audit file must exist and Mattermost must have write permissions in it. Example: /var/log/mattermost_audit.log

System Config path: Compliance > Audit Logging config.json setting: ExperimentalAuditSettings > FileName > "" Environment variable: MM_EXPERIMENTALAUDITSETTINGS_FILENAME

When output audit logs to file is enabled, the file name must be set. To configure file rotation and advanced audit log output, use the AdvancedLoggingJSON setting.

Audit log certificate

Certificate configuration for audit logging. String input. Default is blank.

System Config path: N/A config.json setting: ExperimentalAuditSettings > Certificate > "" Environment variable: MM_EXPERIMENTALAUDITSETTINGS_CERTIFICATE

Output audit logs to multiple targets

Configures Mattermost to output audit log records to multiple targets.

System Config path: Compliance > Audit Logging config.json setting: ExperimentalAuditSettings > AdvancedLoggingJSON > {} Environment variable: MM_EXPERIMENTALAUDITSETTINGS_ADVANCEDLOGGINGJSON

• See the Mattermost logging documentation for details on advanced logging configuration. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed.
• Audit logs are recorded asynchronously to reduce latency to the caller.
• Advanced audit logging supports hot-reloading of logger configuration.
• From Mattermost v12.0, the audit-delivery log level isn't written by the built-in audit log file target, so post delivery audit records are discarded unless you add a target here whose levels list includes {"id": 104, "name": "audit-delivery"}.

---

Session lengths

With self-hosted deployments, user sessions are cleared when a user tries to log in, and sessions are cleared every 24 hours from the sessions database table. Configure session lengths by going to System Console > Environment > Session Lengths, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Extend session length with activity

Improves the user experience by extending sessions and keeping users logged in if they are active in their Mattermost apps. true: (Default) Sessions are automatically extended when users are active in their Mattermost client. User sessions only expire when users aren’t active in their Mattermost client for the entire duration of the session lengths defined. false: Sessions won't extend with activity in Mattermost. User sessions immediately expire at the end of the session length or based on the session idle timeout configured.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > ExtendSessionLengthWithActivity > true Environment variable: MM_SERVICESETTINGS_EXTENDSESSIONLENGTHWITHACTIVITY

Terminate sessions on password change

Enable or disable session revocation when a user's password changes. true: (Default for new deployments) Session revocation is enabled. All sessions of a user expire if their password is changed (by themselves or by a system admin). If the password change is initiated by the user, their current session isn't terminated. false: (Default for existing deployments) Session revocation is disabled. When users change their password, only the user's current session is revoked. When a system admin changes the user's password, none of the user's sessions are revoked.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > TerminateSessionsOnPasswordChange > true Environment variable: MM_SERVICESETTINGS_TERMINATESESSIONSONPASSWORDCHANGE

Session length for AD/LDAP and email

Set the number of hours counted from the last time a user entered their credentials into the web app or the desktop app to the expiry of the user’s session on email and AD/LDAP authentication. Numerical input in hours. Default is 720 hours.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > SessionLengthWebInHours > 720 Environment variable: MM_SERVICESETTINGS_SESSIONLENGTHWEBINHOURS

After changing this setting, the new session length takes effect after the next time the user enters their credentials.

Session length for mobile

Set the number of hours counted from the last time a user entered their credential into the mobile app to the expiry of the user’s session. Numerical input in hours. Must be greater than 0. Default is 720 hours.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > SessionLengthMobileInHours > 720 Environment variable: MM_SERVICESETTINGS_SESSIONLENGTHMOBILEINHOURS

After changing this setting, the new session length takes effect after the next time the user enters their credentials.

Session length for SSO

Set the number of hours from the last time a user entered their SSO credentials to the expiry of the user’s session. This setting defines the session length for SSO authentication, such as SAML, GitLab, and OAuth 2.0. Numerical input in hours. Must be greater than 0. Default is 720 hours.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > SessionLengthSSOInHours > 720 Environment variable: MM_SERVICESETTINGS_SESSIONLENGTHSSOINHOURS

• After changing this setting, the new session length takes effect after the next time the user enters their credentials.
• If the authentication method is SAML, GitLab, or OAuth 2.0, users may automatically be logged back in to Mattermost if they are already logged in to SAML, GitLab, or with OAuth 2.0.

Session cache

Set the number of minutes to cache a session in memory. Numerical input in minutes. Must be greater than 0. Default is 10 minutes.

System Config path: Environment > Session Lengths config.json setting: ServiceSettings > SessionCacheInMinutes > 10 Environment variable: MM_SERVICESETTINGS_SESSIONCACHEINMINUTES

Session idle timeout

The number of minutes from the last time a user was active on the system to the expiry of the user’s session. Once expired, the user will need to log in to continue. Numerical input in minutes. Default is 43200 (30 days). Minimum value is 5 minutes, and a value of 0 sets the time as unlimited.

System Config path: N/A config.json setting: ServiceSettings > SessionIdleTimeoutInMinutes > 43200 Environment variable: MM_SERVICESETTINGS_SESSIONIDLETIMEOUTINMINUTES

• This setting has no effect when extend session length with activity is set to true.
• This setting applies to the webapp and the desktop app. For mobile apps, use an EMM provider to lock the app when not in use. |
• In high availability mode, enable IP hash load balancing for reliable timeout measurement.

---

Performance monitoring

With self-hosted deployments, you can configure performance monitoring by going to System Console > Environment > Performance Monitoring, or by editing the config.json file as described in the following tables.

{
  "MetricsSettings": {
    "Enable": false,
    "BlockProfileRate": 0,
    "ListenAddress": :8067,
    "EnableClientMetrics": false,
    "EnableNotificationMetrics": true,
    "ClientSideUserIds": ""
  }
}

Changes to configuration settings in this section require a server restart before taking effect.

See the performance monitoring documentation to learn more about setting up performance monitoring with Prometheus and Grafana. See the collect performance metrics documentation to learn more about using the Mattermost Metrics plugin.

Enable performance monitoring

Enable or disable performance monitoring. true: Performance monitoring data collection and profiling is enabled. false: (Default) Mattermost performance monitoring is disabled.

System Config path: Environment > Performance Monitoring config.json setting: MetricsSettings > Enable > false Environment variable: MM_METRICSSETTINGS_ENABLE

See the performance monitoring documentation to learn more.

Enable client performance monitoring

Enable or disable client performance monitoring. true: Client performance monitoring data collection and profiling is enabled. false: (Default) Mattermost client performance monitoring is disabled.

System Config path: Environment > Performance Monitoring config.json setting: MetricsSettings > EnableClientMetrics > false Environment variable: MM_METRICSSETTINGS_ENABLECLIENTMETRICS

Client side user ids

A list of comma-separated user IDs you want to track for client-side webapp metrics. Limited to 5 user IDs. Blank by default.

System Config path: Environment > Performance Monitoring config.json setting: MetricsSettings > ClientSideUserIds Environment variable: MM_METRICSSETTINGS_CLIENTSIDEUSERIDS

• This setting only applies when EnableClientMetrics is set to true.
• Each user ID should correspond to a valid user in the Mattermost system. For example, MM_METRICSSETTINGS_CLIENTSIDEUSERIDS="user1,user2,user3".
• The total number of user IDs is limited to 5 to ensure performance. Adding more IDs can overwhelm Prometheus due to high label cardinality. To avoid performance issues, we recommend minimizing changes to this list.

Listen address

The port the Mattermost server will listen on to expose performance metrics, when enabled. Numerical input. Default is 8067.

System Config path: Environment > Performance Monitoring config.json setting: MetricsSettings > ListenAddress > 8067 Environment variable: MM_METRICSSETTINGS_LISTENADDRESS

• ListenAddress accepts a port only. It doesn’t take an IP/host. If you need to restrict interfaces, do so via your OS firewall or reverse proxy.
• The address uses a host:port format. Use :8067 to listen on all interfaces on port 8067, or use localhost:8067 to restrict to localhost only.

Block profile rate

Control how often Mattermost collects data about delays caused by blocking operations within Mattermost (such as when one part of the program has to wait for another). Default is 0 (profiling is disabled). The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked. Default is 0.

System Config path: N/A config.json setting: MetricsSettings > BlockProfileRate > 0 Environment variable: MM_METRICSSETTINGS_BLOCKPROFILERATE

• This setting isn't available in the System Console and can only be set in config.json.
• Only adjust this if you’re diagnosing performance issues and know how to analyze profiling data. The value represents how frequently Mattermost records blocking events in its performance profile:
• Set to 0 to record no blocking events (profiling is disabled).
• Set to 1 to record every blocking event (profiling is fully enabled).
• Set to a higher number to record only a fraction of events (useful for sampling instead of full profiling).

Enable notification monitoring

Enable or disable notification metrics data collection. true: (Default) Mattermost notification data collection is enabled for client-side web and desktop app users. false: Mattermost notification data collection is disabled.

System Config path: Site Configuration > Notifications config.json setting: MetricsSettings > EnableNotificationMetrics > true Environment variable: MM_METRICSSETTINGS_ENABLENOTIFICATIONMETRICS

• MetricsSettings.Enable must be set to true
• MetricsSettings.EnableNotificationMetrics must be set to true

See the performance monitoring documentation to learn more about Mattermost Notification Health metrics.

---

Developer

With self-hosted deployments, you can configure developer mode by going to System Console > Environment > Developer, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Enable testing commands

Enable or disable the /test slash command. true: (Default) The /test slash command is enabled to load test accounts and test data. Use this setting only in isolated non-production environments and never in production. false: The /test slash command is disabled.

System Config path: Environment > Developer config.json setting: ServiceSettings > EnableTesting > true Environment variable: MM_SERVICESETTINGS_ENABLETESTING

Enable developer mode

Enable or disable developer mode. true: (Default) Javascript errors are shown in a banner at the top of Mattermost the user interface. Not recommended for use in production. false: Users are not alerted to Javascript errors.

System Config path: Environment > Developer config.json setting: ServiceSettings > EnableDeveloper > true Environment variable: MM_SERVICESETTINGS_ENABLEDEVELOPER

Enable client debugging

Enable or disable client-side debugging settings found in Settings > Advanced > Debugging for individual users. true: Those settings are visible and can be enabled by users. false: (Default) Those settings are hidden and disabled.

System Config path: Environment > Developer config.json setting: ServiceSettings > EnableClientPerformanceDebugging > false Environment variable: MM_SERVICESETTINGS_ENABLECLIENTPERFORMANCEDEBUGGING

See the client debugging documentation to learn more.

Allow untrusted internal connections

This setting is intended to prevent users located outside your local network from using the Mattermost server to request confidential data from inside your network. Care should be used when configuring this setting to prevent unintended access to your local network.

Limit the ability for the Mattermost server to make untrusted requests within its local network. A request is considered “untrusted” when it’s made on behalf of a client.

System Config path: Environment > Developer config.json setting: ServiceSettings > AllowedUntrustedInternalConnections > "" Environment variable: MM_SERVICESETTINGS_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS

This setting is a whitelist of local network addresses that can be requested by the Mattermost server. It’s configured as a whitespace-separated list of hostnames, IP addresses, and CIDR ranges that can be accessed.

Requests that can only be configured by system admins are considered trusted and won't be affected by this setting. Trusted URLs include ones used for OAuth login or for sending push notifications.

The following features make untrusted requests and are affected by this setting:

• Integrations using webhooks, slash commands, or message actions. This prevents them from requesting endpoints within the local network.
• Link previews. When a link to a local network address is posted in a chat message, this prevents a link preview from being displayed.
• The local image proxy. If the local image proxy is enabled, images located on the local network cannot be used by integrations or posted in chat messages.

Some examples of when you may want to modify this setting include:

• When installing a plugin that includes its own images, such as Matterpoll, you'll need to add the Mattermost server’s domain name to this list.
• When running a bot or webhook-based integration on your local network, you’ll need to add the hostname of the bot/integration to this list.
• If your network is configured in such a way that publicly-accessible web pages or images are accessed by the Mattermost server using their internal IP address, the hostnames for those servers must be added to this list.

• The public IP of the Mattermost application server itself is also considered a reserved IP.
• Use whitespaces instead of commas to list the hostnames, IP addresses, or CIDR ranges. For example: webhooks.internal.example.com, 127.0.0.1, or 10.0.16.0/28.
• IP address and domain name rules are applied before host resolution.
• CIDR rules are applied after host resolution, and only CIDR rules require DNS resolution.
• Mattermost attempts to match IP addresses and hostnames without even resolving. If that fails, Mattermost resolve using the local resolver (by reading the /etc/hosts file first), then checking for matching CIDR rules. For example, if the domain “webhooks.internal.example.com” resolves to the IP address 10.0.16.20, a webhook with the URL https://webhooks.internal.example.com/webhook can be whitelisted using webhooks.internal.example.com, or 10.0.16.16/28, but not 10.0.16.20.

Mobile security

From Mattermost v10.7 and mobile app v2.27, you can configure biometric authentication, prevent Mattermost use on jailbroken or rooted devices, and can block screen captures without relying on an EMM Provider. Configure these options by going to System Console > Environment > Mobile Security, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart and require users to restart their mobile app or log out and back in before taking effect.

Enable biometric authentication

Enforce biometric authentication, with PIN/passcode fallback, before accessing the app. Users will be prompted based on session activity and server switching rules. true: Biometric authentication is enabled. false: (Default) Biometric authentication is disabled.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileEnableBiometrics > false Environment variable: MM_NATIVEAPPSETTINGS_MOBILEENABLEBIOMETRICS

• Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.
• Users must authenticate in the following situations:
• Adding a new server: When a new server is added to the mobile app and biometric authentication is enabled.
• Opening the mobile app: At app launch when the active server requires authentication.
• Returning after background use: After the app has been in the background for 5 minutes or more and the active server requires authentication.
• Using multiple servers: When accessing a server for the first time, after 5 minutes of inactivity on a server, and when the last authentication attempt fails.

Enable jailbreak/root protection

Prevent access to the app on devices detected as jailbroken or rooted. If a device fails the security check, users will be denied access or prompted to switch to a compliant server. true: Jailbreak/Root protection is enabled. false: (Default) Jailbreak/Root protection is disabled.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileJailbreakProtection > false Environment variable: MM_NATIVEAPPSETTINGS_MOBILEJAILBREAKPROTECTION

• Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.
• See the Expo SDK documentation to learn more about how checks are performed for this functionality.

Prevent screen capture

Block screenshots and screen recordings when using the mobile app. Screenshots will appear blank, and screen recordings will blur (iOS) or show a black screen (Android). Also applies when switching apps. true: Screen capture blocking is enabled. false: (Default) Screen capture blocking is disabled.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobilePreventScreenCapture > false Environment variable: MM_NATIVEAPPSETTINGS_MOBILEPREVENTSCREENCAPTURE

Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.

Mobile ephemeral mode

See mobile security features for a full description of how the timers and operations interact.

These settings apply globally to all mobile users. Changes are delivered to connected devices in real time; offline devices continue operating under their last-known configuration until they reconnect. Timer state persists across app and device restarts.

When a timer expires, active cached content such as posts and file previews is purged, and the app notifies the user that data was removed due to policy enforcement. After a purge, users re-sync from the server on reconnection — server URLs are recoverable from keychain entries so server access is not lost.

Enable Mobile Ephemeral Mode

Controls whether mobile clients enforce the server-configured ephemeral data policies. true: (Default) Ephemeral data policies are enforced. false: Ephemeral data policies are not enforced on mobile clients.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileEnableEphemeralMode > true Environment variable: MM_NATIVEAPPSETTINGS_MOBILEENABLEEPHEMERALMODE

Disconnection timeout

Grace period in seconds after the WebSocket drops before the device is considered offline. Once elapsed, the Offline Persistence Timer begins counting down. Numerical input in seconds. Default is 60. Values below 5 are not recommended.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileDisconnectionTimeoutSeconds > 60 Environment variable: MM_NATIVEAPPSETTINGS_MOBILEDISCONNECTIONTIMEOUTSECONDS

Offline persistence timer

How long cached content is retained after the device is considered offline, in hours. Numerical input in hours. Default is 2. Set to 0 for immediate purge on disconnect.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileOfflinePersistenceTimerHours > 2 Environment variable: MM_NATIVEAPPSETTINGS_MOBILEOFFLINEPERSISTENCETIMERHOURS

Auto cache cleanup

Maximum age in days for content cached on the device, regardless of connection status. Numerical input in days. Default is 7. Set to 0 for zero-persistence mode.

System Config path: Environment > Mobile Security config.json setting: NativeAppSettings > MobileAutoCacheCleanupDays > 7 Environment variable: MM_NATIVEAPPSETTINGS_MOBILEAUTOCACHECLEANUPDAYS

Enable secure file preview on mobile

This setting improves an organization's mobile security posture by restricting file access while still allowing essential file viewing capabilities.

true: Prevents file downloads, previews, and sharing for most file types, | - System Config path: Site Configuration > File sharing and downloads | even when the | - config.json setting: FileSettings > MobileEnableSecureFilePreview > false | Allow file downloads on mobile | - Environment variable: MM_FILESETTINGS_MOBILEENABLESECUREFILEPREVIEW configuration setting is enabled. Allows in-app previews for PDFs, | | videos, and images only. Files are stored temporarily in the app's cache and cannot be exported or shared. | | false: (Default) Secure file preview mode is disabled. | |

Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.

Allow PDF link navigation on mobile

true: (Default) Enables tapping links inside PDFs on mobile when Secure File Preview Mode is active. Links will open in the device browser or supported app. false: Disables link navigation in PDFs when Secure File Preview Mode is active.

System Config path: Site Configuration > File sharing and downloads config.json setting: FileSettings > MobileAllowPdfLinkNavigation > true Environment variable: MM_FILESETTINGS_MOBILEALLOWPDFLINKNAVIGATION

• Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.
• This setting has no effect when the Secure file preview on mobile configuration setting is disabled.

---

config.json-only settings

The following self-hosted deployment settings are only configurable in the config.json file and are not available in the System Console.

Disable Customer Portal requests

Enable or disable customer portal requests. true: (Default) Server-side requests made to the customer portal are disabled. false: Server-side requests made to the Mattermost Customer Portal are enabled, but will always fail in air-gapped and restricted deployment environments.

System Config path: N/A config.json setting: CloudSettings > Disable > true, Environment variable: MM_CLOUDSETTINGS_DISABLE

Cloud admins can’t modify this configuration setting.

Enable API team deletion

Allow permanent team deletion via API. true: Team and system admins (or users with appropriate permissions) can call api/v4/teams/{teamid}?permanent=true or use mmctl team delete to permanently delete a team. false: (Default) Endpoint not available; api/v4/teams/{teamid} still soft deletes a team.

System Config path: N/A config.json setting: ServiceSettings > EnableAPITeamDeletion > false Environment variable: N/A

This setting isn’t available in the System Console and can only be set in config.json.

Enable API user deletion

Allow permanent user deletion via API. true: System admins (or users with appropriate permissions) can call api/v4/users/{userid}?permanent=true or use mmctl user delete to permanently delete a user. false: (Default) Endpoint not available; api/v4/users/{userid} still soft deletes a user.

System Config path: N/A config.json setting: ServiceSettings > EnableAPIUserDeletion > false Environment variable: N/A

This setting isn’t available in the System Console and can only be set in config.json.

Enable API channel deletion

Allow permanent channel deletion via API. true: System admins (or users with appropriate permissions) can call api/v4/channels/{channelid}?permanent=true or use mmctl channel delete to permanently delete a channel. false: (Default) Endpoint not available; api/v4/channels/{channelid} still soft deletes a channel.

System Config path: N/A config.json setting: ServiceSettings > EnableAPIChannelDeletion > false Environment variable: N/A

This setting isn’t available in the System Console and can only be set in config.json.

Enable desktop app developer mode

From Desktop App v5.10, this setting enables developer debugging options available by going to the View > Developer Tools menu in the Mattermost desktop app.

This setting isn't available in the System Console and can only be enabled in config.json by setting the environment variable MM_DESKTOP_DEVELOPER_MODE to true. This setting is disabled by default.

• True: Unlocks the following options in the Desktop App for the purposes of troubleshooting and debugging. You should only enable this setting if instructed to by a Mattermost developer:
• Browser Mode Only: Completely disables the preload script and stops web app components from knowing they're in the desktop app. This option should be the best indicator of whether a web app component is causing performance and/or memory retention issues. This option disables notifications, cross-tab navigation, unread/mentions badges, the calls widget, and breaks resizing on macOS.
• Disable Notification Storage: Turns off maps that hold references to unread notifications until they've been selected & read. This option is good for debugging in cases where Mattermost is holding onto too many references to unused notifications.
• Disable User Activity Monitor: Turns off the interval that checks whether the user is away or not. This option is good for debugging whether a user's availability status is causing unexpected desktop app behavior.
• Disable Context Menu: Turns off the context menu attached to the BrowserViews. This option is good as a library santity check.
• Force Legacy Messaging API: Forces the app to revert back to the old messaging API instead of the newer contextBridge API. This option is a good santity check to confirm whether the new API is responsible for holding onto memory.
• Force New Messaging API: Forces the app to use the contextBridge API and completely disables the legacy one. This option forces off listeners for the legacy API.
• False: (Default) Developer debugging options are locked and unavailable in the Desktop App.

Redis cache backend

From Mattermost v10.4, Mattermost Enterprise customers with self-hosted deployments can configure Redis (Remote Dictionary Server) as an alternative cache backend. Redis is an open-source, in-memory data structure store that can be used as a database, cache, and message broker. It supports various data structures and is a top choice for its performance because its able to store data in memory and provide very quick data access.

Using Redis as a caching solution can help ensure that Mattermost for enterprise-level deployments with high concurrency and large user bases remains performant and efficient, even under heavy usage.

Configure a Redis cache by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Cache type

Define the cache type. lru: (Default) Mattermost uses the in-memory cache store. redis: Mattermost uses the configured Redis cache store.

System Config path: N/A config.json setting: CacheSettings > CacheType, > lru Environment variable: MM_CACHESETTINGS_CACHETYPE

Redis address

The hostname of the Redis host. String input.

System Config path: N/A config.json setting: CacheSettings > RedisAddress, Environment variable: MM_CACHESETTINGS_REDISADDRESS

Redis password

The password of the Redis host. String input. Leave blank if there is no password.

System Config path: N/A config.json setting: CacheSettings > RedisPassword, Environment variable: MM_CACHESETTINGS_REDISPASSWORD

Redis database

The database of the Redis host. Zero-indexed number up to 15. Typically set to 0. Redis allows a maximum of 16 databases.

System Config path: N/A config.json setting: CacheSettings > RedisDB, Environment variable: MM_CACHESETTINGS_REDISDB

Disable client cache

Disables the client-side cache of Redis. true: Client-side cache of Redis is disabled. Typically used as a test option, and not in production environments. false: (Default) Client-side cache of Redis is enabled.

System Config path: N/A config.json setting: CacheSettings > DisableClientCache, > false Environment variable: MM_CACHESETTINGS_REDISDB

Redis cache prefix

Adds a prefix to all Redis cache keys.

System Config path: N/A config.json setting: CacheSettings > RedisCachePrefix Environment variable: MM_CACHESETTINGS_REDISCACHEPREFIX

Adding a prefix to all Redis cache keys reduces key collisions, simplifies debugging, isolates data, and provides a clear structure for managing and scaling Redis-based systems. In environments where multiple systems or tenants use the same Redis instance, prefixes become critical for maintaining data integrity and operational efficiency.

Enable webhub channel iteration

Control the performance of websocket broadcasting in channels. When enabled, improves websocket broadcasting performance; however, performance may decrease when users join or leave a channel. Not recommended unless you have at least 200,000 concurrent users actively using Mattermost. Disabled by default.

System Config path: N/A config.json setting: ServiceSettings > EnableWebHubChannelIteration, > false Environment variable: MM_SERVICESETTINGS_ENABLEWEBHUBCHANNELITERATION

Enable dedicated export filestore target

Enables the ability to specify an alternate filestore target for Mattermost bulk exports and compliance exports. True: A new ExportFileBackend() is generated under FileSettings using new configuration values for the following configuration settings: ExportDriverName ExportDirectory ExportAmazonS3AccessKeyId ExportAmazonS3SecretAccessKey ExportAmazonS3Bucket ExportAmazonS3PathPrefix ExportAmazonS3Region ExportAmazonS3Endpoint ExportAmazonS3SSL ExportAmazonS3SignV2 ExportAmazonS3SSE ExportAmazonS3Trace ExportAmazonS3RequestTimeoutMilliseconds ExportAmazonS3PresignExpiresSeconds ExportAzureStorageAccount ExportAzureAuthMode ExportAzureAccessKey ExportAzureContainer ExportAzurePathPrefix ExportAzureCloud ExportAzureEndpoint ExportAzureSSL ExportAzureRequestTimeoutMilliseconds ExportAzurePresignExpiresSeconds False: (Default) Standard file storage is used. Standard file storage will also be used when the configuration setting or value is omitted.

System Config path: N/A config.json setting: FileSettings > DedicatedExportStore Environment variable: MM_FILESETTINGS_DEDICATEDEXPORTSTORE

• When an alternate filestore target is configured, Mattermost Cloud admins can generate a presigned download URL for exports using the /exportlink [job-id|zip file|latest] slash command. On Amazon S3 this is an S3 presigned URL; on Azure Blob Storage it's a Shared Access Signature (SAS) URL. The lifetimes of these URLs are controlled, respectively, by ExportAmazonS3PresignExpiresSeconds or ExportAzurePresignExpiresSeconds. See the Mattermost data migration documentation for details. Cloud admins can also use the mmctl export generate-presigned-url command to generate a presigned URL directly from mmctl.
• Generating a presigned URL is only available in Mattermost Cloud, and requires storage that supports presigned links (Amazon S3 or Azure Blob Storage) and this dedicated export store setting to be set to true. Presigned URLs for exports aren't supported for systems with shared storage.