Environment configuration settings#

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.

Both self-hosted and Cloud admins can access the following configuration settings in System Console > Environment. Self-hosted admins can also edit the config.json file as described in the following tables.

Web server#

Available on all plans

self-hosted deployments

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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 Entra ID, will fail.
- Plugins may not work as expected.

Maximum URL length#

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

Numeric value. Default is 2048 characters.

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

Web server listen address#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Forward insecure traffic from port 80 to port 443.

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

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

Web server connection security#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

String input.

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

Use Let’s Encrypt#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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: Environment > Web Server
config.json setting: ".ServiceSettings.LetsEncryptCertificateCacheFile",
Environment variable: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE

Read timeout#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

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

Enable insecure outgoing connections#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Note

Available only on Enterprise plans

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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. high availability cluster-based deployments will attempt to purge all the servers in the cluster

Websocket URL#

Also available in legacy Mattermost Enterprise Edition E10 or 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

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

License file location#

Note

Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The minimum TLS version used by the Mattermost server.

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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:

The default value of [] means 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)#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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_GOROUTINEHEALTHTHRESHOLD

Allow cookies for subdomains#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Note

Available only on Enterprise plans

Also available in legacy Mattermost Enterprise Edition E20

Define the frequency, in milliseconds, of cluster request time logging 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.

Maximum payload size#

The maximum payload size in bytes for all APIs except APIs that receive a file as an input.

For example, the upload attachment API or the API to upload a custom emoji.

Numerical value. Default is 300000 (300 kB).

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

Database#

Available on all plans

self-hosted deployments

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.

Mattermost Academy Learn about setting up the Mattermost database

Driver name#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

PostgreSQL databases

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

To use TLS with PostgreSQL databases

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

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

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

MySQL databases

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

To specify collation:

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

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

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

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.

To use TLS with MySQL databases

The parameter to encrypt connection against a MySQL server is tls. The library used to interact with MySQL is Go-MySQL-Driver. For the moment, it’s not possible to use all the values that you could pass to a standard MySQL Client mysql --ssl-mode=value. See Connection-Encryption Option Summary documentation for a version 8.0 example.

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

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

AWS High Availablity RDS cluster deployments

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

Maximum open connections#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The maximum number of open connections to the database.

Numerical input. Default is 300 for self-hosted deployments, and 100 for Cloud deployments.

System Config path: Environment > Database
config.json setting: ".SqlSettings.MaxOpenConns": 300,
Environment variable: MM_SQLSETTINGS_MAXOPENCONNS

Query timeout#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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 3600000 milliseconds (1 hour).

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

Maximum connection idle timeout#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Note

Available only on Enterprise plans

Also available in legacy Mattermost Enterprise Edition E20

Select the Recycle Database Connections button to manually recycle the connection pool by closing the current set of open connections to the database within 20 seconds, and then creating a new set of connections.

To fail over without stopping the server, change the database line in the config.json file, select Reload Configuration from Disk via Environment > Web Server, then select Recycle Database Connections.

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

Disable database search#

Also available in legacy Mattermost Enterprise Edition E10 or E20

When other search engines are configured, such as Elasticsearch, the database can be disabled to perform searches.

true: Disables the use of the database to perform searches. If another search engine isn’t configured, setting this value to true will result in empty search results.
false: (Default) Database search isn’t disabled.

System Config path: Environment > Database
config.json setting: ".SqlSettings.DisableDatabaseSearch: false",
Environment variable: MM_SQLSETTINGS_DISABLEDATABASESEARCH

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

When Elasticsearch is enabled, Mattermost will try to use it first.
If Elasticsearch fails or is disabled, Mattermost will attempt to use Bleve, if enabled. If this occurs, you will see the warning Encountered error on SearchPostsInTeamForUser.
If both Elasticsearch and Bleve fail or are disabled, Mattermost tries to search the database directly, if this is enabled.
If all of the above methods fail or are disabled, the search results will be empty.

Applied schema migrations#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

Active Search Backend#

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

Read replicas#

Note

Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E10 or 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.

AWS High Availablity RDS cluster deployments

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

Search replicas#

Note

Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E10 or 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.

AWS High Availablity RDS cluster deployments

Replica lag settings#

Note

Available only on Enterprise plans

Also available in legacy Mattermost 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 database instance.
QueryAbsoluteLag: A plain SQL query that must return a single row. The first column must be the node value of the Prometheus metric, and the second column must be the value of the lag used to measure absolute lag.
QueryTimeLag: A plain SQL query that must return a single row. The first column must be the node value of the Prometheus metric, and the second column must be the value of the lag used to measure the time lag.

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

Notes:

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

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

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

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

Example:
{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "replica-1",
            "QueryAbsoluteLag": "select server_id, highest_lsn_rcvd-durable_lsn as bindiff from aurora_global_db_instance_status() where server_id=<>",
            "QueryTimeLag": "select server_id, visibility_lag_in_msec from aurora_global_db_instance_status() where server_id=<>"
        }
      ]
  }
}
MySQL Group Replication
Add the configuration highlighted below to your SqlSettings.ReplicaLagSettings array. You only need to add this once because replication statistics for all nodes are shared across all server instances that are members of the MySQL replication group. Be sure to change the DataSource to point to a single node in the group.

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

Example:
{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "replica-1",
            "QueryAbsoluteLag": "select member_id, count_transactions_remote_in_applier_queue FROM performance_schema.replication_group_member_stats where member_id=<>",
            "QueryTimeLag": ""
        }
      ]
  }
}
PostgreSQL replication slots
Add the configuration highlighted below to your SqlSettings.ReplicaLagSettings array. This query should run against the primary node in your cluster, to do this change the DataSource to match the SqlSettings.DataSource setting you have configured.

For more information on pg_stat_replication, see the PostgreSQL documentation.
Example:
{
  "SqlSettings": {
      "ReplicaLagSettings": [
        {
            "DataSource": "postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10.",
            "QueryAbsoluteLag": "select usename, pg_wal_lsn_diff(pg_current_wal_lsn(),replay_lsn) as metric from pg_stat_replication;",
            "QueryTimeLag": ""
        }
      ]
  }
}
Grant permissions to the database user for pg_monitor. This user should be the same user configured above in the DataSource string.
For more information on roles, see the PostgreSQL documentation.
sudo -u postgres psql
postgres=# GRANT pg_monitor TO mmuser;

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

mattermost_db_replica_lag_abs{instance=~"$server"}

A screenshot showing how to clone a chart within Grafana

A screenshot showing the specific edits to make to the cloned grafana chart.

Replica monitor interval (seconds)#

Available on all plans

self-hosted deployments

Specifies how frequently unhealthy replicas will be monitored for liveness check. Mattermost will dynamically choose a replica if it’s alive.

Numerical input. Default is 5 seconds.

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

Elasticsearch#

Available on Enterprise plans

self-hosted deployments

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

You can configure the Elasticsearch environment in which Mattermost is deployed in System Console > Environment > Elasticsearch. You can also edit the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Enable Elasticsearch indexing#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Configure Mattermost to index new posts automatically.

true: Indexing of new messages occurs automatically.
false: (Default) Elasticsearch indexing is disabled and new messages aren’t indexed.

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

Notes:

Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that scale, enabling Elasticsearch for search queries is highly recommended
If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for optimum search performance before reaching 3 million posts.
For deployments with over 3 million posts, Elasticsearch is required to avoid significant performance issues, such as timeouts, with message searches and @mentions.
If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results.

Backend type#

The type of search backend.

elasticsearch - (Default)
opensearch - Required for AWS Opensearch customers.

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

Important

Mattermost v9.11 introduces support for Elasticsearch v8 and beta support for Opensearch v1.x and v2.x.

Mattermost supports Elasticsearch v7.17+. However, we recommend upgrading your Elasticsearch v7 instance to v8.x. See the Elasticsearch upgrade documentation for details.
Customers using Elasticsearch v8 must set action.destructive_requires_name to false in elasticsearch.yml to enable wildcard operations.

AWS Elasticsearch Customers

The official AWS Elasticsearch v8 client only works from Elasticsearch v7.11 and later. This is a breaking change for customers using AWS Elasticsearch v7.10.x. If you’re using AWS Elasticsearch, you must upgrade to AWS Opensearch. See the AWS Amazon Opensearch upgrade documentation for details.

If you’re using AWS Elasticsearch, you must:

Upgrade to AWS Opensearch for future compatibility. Refer to the Opensearch upgrade documentation for details.

Disable “compatibility mode” in Opensearch.

Upgrade the Mattermost server.

Change the default ElasticsearchSettings.Backend configuration value from elasticsearch to opensearch using mmctl config set, or by editing the config.json file manually. This value cannot be changed using the System Console. See the Mattermost Elasticsearch backend type documentation for additional details.

Restart the Mattermost server.

Server connection address#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The address of the Elasticsearch server.

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

CA path#

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

System Config path: Environment > Elasticsearch
config.json setting: ".Elasticsearchsettings.CA",
Environment variable: MM_ELASTICSEARCHSETTINGS_CA

Note

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

Client certificate path#

Optional client certificate for the connection to the Elasticsearch server in the PEM format.	System Config path: Environment > Elasticsearch `config.json` setting: `".Elasticsearchsettings.ClientCert",` Environment variable: `MM_ELASTICSEARCHSETTINGS_CLIENTCERT`
Note: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Client certificate key path#

Optional key for the client certificate in the PEM format.	System Config path: Environment > Elasticsearch `config.json` setting: `".Elasticsearchsettings.ClientKey",` Environment variable: `MM_ELASTICSEARCHSETTINGS_CLIENTKEY`
Note: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.

Skip TLS verification#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

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

Notes:

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

Rebuild channels index#

Purge the channels index adn re-index all channels in the database, from oldest to newest.	System Config path: Environment > Elasticsearch `config.json` setting: N/A Environment variable: N/A
Select the Rebuild Channels Index button in the System Console to purge the channels index. Ensure no other indexing jobs are in progress via the Bulk Indexing table before starting this process. During indexing, channel auto-complete is available, but search results may be incomplete until the indexing job is complete.

Purge indexes#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Purge the entire Elasticsearch index.	System Config path: Environment > Elasticsearch `config.json` setting: N/A Environment variable: N/A
Select the Purge Indexes button in the System Console to purge the index. After purging the index, create a new index by selecting the Index Now button.

Indexes to skip while purging#

Specify index names to ignore while purging indexes. Separate multiple index names with commas.

Use an asterisk (*) to match a sequence of index name characters.

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

Enable Elasticsearch for search queries#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Important

Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that scale, enabling Elasticsearch for search queries is highly recommended.
If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for optimum search performance before reaching 3 million posts.
For deployments with over 3 million posts, Elasticsearch with dedicated indexing and scaled usage resourcing through cluster support is required to avoid significant performance issues, such as timeouts, with message searches and @mentions.

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

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

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

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

Enable Elasticsearch for autocomplete queries#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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 notes:

If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.
If there are n data nodes, the number of replicas per shard for each index should be n-1.
If the number of nodes in an Elasticsearch cluster changes, this configuration setting, as well as Channel Index Replicas and User Index Replicas must also be updated accordingly.

Post index shards#

Also available in legacy Mattermost Enterprise Edition E10 or 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 configuration setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, purge and rebuild the index after changing this setting.

Channel index replicas#

Also available in legacy Mattermost Enterprise Edition E10 or 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

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

Channel index shards#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

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

User index shards#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The number of new posts needed before those posts are added to the Elasticsearch index. Once added to the Index, the post becomes searchable.

On servers with more than 1 post per second, we suggest setting this value to the average number of posts over a 20 second period of time.

Numerical input. Default is 1. Every post is indexed synchronously as they are created.

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

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

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

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

How to find the right number for your server

You must understand how many posts your server makes every minute. Run the query below to calculate your server’s average posts per minute.
Note that this query can be heavy, so we recommend that you run it during non-peak hours. Additionally, you can adjust the WHERE clause to see the posts per minute over a different time period. Right now 31536000000 represents the number of milliseconds in a year.
SELECT AVG(postsPerMinute) as averagePostsPerMinute FROM ( SELECT count(*) as postsPerMinute, date_trunc('minute', to_timestamp(createat/1000)) FROM posts WHERE createAt > ( (extract(epoch from now()) * 1000 ) - 31536000000) GROUP BY date_trunc('minute', to_timestamp(createat/1000)) ) as ppm;
Decide the acceptable index window for your environment, and divide your average posts per minute by that. We suggest 10-20 seconds. Assuming you have 600 posts per minute on average, and you want to index every 20 seconds (60 seconds / 20 seconds = 3`) you would calculate 600 / 3 to come to the number 200. After 200 posts, Mattermost will index the posts into Elasticsearch. So, on average, there would be a 20-second delay in searchability.

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

In the ``config.json``

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

Via mmctl

mmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200

Via an environment variable

MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200

Restart the Mattermost server.

Batch size#

The number of posts for a single batch during a bulk indexing job.

Numerical input. Default is 10000.

System Config path: N/A
config.json setting: ".Elasticsearchsettings.BatchSize :10000",
Environment variable: MM_ELASTICSEARCHSETTINGS_BATCHSIZE

Request timeout#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Available on all plans

self-hosted deployments

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 Academy Learn about file storage

Note

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

The default is 104857600 bytes (100 mebibytes).

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

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.

Notes:

When uploading plugin files, a Received invlaid response from the server error typically indicates that MaxFileSize isn’t large enough to support the plugin file upload, and/or that proxy settings may not be sufficient.
If you use a proxy or load balancer in front of Mattermost, the following proxy settings must be adjusted accordingly:

For NGINX, use client_max_body_size.

For Apache use LimitRequestBody.

Enable document search by content#

Also available in legacy Mattermost Enterprise Edition E10 or 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 mmctl. If this command is not run, users can search older files based on file name only.

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

tidy: Used to search the contents of HTML documents.
wv: Used to search the contents of DOC documents.
popplerutils: Used to significantly improve server performance when extracting the contents of PDF documents.
unrtf: Used to search the contents of RTF documents.
JusText: Used to search HTML documents.

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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, 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Not available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

Amazon S3 request timeout#

The amount of time, in milliseconds, before requests to Amazon S3 storage time out.

Default is 30000 (30 seconds).

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

Amazon S3 upload part size#

The size, in bytes, of each part in a multi-part upload to Amazon S3.

Numeric value. Default is 5242880 (5MB).

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

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

Amazon S3 exported upload part size#

The size, in bytes, of each part in a multi-part exported to Amazon S3.

Numeric value. Default is 104857600 (100MB).

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

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

Initial font#

Also available in legacy Mattermost Enterprise Edition E10 or 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

Amazon S3 request timeout#

The amount of time, in milliseconds, before requests to Amazon S3 storage time out.

Default is 30000 (30 seconds).

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

Image proxy#

Available on all plans

self-hosted deployments

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Available on all plans

self-hosted deployments

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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: ".ServiceSettings.EnableSecurityFixAlert": true",
Environment variable: MM_SERVICESETTINGS_ENABLESECURITYFIXALERT

See the Telemetry documentation to learn more.

SMTP server timeout#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

Numerical value in seconds.

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

Push notification server#

Available on all plans

self-hosted deployments

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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable or disable Mattermost push notifications.

Do not send push notifications: Mobile push notifications are disabled.
Use HPNS connection with uptime SLA to send notifications to iOS and Android apps: (Default) Use Mattermost’s hosted push notification service.
Use TPNS connection to send notifications to iOS and Android apps: Use Mattermost’s test push notification service.
Manually enter Push Notification Service location: When building your own custom mobile apps, you must host your own mobile push proxy service, and specify that URL in the Push Notification Server field.

System Config path: Environment > Push Notification Server
config.json setting: ".EmailSettings.SendPushNotifications": true",
Environment variable: MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS

Notes:

Mattermost Enterprise, Professional, and Cloud customers can use Mattermost’s SLA-bound Hosted Push Notification Service (HPNS) in one of two locations, including the United States and Germany. Mattermost Team Edition customers can use Mattermost’s Test Push Notification server (TPNS).
The TPNS is provided for testing push notifications prior to compiling your own service, and isn’t available for Mattermost Cloud deployments. 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.
See the documentation for details on hosting your own push proxy service.
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.

Push notification server location#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The physical location of the Mattermost Hosted Push Notification Service (HPNS) server.

Select from US (Default) or Germany to automatically populate the Push Notification Server field server URL.

System Config path: Environment > Push Notification Server
config.json setting: ".EmailSettings.PushNotificationServer",
Environment variable: MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER

Maximum notifications per channel#

Also available in legacy Mattermost Enterprise Edition E10 or 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 channel.

High availability#

Available on Enterprise plans

self-hosted deployments

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

In a Mattermost high availability cluster-based 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 cluster-based environment, you can disable ClusterSettings.ReadOnlyConfig in the config.json file by setting it to false. This allows changes applied using the System Console to be saved back to the configuration file.

Enable high availability mode#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E20

The cluster to join by name in a high availability cluster-based deployment.

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

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.ClusterName",
Environment variable: MM_CLUSTERSETTINGS_CLUSTERNAME

Override hostname#

Also available in legacy Mattermost 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-based deployment documentation for details.

Use IP address#

Also available in legacy Mattermost Enterprise Edition E20

You can configure your high availability cluster-based deployment to communicate using the hostname instead of the IP address.

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

System Config path: Environment > High Availability
config.json setting: ".ClusterSettings.UseIPAddress: true",
Environment variable: MM_CLUSTERSETTINGS_USEIPADDRESS

Enable experimental gossip encryption#

Also available in legacy Mattermost Enterprise Edition E20

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

true: (Default for Cloud deployments) All communication through the cluster using the gossip protocol will be encrypted.
false: (Default for self-hosted deployments) All communication using gossip protocol remains unchanged. 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#

Also available in legacy Mattermost Enterprise Edition E20

We recommend that you disable this configuration setting for better performance.

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

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

Gossip port#

Also available in legacy Mattermost 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

Read only config#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E20

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

String input.

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

Bind address#

Also available in legacy Mattermost 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

Advertise address#

Also available in legacy Mattermost Enterprise Edition E20

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

String input.

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

Rate limiting#

Available on all plans

self-hosted deployments

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.

Important

Mattermost rate limiting configuration settings are intended for small deployments of Mattermost up to a few hundred users, and is not intended for larger, Enterprise-scale deployments.

Enable rate limiting#

Also available in legacy Mattermost Enterprise Edition E10 or 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.Enable: false”,
Environment variable: MM_RATELIMITSETTINGS_ENABLE

Maximum queries per second#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

Numerical input. Default is 10.

Increase this value to accept more requests each second, and decrease this value to allow fewer requests.

System Config path: Environment > Rate Limiting
config.json setting: ".RateLimitSettings.PerSec: 10,
Environment variable: MM_RATELIMITSETTINGS_PERSEC

Maximum burst size#

Also available in legacy Mattermost Enterprise Edition E10 or E20

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

Numerical input. Default is 100.

Increase this value to allow for more concurrent requests to be handled, and decrease this value to limit this capacity.

System Config path: Environment > Rate Limiting
config.json setting: ".RateLimitSettings.MaxBurst: 100,
Environment variable: MM_RATELIMITSETTINGS_MAXBURST

Memory store size#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

We recommend setting this value to the expected number of users. A higher value may result in underutilized resources, and a lower value may result in user sessions/tokens expiring too frequently.

System Config path: Environment > Rate Limiting
config.json setting: ".RateLimitSettings.MemoryStoreSize: 10000,
Environment variable: MM_RATELIMITSETTINGS_MEMORYSTORESIZE

Vary rate limit by remote address#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Available on all plans

self-hosted deployments

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.

Tip

You can manage additional logging configuration within the config.json file specifically for Mattermost notifications under NotificationLogSettings. These settings are equivalent to the configuration settings available under LogSettings.

Output logs to console#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Configure Mattermost to output console logs as JSON.

true: (Default) Logged events are written in a machine-readable JSON format.
false: Logged events are written in plain text.

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

Note: Typically set to true in a production environment.

Colorize plain text console logs#

Enables system admins to display plain text log level details in color.

true: When logged events are output to the console as plain text, colorize log levels details.
false: (Default) Plain text log details aren’t colorized in the console.

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

Output logs to file#

Also available in legacy Mattermost Enterprise Edition E10 or 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.
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

Note: Typically set to true in a production environment. When enabled, you can download the mattermost.log file locally by going to System Console > Reporting > Server Logs, and selecting Download Logs.

File log directory#

Also available in legacy Mattermost Enterprise Edition E10 or 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.

File log level#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Configure Mattermost to output file logs as JSON.

true: (Default) Logged events are written in a machine-readable JSON format.
false: Logged events are written in plain text.

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

Note: Typically set to true in a production environment.

Enable webhook debugging#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Configure Mattermost to capture the contents of incoming webhooks to console and/or file logs for debugging.

true: (Default) The contents of incoming webhooks are printed to log files for debugging.
false: The contents of incoming webhooks aren’t printed to log files.

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

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

Output logs to multiple targets#

Also available in legacy Mattermost Enterprise Edition E10 or 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.AdvancedLoggingJSON":: "",
Environment variable: MM_LOGSETTINGS_ADVANCEDLOGGINGJSON

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.

Note: See the Mattermost logging documentation for details.

Maximum field size#

Enables system admins to limit the size of log fields during logging.

Numerical value. Default is 2048.

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

Enable diagnostics and error reporting#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Whether or not diagnostics and error reports are sent to Mattermost, Inc.

true: (Default) Send diagnostics and error reports.
false: Diagnostics and error reports aren’t sent.

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

Note: See the telemetry docummentation for details on the information Mattermost collects.

Session lengths#

Available on all plans

self-hosted deployments

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

Extend session length with activity#

Also available in legacy Mattermost Enterprise Edition E10 or 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

Terminate sessions on password change#

Enable or disable session revocation when a user’s password changes.

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

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

Session length for AD/LDAP and email#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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:

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

Performance monitoring#

Available on Enterprise plans

self-hosted deployments

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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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#

Available on all plans

self-hosted deployments

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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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 debugging#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable or disable client-side debugging settings found in Settings > Advanced > Debugging for individual users.

true: Those settings are visible and can be enabled by users.
false: (Default) Those settings are hidden and disabled.

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

See the client debugging documentation to learn more.

Allow untrusted internal connections#

Also available in legacy Mattermost Enterprise Edition E10 or 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_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS`
This setting is a whitelist of local network addresses that can be requested by the Mattermost server. It’s configured as a whitespace-separated list of hostnames, IP addresses, and CIDR ranges that can be accessed. Requests that can only be configured by system admins are considered trusted and won’t be affected by this setting. Trusted URLs include ones used for OAuth login or for sending push notifications. The following features make untrusted requests and are affected by this setting: Integrations using webhooks, slash commands, or message actions. This prevents them from requesting endpoints within the local network. Link previews. When a link to a local network address is posted in a chat message, this prevents a link preview from being displayed. The local image proxy. If the local image proxy is enabled, images located on the local network cannot be used by integrations or posted in chat messages.
Some examples of when you may want to modify this setting include: When installing a plugin that includes its own images, such as Matterpoll, you’ll need to add the Mattermost server’s domain name to this list. When running a bot or webhook-based integration on your local network, you’ll need to add the hostname of the bot/integration to this list. If your network is configured in such a way that publicly-accessible web pages or images are accessed by the Mattermost server using their internal IP address, the hostnames for those servers must be added to this list.
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`.

config.json-only settings#

Available on all plans

self-hosted deployments

Disable Customer Portal requests#

Enable or disable customer portal requests.

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

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

Note

Cloud admins can’t modify this configuration setting.

Enable API team deletion#

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

True: The api/v4/teams/{teamid}?permanent=true API endpoint can be called by team admins and system admins (or users with appropriate permissions), or by running the mmctl team delete command to permanently delete a team.

False: The API endpoint cannot be called. Note that api/v4/teams/{teamid} can still be used to soft delete a team.

This feature’s config.json setting is "EnableAPITeamDeletion": false with options true and false.

Enable API user deletion#

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

True: The api/v4/users/{userid}?permanent=true API endpoint can be called by system admins (or users with appropriate permissions), or by running the mmctl user delete command, to permanently delete a user.

False: The API endpoint cannot be called. Note that api/v4/users/{userid} can still be used to soft delete a user.

This feature’s config.json setting is "EnableAPIUserDeletion": false with options true and false.

Enable API channel deletion#

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

True: The api/v4/channels/{channelid}?permanent=true API endpoint can be called by system admins (or users with appropriate permissions), or by running the mmctl channel delete command, to permanently delete a channel.

False: The API endpoint cannot be called. Note that api/v4/channels/{channelid} can still be used to soft delete a channel.

This feature’s config.json setting is "EnableAPIChannelDeletion": false with options true and false.

Enable desktop app developer mode#

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

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

True: Unlocks the following options in the Desktop App for the purposes of troubleshooting and debugging. You should only enable this setting if instructed to by a Mattermost developer:

Browser Mode Only: Completely disables the preload script and stops web app components from knowing they’re in the desktop app. This option should be the best indicator of whether a web app component is causing performance and/or memory retention issues. This option disables notifications, cross-tab navigation, unread/mentions badges, the calls widget, and breaks resizing on macOS.

Disable Notification Storage: Turns off maps that hold references to unread notifications until they’ve been selected & read. This option is good for debugging in cases where Mattermost is holding onto too many references to unused notifications.

Disable User Activity Monitor: Turns off the interval that checks whether the user is away or not. This option is good for debugging whether a user’s availability status is causing unexpected desktop app behavior.

Disable Context Menu: Turns off the context menu attached to the BrowserViews. This option is good as a library santity check.

Force Legacy Messaging API: Forces the app to revert back to the old messaging API instead of the newer contextBridge API. This option is a good santity check to confirm whether the new API is responsible for holding onto memory.

Force New Messaging API: Forces the app to use the contextBridge API and completely disables the legacy one. This option forces off listeners for the legacy API.