Environment configuration settings

plans-img Available on all plans

deployment-img self-hosted deployments

Tip

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

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

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

The following environment configuration settings are available:

Web server

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Notes:

  • 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 Office 365, will fail.

    • Plugins may not work as expected.

Web server listen address

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Forward port 80 to 443

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Forward insecure traffic from port 80 to port 442.

  • 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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. See the configuring TLS on Mattermost for more details

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.ConnectionSecurity",

  • Environment variable: MM_SERVICESETTINGS_CONNECTIONSECURITY

TLS certificate file

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

String input.

  • System Config path: REnvironment > Web Server

  • config.json setting: ".ServiceSettings.TLSKeyFile",

  • Environment variable: MM_SERVICESETTINGS_TLSKEYFILE

Use Let’s Encrypt

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Enable the automatic retrieval of certificates from Let’s Encrypt. See the configuring TLS on Mattermost documentation for more details on setting up 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

Let’s Encrypt certificate cache file

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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: Reporting > Team Statistics

  • config.json setting: ".ServiceSettings.LetsEncryptCertificateCacheFile",

  • Environment variable: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE

Read timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

  • 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. 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.WriteTimeout: 300",

  • Environment variable: MM_SERVICESETTINGS_WRITETIMEOUT

Idle timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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. Default is 300 seconds.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.IdleTimeout: 300",

  • Environment variable: MM_SERVICESETTINGS_IDLETIMEOUT

Webserver mode

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

We recommend gzip to improve performance unless your environment has specific restrictions, such as a web proxy that distributes gzip files poorly.

  • 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: The Mattermost server will serve static files uncompressed.

  • Disabled: The Mattermost server will not serve static files. based on the TLS Certificate File and TLS Key File specified above.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.WebserverMode: gzip",

  • Environment variable: MM_SERVICESETTINGS_WEBSERVERMODE

Enable insecure outgoing connections

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

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

Managed resource paths

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: 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

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: Purging the caches may adversely impact performance. Deployments using high availability clusters will attempt to purge all the servers in the cluster.

Websocket URL

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

License file location

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The minimum TLS version used by the Mattermost server. on where they should try to connect websockets to.

String input. Default is 1.2.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TLSMinVer: 1.2",

  • Environment variable: MM_SERVICESETTINGS_TLSMINVER

Note: 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Notes:

  • From Mattermost v5.12, new deployments set this value to [], meaning that no header will be trusted. Prior to v5.12, the absence of this configuration setting entry will have it set to ["X-Forwarded-For", "X-Real-Ip"] on upgrade to maintain backwards compatibility.

  • 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)

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

  • 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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. 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Notes:

  • 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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_GOROUTINEHEALTHTHREADHSOLD

Allow cookies for subdomains

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

  • true: (Default) Allows cookies for subdomains by setting the domain parameter on Mattermost cookies.

  • false: Cookies not allowed for subdomains.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.AllowCookiesForSubdomains: true",

  • Environment variable: MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS

Cluster log timeout

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

Define the frequency, in milliseconds, of cluster request time logging for performance monitoring. for performance monitoring

Numerical input. 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.

Database

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The connection string to the master database.

String input.

  • System Config path: N/A

  • config.json setting: ".SqlSettings.DataSource",

  • Environment variable: MM_SQLSETTINGS_DATASOURCE

To enable SSL:

  • Add &tls=true to your database connection string if your SQL driver supports it.

  • Add &tls=skip-verify if you use self-signed certificates.

MySQL databases

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

To specify collation:

"SqlSettings": {
    "DataSource":
"<user:pass>@<servername>/mattermost?charset=utf8mb4,utf8&collation=utf8mb4_general_ci",
    [...]
 }

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

"SqlSettings": {
    "DataSource": "<user:pass>@<servername>/mattermost?charset=utf8mb4,utf8",
    [...]
 }

Note: 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.

PostgreSQL databases

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

Maximum idle database connections

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum number of idle connections held open to the database.

Numerical input. Default is 10.

  • System Config path: Environment > Database

  • config.json setting: ".SqlSettings.MaxIdleConns": 10,

  • Environment variable: MM_SQLSETTINGS_MAXIDLECONNS

Maximum open connections

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum number of idle connections held open to the database.

Numerical input. Default is 300.

  • System Config path: Environment > Database

  • config.json setting: ".SqlSettings.MaxOpenConns": 300,

  • Environment variable: MM_SQLSETTINGS_MAXOPENCONNS

Query timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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 3,600,000 milliseconds (1 hour).

  • System Config path: Environment > Database

  • config.json setting: ".SqlSettings.ConnMaxLifetimeMilliseconds: 3600000",

  • Environment variable: MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS

Maximum connection idle timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

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

SQL statement logging

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

Select the Recycle Database Connections button to reconnect to the configured database. All old connections are closed after 20 seconds.

To fail over without downing 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

Applied schema migrations

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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 menu to review the current database schema version applied to your deployment.

Read replicas

Available in legacy Enterprise Edition E10 and E20

Specifies the connection strings for the read replica databases.

  • System Config path: N/A

  • config.json setting: ".SqlSettings.DataSourceReplicas": []

  • Environment variable: MM_SQLSETTINGS_DATASOURCEREPLICAS

Note: Each database connection string in the array must be in the same form used for the Data source setting.

Search replicas

Available in legacy Enterprise Edition E10 and E20

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

Note: Each database connection string in the array must be in the same form used for the Data source setting.

Replica lag settings

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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 replica 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

Examples:

For AWS Aurora instances, QueryAbsoluteLag can be:

select server_id, highest_lsn_rcvd-durable_lsn as bindiff from aurora_global_db_instance_status() where server_id=<>

And for AWS Aurora instances, QueryTimeLag can be:

select server_id, visibility_lag_in_msec from aurora_global_db_instance_status() where server_id=<>

For MySQL Group Replication, the absolute lag can be measured from the number of pending transactions in the applier queue:

select member_id, count_transactions_remote_in_applier_queue FROM performance_schema.replication_group_member_stats where member_id=<>

Elasticsearch

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

Configure the Elasticsearch environment in which Mattermost is deployed by going to System Console > Environment > Elasticsearch, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Enable Elasticsearch indexing

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to index new posts automatically.

  • true: Indexing of new posts occurs automatically.

  • false: (Default) Elasticsearch indexing is disabled and new posts are not indexed.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableIndexing: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING

Notes:

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

  • Search queries will use database search until Elasticsearch for search queries is enabled.

Server connection address

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The address of the Elasticsearch server.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.ConnectionUrl",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL

Skip TLS verification

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The certificate step for TLS connections can be skipped.

  • true: Skips the certificate verification step for TLS connections.

  • false: (Default) Mattermost does not skip certificate verification.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.SkipTLSVerification: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION

Server username

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

String input.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.UserName",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERNAME

Server password

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

String input.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.Password",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_PASSWORD

Enable cluster sniffing

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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 .

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.Sniff: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_SNIFF

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

Bulk indexing

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to start a bulk index of all existing posts in the database.

  • System Config path: Environment > Elasticsearch

  • config.json setting: N/A

  • Environment variable: N/A

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

Purge indexes

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to purge the entire Elasticsearch index. Typically only used if the index has corrupted and search isn’t behaving as expected.

  • 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.

Enable Elasticsearch for search queries

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to use Elasticsearch for all search queries using the latest index

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

  • false: (Default) Database search is used for search queries.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableSearching: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING

Enable Elasticsearch for autocomplete queries

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to use Elasticsearch for all autocompletion queries on users and channels using the latest index.

  • true: Elasticsearch will be used for all autocompletion queries on users and channels using the latest index.

  • false: (Default) Database autocomplete is used.

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.EnableAutocomplete: false",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE

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

Post index replicas

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each post index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.PostIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS

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

Post index shards

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each post index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.PostIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS

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

Channel index replicas

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each channel index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.ChannelIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS

Channel index shards

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each channel index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.ChannelIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS

User index replicas

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of replicas to use for each user index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.UserIndexReplicas: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS

User index shards

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of shards to use for each user index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.UserIndexShards: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS

Aggregate search indexes

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Numerical input. Default is 365 days.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.AggregatePostsAfterDays: 365",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS

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

Post aggregator start time

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The prefix added to the Elasticsearch index name.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.IndexPrefix",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_INDEXPREFIX

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

Live indexing batch size

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The number of new posts batched together before they’re added to the Elasticsearch index.

Numerical input. Default is 1.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.LiveIndexingBatchSize: 1",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE

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

Bulk indexing time window

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum time window, in seconds, for a batch of posts being indexed by the Bulk Indexer. This setting serves as a performance optimization for installs with over

~10 million posts in the database.

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

  • System Config path: Environment > Elasticsearch

  • config.json setting: ".Elasticsearchsettings.BulkIndexingTimeWindowSeconds: 3600",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_BULKINDEXINGTIMEWINDOWSECONDS

Note: Setting this value too low will cause bulk indexing jobs to run slowly.

Request timeout

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The timeout, in seconds, for Elasticsearch calls.

Numerical input in seconds. Default is 30 seconds.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.RequestTimeoutSeconds :30",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS

Trace

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Options for printing Elasticsearch trace errors.

  • error: Creates the error trace when initializing the Elasticsearch client and prints any template creation or search query that returns an error as part of the error message.

  • all: Creates the three traces (error, trace and info) for the driver and doesn’t print the queries because they will be part of the trace log level of the driver.

  • not specified: (Default) No error trace is created.

  • System Config path: N/A

  • config.json setting: ".Elasticsearchsettings.Trace",

  • Environment variable: MM_ELASTICSEARCHSETTINGS_TRACE

File storage

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 currently supports storing files on the local filesystem and Amazon S3 or S3-compatible containers. We have tested Mattermost with MinIO and Digital Ocean Spaces products, 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.

File storage system

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The type of file storage system used. Can be either Local File System or Amazon S3.

  • 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 MinIO (beta) and Digital Ocean Spaces.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.DriverName:  local”,

  • Environment variable: MM_FILESETTINGS_DRIVERNAME

Local storage directory

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

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

Maximum file size

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum file size for message attachments. This value must be specified in megabytes in the System Console, and in bytes in the config.json file.

The default is 1048576 bytes (1 megabyte).

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.MaxFileSize: 104857600",

  • Environment variable: MM_FILESETTINGS_MAXFILESIZE

Warning: Verify server memory can support your setting choice. Large file sizes increase the risk of server crashes and failed uploads due to network disruptions.

Note: 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: 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 CLI or 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, HTML, and PAGES:

  • tidy: Used to search the contents of HTML and PAGES documents.

  • wv: Used to search the contents of DOC documents.

  • popplerutils: Used to significantly improve server performance when extracting the contents of PDF documents.

  • unrtf: Used to search the contents of RTF documents.

  • Justtext: Used to search HTML documents.

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: Document content search within ZIP files is available in Mattermost Server from v5.35, with mobile support coming soon. Searching document contents adds load to your server. 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: For MinIO or Digital Ocean Spaces, leave this setting empty.

Amazon S3 access key ID

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

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

Amazon S3 endpoint

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

Note: 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Not available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Enable Amazon S3 debugging

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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.

Initial Font

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

An image proxy is 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

An image proxy anonymizes Mattermost app connections and prevents them from accessing insecure content.

  • true: (Default) Enables an image proxy for loading external images.

  • false: 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The type of image proxy used by Mattermost.

  • local: (Default) The Mattermost server itself acts as the image proxy.

  • atmos/camo: An external atmos/camo image proxy is used.

  • 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.

Remote image proxy URL

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The URL of the atmos/camo proxy. This setting isn’t needed when using the local image proxy.

  • System Config path: Environment > Image Proxy

  • config.json setting: ".ImageProxySettings.RemoteImageProxyURL",

  • Environment variable: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYURL

Remote image proxy options

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The URL signing key passed to an atmos/camo image proxy. This setting isn’t needed when using the local image proxy type.

  • System Config path: Environment > Image Proxy

  • config.json setting: ".ImageProxySettings.RemoteImageProxyOptions",

  • Environment variable: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS

See the image proxy documentation to learn more.

SMTP

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The port of SMTP email server.

Numerical input.

  • System Config path: Environment > SMTP

  • config.json setting: ".EmailSettings.SMTPPort",

  • Environment variable: MM_EMAILSETTINGS_SMTPPORT

Enable SMTP authentication

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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: ".EmailSettings.EnableSecurityFixAlert": true",

  • Environment variable: MM_EMAILSETTINGS_ENABLESECURITYFIXALERT

See the Telemetry documentation to learn more.

SMTP server timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum amount of time, in seconds, allowed for establishing a TCP connection between Mattermost and the SMTP server to be idle before being terminated.

Numerical value in seconds.

  • System Config path: Environment > SMTP

  • config.json setting: ".EmailSettings.SMTPServerTimeout",

  • Environment variable: MM_EMAILSETTINGS_SMTPSERVERTIMEOUT

Push notification server

Configure Mattermost to enable push notifications to Mattermost clients by going to System Console > Environment > Push Notification Server, 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 push notifications

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Enable or disable Mattermost push notifications.

  • true: (Default) Your Mattermost server sends mobile push notifications to the server specified.

  • false: Mobile push notifications are disabled.

  • System Config path: Environment > Push Notification Server

  • config.json setting: ".EmailSettings.SendPushNotifications": true",

  • Environment variable: MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS

Push notification server location

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The location of Mattermost Push Notification Service (MPNS), which re-sends push notifications from Mattermost to services like Apple Push Notification Service (APNS) and Google Cloud Messaging (GCM).

  • Customers running a Professional or Enterprise Edition workspace should enter https://push.mattermost.com for the push notification server hosted in the United States.

  • If you prefer to use a push notification server hosted in Germany, enter https://hpns-de.mattermost.com/.

  • Team Edition customers should enter https://push-test.mattermost.com.

  • System Config path: Environment > Push Notification Server

  • config.json setting: ".EmailSettings.PushNotificationServer",

  • Environment variable: MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER

Notes:

  • The TPNS is provided for testing push notifications prior to compiling your own service. Ensure you’re familiar with its limitations. Review the mobile push notifications and mobile apps documentation, including guidance on compiling your own mobile apps and MPNS, before deploying to production.

  • To confirm push notifications are working, connect to the Mattermost iOS App available on the App Store, or the Mattermost Android App available on Google Play.

Maximum notifications per channel

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum total number of users in a channel before @all, @here, and @channel no longer send desktop, email, or mobile push notifications to maximize performance.

Numerical input. Default is 1000.

  • System Config path: Environment > Push Notification Server

  • config.json setting: ".TeamSettings.MaxNotificationsPerChannel: 1000",

  • Environment variable: MM_EMAILSETTINGS_MAXNOTIFICATIONSPERCHANNEL

Note: We recommend increasing this value a little at a time, monitoring system health by tracking performance monitoring metrics, and only increasing this value if large channels have restricted permissions controlling who can post to the channel, such as a read-only Town Square channel.

High availability

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

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

Enable high availability mode

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

You can enable high availability mode.

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_ENABLE

Cluster name

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_CLUSTERNAME

Override hostname

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

You can override the hostname of this server.

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME

See the high availability cluster documentation for details.

Use IP address

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_USEIPADDRESS

Use gossip

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

All cluster traffic uses the gossip protocol.

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_USEEXPERIMENTALGOSSIP

Notes:

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

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

Enable experimental gossip encryption

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_ENABLEEXPERIMENTALGOSSIPENCRYPTION

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

Enable gossip compression

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

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

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_ENABLE GOSSIPCOMPRESSION

Gossip port

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Numerical input. Default is 8074.

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_GOSSIPPORT

Streaming port

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

The port used for streaming data between servers.

Numerical input. Default is 8075.

  • System Config path: Environment > High Availability

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

  • Environment variable: MM_CLUSTERSETTINGS_STREAMINGPORT

Read only config

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_READONLYCONFIG

Network interface

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

String input.

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_NETWORKINTERFACE

Bind address

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

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

String input.

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_BINDADDRESS

Maximum idle connections for high availability

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Numerical input. Default is 100.

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNS

Maximum idle connections per host

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Numerical input. Default is 128.

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_MAXIDLECONNSPERHOST

Idle connection timeout

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Numerical input. Default is 90000.

  • System Config path: N/A

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

  • Environment variable: MM_CLUSTERSETTINGS_IDLECONNTIMEOUTMILLISECONDS

Rate limiting

Rate limiting prevents your Mattermost server from being overloaded with too many requests, and decreases the risk and impact of third-party applications or malicious attacks on your server. Configure rate limiting settings by going to System Console > Environment > Rate Limiting, 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 rate limiting

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Enable or disable rate limiting to throttle APIs to a specified number of requests per second.

  • true: APIs are throttled at the rate specified by the Maximum queries per second configuration setting.

  • false: (Default) API access isn’t throttled.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.Eanble: false”,

  • Environment variable: MM_RATELIMITSETTINGS_ENABLE

Maximum queries per second

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Throttle the API at this number of requests per second when rate limiting is enabled.

Numerical input. Default is 10.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.PerSec: 10,

  • Environment variable: MM_RATELIMITSETTINGS_PERSEC

Maximum burst size

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum number of requests allowed beyond the per second query limit when rate limiting is enabled.

Numerical input. Default is 100.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.MaxBurst: 100,

  • Environment variable: MM_RATELIMITSETTINGS_MAXBURST

Memory store size

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The maximum number of user sessions connected to the system as determined by vary rate limit settings when rate limiting is enabled.

Numerical input. Default is 10000. Typically set to the number of users in the system.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.MemoryStoreSize: 10000,

  • Environment variable: MM_RATELIMITSETTINGS_MEMORYSTORESIZE

Vary rate limit by remote address

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to rate limit API access by IP address when rate limiting is enabled.

  • true: (Default) Rate limit API access by IP address. Recommended when using a proxy.

  • false: Rate limiting does not vary by IP address.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.VaryByRemoteAddr: true,

  • Environment variable: MM_RATELIMITSETTINGS_VARYBYREMOTEADDR

Vary rate limit by user

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to rate limit API access by authentication token or not when rate limiting is enabled.

  • true: Rate limit API access by user authentication token. Recommended when using a proxy.

  • false: (Default) Rate limiting does not vary by user authentication token.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.VaryByUser: false,

  • Environment variable: MM_RATELIMITSETTINGS_VARYBYUSER

Vary rate limit by HTTP header

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to vary rate limiting API access by the HTTP header field specified. Recommended when you’re using a proxy.

  • When configuring NGINX, set this to X-Real-IP.

  • When configuring AmazonELB, set this to X-Forwarded-For.

  • System Config path: Environment > Rate Limiting

  • config.json setting: ".RateLimitSettings.VaryByHeader: "",

  • Environment variable: MM_RATELIMITSETTINGS_VARYBYHEADER

Logging

Configure 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to output 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

Console log level

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The level of detail in 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.

  • System Config path: Environment > Logging

  • config.json setting: ".LogSettings.ConsoleLevel": DEBUG",

  • Environment variable: MM_LOGSETTINGS_CONSOLELEVEL

Output console logs as JSON

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to output console logs as JSON.

  • true: (Default) Logged events are written in a machine-readable JSON format. Typically set to true in production.

  • false: Logged events are written in plain text.

  • System Config path: Environment > Logging

  • config.json setting: ".LogSettings.ConsoleJson": true",

  • Environment variable: MM_LOGSETTINGS_CONSOLEJSON

Output logs to file

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to output 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. Typically set to true in production.

  • 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

File log level

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The level of detail in 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.

  • System Config path: Environment > Logging

  • config.json setting: ".LogSettings.FileLevel": INFO",

  • Environment variable: MM_LOGSETTINGS_FILELEVEL

Output file logs as JSON

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to output file logs as JSON.

  • true: (Default) Logged events are written in a machine-readable JSON format. Typically set to true in production.

  • false: Logged events are written in plain text.

  • System Config path: Environment > Logging

  • config.json setting: ".LogSettings.FileJson": true",

  • Environment variable: MM_LOGSETTINGS_FILEJSON

File log directory

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

The location of the 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

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

Enable webhook debugging

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to capture the contents of incoming webhooks to log files 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 diagnostics and error reporting

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send log records to multiple targets.

  • System Config path: Environment > Logging

  • config.json setting: ".LogSettings.AdvancedLoggingConfig": "",

  • Environment variable: MM_LOGSETTINGS_ADVANCEDLOGGINGCONFIG

Output logs to multiple targets

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send 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.AdvancedLoggingConfig": "",

  • Environment variable: MM_LOGSETTINGS_ADVANCEDLOGGINGCONFIG

Notes:

  • 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.

See the audit log v2 documentation for additional information.

Session lengths

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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_EXTENDSESSONLENGTHWITHACTIVITY

Session length for AD/LDAP and email

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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_SESSONLENGTHWEBINHOURS

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

Session length for mobile

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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. Default is 720 hours.

  • System Config path: Environment > Session Lengths

  • config.json setting: ".ServiceSettings.SessionLengthMobileInHours: 720,

  • Environment variable: MM_SERVICESETTINGS_SESSONLENGTHMOBILEINHOURS

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

Session length for SSO

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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. Default is 720 hours. Numbers as decimals are also valid values for this configuration setting.

  • System Config path: Environment > Session Lengths

  • config.json setting: ".ServiceSettings.SessionLengthSSOInHours: 720,

  • Environment variable: MM_SERVICESETTINGS_SESSONLENGTHSSOINHOURS

Notes:

  • 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Set the number of minutes to cache a session in memory.

Numerical input in minutes. Default is 10 minutes.

  • System Config path: Environment > Session Lengths

  • config.json setting: ".ServiceSettings.SessionCacheInMinutes: 10,

  • Environment variable: MM_SERVICESETTINGS_SESSONCACHEINMINUTES

Session idle timeout

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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_SESSONIDLETIMEOUTINMINUTES

Notes:

Performance monitoring

Configure performance monitoring by going to System Console > Environment > Performance Monitoring, 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 performance monitoring

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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.

Listen address for performance

plans-img Available on Enterprise plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E20

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

Developer

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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Enable or disable the /test slash command.

  • true: (Default) The /test slash command is enabled to load test accounts and test data.

  • 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

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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 performance debugging

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

Enable or disable the /test slash command.

  • true: (Default) The /test slash command is enabled to load test accounts and test data.

  • false: The /test slash command is disabled.

  • System Config path: Environment > Developer

  • config.json setting: ".ServiceSettings.EnableDeveloper": false",

  • Environment variable: MM_SERVICESETTINGS_ENABLEDEVELOPER

See the performance debugging documentation to learn more.

Allow untrusted internal connections

plans-img Available on all plans

deployment-img self-hosted deployments

Available in legacy Enterprise Edition E10/E20

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_ALLOWUNTRUSTEDINTERNALCONNECTIONS

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.

Warning: 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.

Notes:

  • 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.