docs/main/administration-guide/configure/environment-configuration-settings.mdx
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
import Inc0_push_notification_server_configuration_settings from './push-notification-server-configuration-settings.mdx'; import Inc1_rate_limiting_configuration_settings from './rate-limiting-configuration-settings.mdx';
<PlanAvailability slug="all-commercial" />Review and manage the following environmental configuration options in the System Console by selecting the Product menu, selecting System Console, and then selecting Environment:
System admins managing a self-hosted Mattermost deployment can edit the config.json file as described in the following tables. Each configuration value below includes a JSON path to access the value programmatically in the config.json file using a JSON-aware tool. For example, the SiteURL value is under ServiceSettings.
cat config/config.json | jq '.ServiceSettings.SiteURL'config.json file manually, look for an object such as ServiceSettings, then within that object, find the key SiteURL.With self-hosted deployments, you can configure the network environment in which Mattermost is deployed by going to System Console > Environment > Web Server, or by updating the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
https://example.com/company/mattermost.Web server uses address:port (e.g., ":8065"), while Metrics uses a port number only (e.g., 8067).
See the setting up TLS for Mattermost for details.
See the setting up TLS for Mattermost for details on setting up Let's Encrypt.
Enabling this feature makes these connections susceptible to man-in-the-middle attacks.
</Warning>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.
</Note>Purging the caches may adversely impact performance. high availability cluster-based deployments will attempt to purge all the servers in the cluster.
</Note>We strongly recommend configuring a single websocket URL that matches the Site URL configuration setting.
</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.
</Note>[] means that no header will be trusted.See the Strict-Transport-Security documentation for details.
See the Strict-Transport-Security documentation for details.
ServerTLSSupportedCiphers variable in /model/config.go for a list of ciphers considered secure.See the performance monitoring documentation for details.
With self-hosted deployments, you can configure the database environment in which Mattermost is deployed by going to System Console > Environment > Database, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
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.
<table style={{width: '99%'}}> <colgroup> <col style={{width: '30%'}} /> <col style={{width: '13%'}} /> <col style={{width: '55%'}} /> </colgroup> <thead> <tr> <th>Short description of the <code>sslmode</code> parameter</th> <th>Value</th> <th>Example of a data source name</th> </tr> </thead> <tbody> <tr> <td><p>Don't use TLS / SSL encryption against the PostgreSQL server.</p><p>Default value in file <code>config.json</code></p></td> <td><code>disable</code></td> <td><code>postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=disable&connect_timeout=10</code></td> </tr> <tr> <td><p>The data is encrypted and the network is trusted.</p><p>Default value is <code>sslmode</code> when omitted.</p></td> <td><code>require</code></td> <td><code>postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=require&connect_timeout=10</code></td> </tr> <tr> <td>The data is encrypted when connecting to a trusted server.</td> <td><code>verify-ca</code></td> <td><code>postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=verify-ca&connect_timeout=10</code></td> </tr> <tr> <td>The data is encrypted when connecting to a trusted server.</td> <td><code>verify-full</code></td> <td><code>postgres://mmuser:password@hostname_or_IP:5432/mattermost_test ?sslmode=verify-full&connect_timeout=10</code></td> </tr> </tbody> </table>When Driver Name is set to mysql, we recommend using collation over using charset.
To specify collation:
"SqlSettings": {
"DataSource": "<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8&collation=utf8mb4_general_ci",
[...]
}
If collation is omitted, the default collation, utf8mb4_general_ci is used:
"SqlSettings": {
"DataSource": "<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8",
[...]
}
If you’re using MySQL 8.0 or later, the default collation has changed to utf8mb4_0900_ai_ci. See our Database Software Requirements documentation for details on MySQL 8.0 support.
To use TLS with MySQL Databases
The parameter to encrypt connection against a MySQL server is tls.
The library used to interact with MySQL is Go-MySQL-Driver.
For the moment, it's not possible to use all the values that you could pass to a standard MySQL Client mysql --ssl-mode=value. See Connection-Encryption Option Summary documentation for a version 8.0 example.
Your database admin must configure the functionality according to supported values described below.
<table style={{width: '99%'}}> <colgroup> <col style={{width: '32%'}} /> <col style={{width: '14%'}} /> <col style={{width: '52%'}} /> </colgroup> <thead> <tr> <th>Short description of the <code>tls</code> parameter</th> <th>Value</th> <th>Example of a data source name</th> </tr> </thead> <tbody> <tr> <td>Don't use TLS / SSL encryption against MySQL server.</td> <td><code>false</code></td> <td><code>"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=false"</code></td> </tr> <tr> <td>Use TLS / SSL encryption against MySQL server.</td> <td><code>true</code></td> <td><code>"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=true"</code></td> </tr> <tr> <td>Use TLS / SSL encryption with a self-signed certificate against MySQL server.</td> <td><code>skip-verify</code></td> <td><code>"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify"</code></td> </tr> <tr> <td>Use TLS / SSL encryption if server advertises a possible fallback; unencrypted if it's not advertised.</td> <td><code>preferred</code></td> <td><code>"<mmuser:password>@tcp(hostname or IP:3306)/mattermost_test ?charset=utf8mb4,utf8&writeTimeout=30s&tls=preferred"</code></td> </tr> </tbody> </table>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.
MySQL databases must be configured to support searching strings shorter than three characters. See the MySQL documentation for details.
</Note>Search behavior in Mattermost depends on which search engines are enabled:
Disabling this configuration setting in larger deployments may improve server performance in the following areas:
However, the ability to perform database searches in Mattermost is a critical feature for many users, particularly when other search engines aren't enabled. Disabling this feature will result in users seeing an error if they attempt to use the Mattermost Search box. It’s important to balance performance improvements with the needs of your organization and users.
</Note>A list of all migrations that have been applied to the data store based on the version information available in the db_migrations table. Select About Mattermost from the Product menu to review the current database schema version applied to your deployment.
Read-only display of the currently active backend used for search. Values can include none, database, elasticsearch, or bleve.
MM_SQLSETTINGS_DATASOURCEREPLICAS=dc-1 dc-2For 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.
Each database connection string in the array must be in the same form used for the Data source setting.
</Note>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.
QueryAbsoluteLag and QueryTimeLag queries must return a single row.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=<>"
}
]
}
}
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": ""
}
]
}
}
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:
json{ "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": "" } ] } }
pg_monitor. This user should be the same user configured above in the DataSource string.</TabItem> </Tabs>For more information on roles, see the PostgreSQL documentation.
shsudo -u postgres psql postgres=# GRANT pg_monitor TO mmuser;
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.textmattermost_db_replica_lag_abs{instance=~"$server"}
This configuration setting is applicable to self-hosted deployments only.
</Note>Core database search happens in a relational database and is intended for deployments under about 2–3 million posts and file entries. Beyond that scale, enabling enterprise search with Elasticsearch or AWS OpenSearch is highly recommended for optimum search performance before reaching 3 million posts.
For self-hosted deployments with over 3 million posts, Elasticsearch or AWS OpenSearch is required to avoid significant performance issues, such as timeouts, with message searches and @mentions.
You can configure Mattermost enterprise search by going to System Console > Environment > Elasticsearch. The following configuration settings apply to both Elasticsearch and AWS OpenSearch. You can also edit the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results.
</Note>Both Elasticsearch and AWS OpenSearch provide enterprise-scale deployments with optimized search performance and prevents performance degradation and timeouts. Learn more about enterprise search in our product documentation.
<table> <colgroup> <col style={{width: '36%'}} /> <col style={{width: '63%'}} /> </colgroup> <tbody> <tr> <td><p>The type of search backend.</p><ul><li><code>elasticsearch</code> - (<strong>Default</strong>)</li><li><code>opensearch</code> - Required for AWS OpenSearch.</li></ul></td> <td><ul><li>System Config path: <strong>Environment > Elasticsearch</strong></li><li><code>config.json</code> setting: <code>ElasticsearchSettings</code> > <code>Backend</code> > <code>"elasticsearch"</code></li><li>Environment variable: <code>MM_ELASTICSEARCHSETTINGS_BACKEND</code></li></ul></td> </tr> </tbody> </table>Learn more about enterprise search version support.
/opt/mattermost/data/elasticsearch/ or /opt/mattermost/data/opensearch and configured in the System Console as ./elasticsearch/cert.pem or ./opensearch/cert.pem.Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.
<table> <colgroup> <col style={{width: '41%'}} /> <col style={{width: '58%'}} /> </colgroup> <tbody> <tr> <td>Optional client certificate for the connection to the Elasticsearch or AWS OpenSearch server in the PEM format.</td> <td><ul><li>System Config path: <strong>Environment > Elasticsearch</strong></li><li><code>config.json</code> setting: <code>ElasticsearchSettings</code> > <code>ClientCert</code></li><li>Environment variable: <code>MM_ELASTICSEARCHSETTINGS_CLIENTCERT</code></li></ul></td> </tr> </tbody> </table>Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them.
<table> <colgroup> <col style={{width: '41%'}} /> <col style={{width: '58%'}} /> </colgroup> <tbody> <tr> <td>Optional key for the client certificate in the PEM format.</td> <td><ul><li>System Config path: <strong>Environment > Elasticsearch</strong></li><li><code>config.json</code> setting: <code>ElasticsearchSettings</code> > <code>ClientKey</code></li><li>Environment variable: <code>MM_ELASTICSEARCHSETTINGS_CLIENTKEY</code></li></ul></td> </tr> </tbody> </table>Select the Test Connection button in the System Console to validate the connection between Mattermost and the Elasticsearch or AWS OpenSearch server.
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.
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.
If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results.
Autocompletion results may be incomplete until a bulk index of the existing users and channels database is finished.
This setting has no effect when Compliance Mode is enabled. When Compliance Mode is active, search results are always restricted to channels the user is a member of.
</Note>n data nodes, the number of replicas per shard for each index should be n-1.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.
</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 or AWS OpenSearch cluster changes, this configuration setting, as well as Post Index Replicas and User Index Replicas must also be updated accordingly.
If there are n data nodes, the number of replicas per shard for each index should be n-1. If the number of nodes in an Elasticsearch or AWS OpenSearch cluster changes, this configuration setting, as well as Post Index Replicas and User Index Replicas must also be updated accordingly.
If you’re using data retention and enterprise search, configure this with a value greater than your data retention policy.
</Note>When this setting is used, all Elasticsearch or AWS OpenSearch indexes created by Mattermost are given this prefix. You can set different prefixes so that multiple Mattermost deployments can share an Elasticsearch or AWS OpenSearch cluster without the index names colliding.
</Note>It may be necessary to increase this value to avoid hitting the rate limit or resource limit of your Elasticsearch or AWS OpenSearch cluster on installs handling more than 1 post per second.
</Note>What exactly happens when I increase this value?
The primary impact is that a post will be indexed into Elasticsearch or AWS OpenSearch after the threshold of posts is met, which then makes the posts searchable within Mattermost. So, if you set this based on recommendations for larger servers, and you make a post, you cannot find it via search for ~10–20 seconds, on average. Realistically, no users should see or feel this impact due to the limited number of users who are actively searching for a post this quickly. You can set this value to a lower or higher average depending on your Elasticsearch or AWS OpenSearch server specifications.
During busy periods, this delay will be faster as more traffic is occurring, causing more posts and a quicker time to hit the index number. During slower periods, expect the reverse.
How to find the right number for your server
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
WHEREclause to see the posts per minute over a different time period. Right now31536000000represents the number of milliseconds in a year.SQLSELECT 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<code>) you would calculate </code><code>600 / 3</code><code> to come to the number </code><code>200</code>`. After 200 posts, Mattermost will index the posts into Elasticsearch or AWS OpenSearch. So, on average, there would be a 20-second delay in searchability.
Edit the config.json or run mmctl to modify the LiveIndexingBatchSize setting
In the ``config.json``
JSON{ "ElasticsearchSettings": { "LiveIndexingBatchSize": 200 } }Via mmctl
shmmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200Via an environment variable
shMM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200
Restart the Mattermost server.
Available from Mattermost v11.6. The required analyzer plugins should be installed on the Elasticsearch or AWS OpenSearch server before enabling this setting for full analysis support. If no plugin is detected, a warning will be logged. See the Elasticsearch setup and AWS OpenSearch setup documentation for plugin installation instructions.
If you enable this setting on a server that was previously running Elasticsearch or AWS OpenSearch, you must purge and rebuild the search indexes for existing content to be properly searchable with the new analyzers. See the Elasticsearch setup documentation for instructions on purging and rebuilding indexes.
</Note>With self-hosted deployments, you can configure file storage settings by going to System Console > Environment > File Storage, or by editing the config.json file as described in the following tables.
Mattermost currently supports storing files on the local filesystem and Amazon S3 or S3-compatible containers. We have tested Mattermost with Digital Ocean Spaces, but not all S3-compatible containers on the market. If you are looking to use other S3-compatible containers, we recommend completing your own testing. You can also use local storage or a network drive using NFS.
</Note>When File storage system is set to amazons3, this setting has no effect.
Received invalid response from the server error typically indicates that MaxFileSize isn't large enough to support the plugin file upload, and/or that proxy settings may not be sufficient.client_max_body_size.LimitRequestBody.Enabling document search by content is required when extracting content from files. Both Mattermost file search and Mattermost Agents can access files and their content, when enabled with the necessary dependencies. Document content search results for files shared before upgrading to Mattermost Server v5.35 may be incomplete until an extraction command is executed using the mmctl. If this command is not run, users can search older files based on file name only.
You can optionally install the following dependencies to extend content searching support in Mattermost to include file formats beyond PDF, DOCX, and ODT, such as DOC, RTF, XML, and HTML:
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.
</Note>.7z) files are blocked for security reasons and are not searchable.For Digital Ocean Spaces or other S3-compatible services, leave this setting empty.
This is required for access unless you are using an Amazon S3 IAM Role with Amazon S3.
</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.
</Note>See the AWS documentation for information about when to use the Signature v2 signing process.
This configuration setting is available for self-hosted deployments only.
</Note>Select the Test Connection button in the System Console to validate the settings and ensure the user can access the server.
Some Amazon S3-compatible storage solutions require the storage class parameter to be present in upload requests, otherwise they will be rejected. Configure this storage class as the storage class required by your S3-compatible solution.
<table> <colgroup> <col style={{width: '42%'}} /> <col style={{width: '57%'}} /> </colgroup> <tbody> <tr> <td><p>The storage class to use for uploads to S3-compatible storage solutions.</p><p>String input. Default is an empty string <code>""</code>. Select <strong>Test Connection</strong> to test the configured connection.</p></td> <td><ul><li>System Config path: <strong>Environment > File Storage</strong></li><li><code>config.json</code> setting: <code>FileSettings</code> > <code>AmazonS3StorageClass</code> > <code>""</code>,</li><li>Environment variable: <code>MM_FILESETTINGS_AMAZONS3STORAGECLASS</code></li></ul></td> </tr> </tbody> </table> <Note>Most Amazon S3-compatible storage solutions assign a default storage class of STANDARD when no storage class is provided. See the Amazon S3 storage class documentation for details about supported storage classes.
Most Amazon S3-compatible storage solutions assign a default storage class of STANDARD when no storage class is provided. See the Amazon S3 storage class documentation for details about supported storage classes.
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.
</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.
</Note>With self-hosted deployments, an image proxy can be used by Mattermost apps to prevent them from connecting directly to remote self-hosted servers. Configure an image proxy by going to System Console > Environment > Image Proxy, or by editing the config.json file as described in the following tables.
See the image proxy documentation to learn more.
See the image proxy documentation to learn more.
See the image proxy documentation to learn more.
With self-hosted deployments, you can configure SMTP email server settings by going to System Console > Environment > SMTP, or by editing the config.json file as described in the following tables.
See the Telemetry documentation to learn more.
<Inc0_push_notification_server_configuration_settings />
With self-hosted deployments, you can configure Mattermost as a high availability cluster-based deployment by going to System Console > Environment > High Availability, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
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.
See the high availability cluster-based deployment documentation for details.
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.<Inc1_rate_limiting_configuration_settings />
Mattermost provides 3 independent logging systems for self-hosted deployments that can be configured separately with separate log files and rotation policies to meet different operational and compliance needs:
By default, all Mattermost editions write logs to both the console and to the mattermost.log file in a machine-readable JSON format. Mattermost Enterprise and Professional customers can additionally log directly to syslog and TCP socket destination targets.
Configure general logging by going to System Console > Environment > Logging, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
From Mattermost v11.0, notification logs are automatically included in the main console logs.
</Note>Typically set to true in a production environment.
mattermost.log file locally by going to System Console > Reporting > Server Logs, and selecting Download Logs.MM_LOG_PATH environment variable to restrict log file locations to a designated root directory. This security enhancement ensures that all log files configured via LogSettings.FileLocation or LogSettings.AdvancedLoggingJSON remain within an authorized logging directory.
MM_LOG_PATH isn't set, the default logs directory is used. Paths outside the root directory generate error logs and are excluded from support packet downloads. See the log path restrictions documentation for details.Typically set to true in a production environment.
Enable debug logs by changing the file log level to DEBUG to include the request body of incoming webhooks in logs.
AdvancedLoggingJSON configurations should be within the directory specified by the MM_LOG_PATH environment variable. See log path restrictions for details.See the telemetry documentation for details on the information Mattermost collects.
</Note>From Mattermost v11, notification log settings have been consolidated into the standard console logs and mattermost.log file. You can no longer disable notification logging without using advanced logging settings, as the main log level setting now controls both server and notification logs.
You can use the AdvancedLoggingJSON configuration with discrete notification log levels: NotificationError, NotificationWarn, NotificationInfo, NotificationDebug, and NotificationTrace to split notification logs into separate files and reduce troubleshooting noise. See Advanced Logging for details.
The following configuration settings apply only to Mattermost server versions prior to v11.0.
You can configure logging specifically for Mattermost notifications by editing the config.json file as described in the following tables. These settings operate independently from the main LogSettings and allow you to customize logging behavior specifically for the notification subsystem. Changes to these configuration settings require a server restart before taking effect.
Typically set to true in a production environment.
The path you configure must exist, and Mattermost must have write permissions for this directory.
</Note>Configure audit logging by going to System Console > Compliance > Audit Logging, or by editing the config.json file as described in the following tables. These settings operate independently from the main LogSettings and allow you to customize logging behavior specifically for the audit subsystem. Changes to these configuration settings require a server restart before taking effect.
When FileEnabled is set to true, then the audit file name must be set.
When output audit logs to file is enabled, the file name must be set. To configure file rotation and advanced audit log output, use the AdvancedLoggingJSON setting.
</Note>With self-hosted deployments, user sessions are cleared when a user tries to log in, and sessions are cleared every 24 hours from the sessions database table. Configure session lengths by going to System Console > Environment > Session Lengths, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
After changing this setting, the new session length takes effect after the next time the user enters their credentials.
</Note>After changing this setting, the new session length takes effect after the next time the user enters their credentials.
</Note>With self-hosted deployments, you can configure performance monitoring by going to System Console > Environment > Performance Monitoring, or by editing the config.json file as described in the following tables.
{
"MetricsSettings": {
"Enable": false,
"BlockProfileRate": 0,
"ListenAddress": :8067,
"EnableClientMetrics": false,
"EnableNotificationMetrics": true,
"ClientSideUserIds": ""
}
}
Changes to configuration settings in this section require a server restart before taking effect.
See the performance monitoring documentation to learn more about setting up performance monitoring with Prometheus and Grafana. See the collect performance metrics documentation to learn more about using the Mattermost Metrics plugin.
See the performance monitoring documentation to learn more.
EnableClientMetrics is set to true.MM_METRICSSETTINGS_CLIENTSIDEUSERIDS="user1,user2,user3".ListenAddress accepts a port only. It doesn’t take an IP/host. If you need to restrict interfaces, do so via your OS firewall or reverse proxy.host:port format. Use :8067 to listen on all interfaces on port 8067, or use localhost:8067 to restrict to localhost only.config.json.MetricsSettings.Enable must be set to trueMetricsSettings.EnableNotificationMetrics must be set to trueSee the performance monitoring documentation to learn more about Mattermost Notification Health metrics.
With self-hosted deployments, you can configure developer mode by going to System Console > Environment > Developer, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
See the client debugging documentation to learn more.
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.
</Warning> <table> <colgroup> <col style={{width: '32%'}} /> <col style={{width: '67%'}} /> </colgroup> <tbody> <tr> <td>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.</td> <td><ul><li>System Config path: <strong>Environment > Developer</strong></li><li><code>config.json</code> setting: <code>ServiceSettings</code> > <code>AllowedUntrustedInternalConnections</code> > <code>""</code></li><li>Environment variable: <code>MM_SERVICESETTINGS_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS</code></li></ul></td> </tr> </tbody> </table>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:
Some examples of when you may want to modify this setting include:
webhooks.internal.example.com, 127.0.0.1, or 10.0.16.0/28./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.From Mattermost v10.7 and mobile app v2.27, you can configure biometric authentication, prevent Mattermost use on jailbroken or rooted devices, and can block screen captures without relying on an EMM Provider. Configure these options by going to System Console > Environment > Mobile Security, or by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart and require users to restart their mobile app or log out and back in before taking effect.
Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.
</Note>See mobile security features for a full description of how the timers and operations interact.
These settings apply globally to all mobile users. Changes are delivered to connected devices in real time; offline devices continue operating under their last-known configuration until they reconnect. Timer state persists across app and device restarts.
When a timer expires, active cached content such as posts and file previews is purged, and the app notifies the user that data was removed due to policy enforcement. After a purge, users re-sync from the server on reconnection — server URLs are recoverable from keychain entries so server access is not lost.
This setting improves an organization's mobile security posture by restricting file access while still allowing essential file viewing capabilities.
<table> <colgroup> <col style={{width: '100%'}} /> </colgroup> <tbody> <tr> <td><ul><li><strong>true</strong>: Prevents file downloads, previews, and sharing for most file types, | - System Config path: <strong>Site Configuration > File sharing and downloads</strong> | even when the | - <code>config.json</code> setting: <code>FileSettings</code> > <code>MobileEnableSecureFilePreview</code> > <code>false</code> | <a href="mm-ref:administration-guide%2Fconfigure%2Fsite-configuration-settings%3Aallow%20file%20downloads%20on%20mobile">Allow file downloads on mobile</a> | - Environment variable: <code>MM_FILESETTINGS_MOBILEENABLESECUREFILEPREVIEW</code> configuration setting is enabled. Allows in-app previews for PDFs, | | videos, and images only. Files are stored temporarily in the app's cache and cannot be exported or shared. | |</li><li><strong>false</strong>: <strong>(Default)</strong> Secure file preview mode is disabled. | |</li></ul></td> </tr> </tbody> </table> <Note>Changing this configuration setting takes effect when mobile users restart their Mattermost mobile app or log out and log back in.
</Note>The following self-hosted deployment settings are only configurable in the config.json file and are not available in the System Console.
Cloud admins can’t modify this configuration setting.
</Note>This setting isn’t available in the System Console and can only be set in config.json.
This setting isn’t available in the System Console and can only be set in config.json.
This setting isn’t available in the System Console and can only be set in config.json.
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.
From Mattermost v10.4, Mattermost Enterprise customers with self-hosted deployments can configure Redis (Remote Dictionary Server) as an alternative cache backend. Redis is an open-source, in-memory data structure store that can be used as a database, cache, and message broker. It supports various data structures and is a top choice for its performance because its able to store data in memory and provide very quick data access.
Using Redis as a caching solution can help ensure that Mattermost for enterprise-level deployments with high concurrency and large user bases remains performant and efficient, even under heavy usage.
Configure a Redis cache by editing the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
Adding a prefix to all Redis cache keys reduces key collisions, simplifies debugging, isolates data, and provides a clear structure for managing and scaling Redis-based systems. In environments where multiple systems or tenants use the same Redis instance, prefixes become critical for maintaining data integrity and operational efficiency.
</Tip>/exportlink [job-id|zip file|latest] slash command. See the Mattermost data migration documentation for details. Alternatively, Cloud and self-hosted admins can use the mmctl export generate-presigned-url command to generate a presigned URL directly from mmctl.EnableExportDirectDownload to be set to true, the storage must be compatible with generating an S3 link, and this experimental configuration setting must be set to true. Presigned URLs for exports aren't supported for systems with shared storage.