Skip to main content

Experimental configuration settings

Review and manage the following experimental configuration options in the System Console by selecting the Product Navigate between Channels, collaborative playbooks, and boards using the product menu icon. menu, selecting System Console, and then selecting Experimental > Features:

Experimental System Console configuration settings​

Change authentication method​

True: Users can change their sign-in method to any that is enabled on the server, either via their Profile or the APIs.

False: Users cannot change their sign-in method, regardless of which authentication options are enabled.

This feature's config.json setting is "ExperimentalEnableAuthenticationTransfer": true with options true and false.

Adds a configurable timeout for requests made to return link metadata. If the metadata is not returned before this timeout expires, the message will post without requiring metadata. This timeout covers the failure cases of broken URLs and bad content types on slow network connections.

This feature's config.json setting is "LinkMetadataTimeoutMilliseconds: 5000`` with numerical input.

Enable automatic replies​

True: Users can enable Automatic Replies in Settings > Notifications. Users set a custom message that will be automatically sent in response to Direct Messages.

False: Disables the Automatic Direct Message Replies feature and hides it from Settings.

This feature's config.json setting is "ExperimentalEnableAutomaticReplies": false with options true and false.

Enable default channel leave/join system messages​

This setting determines whether team leave/join system messages are posted in the default town-square channel.

True: Enables leave/join system messages in the default town-square channel.

False: Disables leave/join messages from the default town-square channel. These system messages won't be added to the database either.

This feature's config.json setting is "ExperimentalEnableDefaultChannelLeaveJoinMessages": true with options true and false.

Enable Mobile Watermark​

Available on Enterprise Advanced from Mattermost v11.7 onward.

True: Authenticated Mattermost mobile sessions display a watermark overlay showing the user's username, the server domain, the current date (YYYY-MM-DD), and the current time (HH:mm). This experimental capability is intended to support data loss prevention (DLP) workflows by helping identify the user, server, and time associated with mobile screenshots or shared screen captures.

False: No watermark overlay is displayed in the Mattermost mobile app.

This feature's config.json setting is "ExperimentalSettings.EnableWatermark": false with options true and false.

User's status and profile fetching poll interval​

This setting configures the number of milliseconds to wait between fetching user statuses and profiles periodically. Set to 0 to disable.

This feature's config.json setting is "ExperimentalSettings.UsersStatusAndProfileFetchingPollIntervalMilliseconds": 3000 with numerical input.

Primary team​

The primary team of which users on the server are members. When a primary team is set, the options to join other teams or leave the primary team are disabled.

If the team URL of the primary team is https://example.mattermost.com/myteam/, then set the value to myteam in config.json.

This feature's config.json setting is "ExperimentalPrimaryTeam": "" with string input.

Disable data refetching on browser refocus​

This setting disables re-fetching of channel and channel members on browser focus.

True: Mattermost won't refetch channels and channel members when the browser regains focus. This may result in improved performance for users with many channels and channel members.

False: (Default) Mattermost will refetch channels and channel members when the browser regains focus.

This feature's config.json setting is "ExperimentalSettings.DisableRefetchingOnBrowserFocus": false with options true and false.

Disable wake up reconnect handler​

This setting disables attempts to detect when the computer has woken up and refetch data.

True: Mattermost won't attempt to detect when the computer has woken up and refetch data. This might reduce the amount of regular network traffic the app is sending.

False: (Default) Mattermost attempts to detect when the computer has woken up and refreshes data.

This feature's config.json setting is "ExperimentalSettings.DisableWakeUpReconnectHandler": false with options true and false.

Delay channel autocomplete​

This setting controls whether or not the channel link autocomplete triggers immediately when after a tilde is typed when composing a message. This setting makes the channel autocomplete, such as ~town-square, less obtrusive for people who use tildes ~ as punctuation.

True: The autocomplete appears after the user types a tilde followed by two or more characters. For example, typing ~to will show the autocomplete, but typing ~ will not.

False: (Default) The autocomplete appears immediately after the user types a tilde. For example, typing ~ will show the autocomplete.

This feature's config.json setting is "ExperimentalSettings.DelayChannelAutocomplete": false with options true and false.

YouTube referrer policy​

This setting resolves issues where YouTube video previews display as unavailable.

True: The referrer policy for embedded YouTube videos is set to strict-origin-when-cross-origin.

False: (Default) The referrer policy is set to no-referrer which enhances user privacy by not disclosing the source URL, but limits the ability to track user engagement and traffic sources in analytics tools.

This feature's config.json setting is "ExperimentalSettings.YoutubeReferrerPolicy": false with options true and false.

Experimental Bleve configuration settings​

Access the following configuration settings in the System Console by going to Experimental > Bleve, or by editing the config.json file as described in the following tables:

Enable Bleve indexing​

True: The indexing of new posts occurs automatically. Search queries will not use bleve search until Enable Bleve for search queries is enabled.

False: The indexing of new posts does not occur automatically.

This feature's config.json setting is "EnableIndexing": false with options true and false.

Index directory​

Directory path to use for storing bleve indexes.

This feature's config.json setting is "IndexDir": "" with string input.

Bulk index now​

Select Index Now to index all users, channels, and posts in the database from oldest to newest. Bleve is available during indexing, but search results may be incomplete until the indexing job is complete.

Purge indexes​

Select Purge Index to remove the contents of the Bleve index directory. Search results may be incomplete until a bulk index of the existing database is rebuilt.

Enable Bleve for search queries​

True: Search queries will use bleve search.

False: Search queries will not use bleve search.

This feature's config.json setting is "EnableSearching": false with options true and false.

Enable Bleve for autocomplete queries​

True: Autocomplete queries will use bleve search.

False: Autocomplete queries will not use bleve search.

This feature's config.json setting is "EnableAutocomplete": false with options true and false.

Experimental configuration settings for self-hosted deployments only​

Access the following self-hosted configuration settings by editing the config.json file as described in the following tables. These configuration settings are not accessible through the System Console.

File Location​

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

Set the file location of the compliance exports. By default, they are written to the exports subdirectory of the configured Local Storage directory.

This feature's config.json setting is "FileLocation": "export" with string input.

Push notification buffer​

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

Used to control the buffer of outstanding Push Notification messages to be sent. If the number of messages exceeds that number, then the request making the Push Notification will be blocked until there's room.

This feature’s config.json setting is "PushNotificationBuffer": 1000" with numerical input.

Restrict system admin​

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

True: (Default for Cloud deployments) Restricts the system admin from viewing and modifying a subset of server configuration settings from the System Console. Not recommended for use in on-prem installations. This is intended to support Mattermost Private Cloud in giving the system admin role to users but restricting certain actions only for Cloud Admins.

False: (Default for self-host deployments) No restrictions are applied to the system admin role.

This feature's config.json setting is "RestrictSystemAdmin": "false" with options true and false.

Enable client-side certification​

True: Enables client-side certification for your Mattermost server. See the documentation to learn more.

False: (Default) Client-side certification is disabled.

This feature's config.json setting is "ClientSideCertEnable": false with options true and false.

Client-side certification login method​

This configuration setting is used in combination with the ClientSideCertEnable configuration setting and has the following possible values:

Primary: After the client side certificate is verified, user's email is retrieved from the certificate and is used to log in without a password.

Secondary: (Default) After the client side certificate is verified, user's email is retrieved from the certificate and matched against the one supplied by the user. If they match, the user logs in with regular email/password credentials.

This feature's config.json setting is "ClientSideCertCheck": "secondary" with options "primary" and "secondary".

Export output directory​

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

The directory where the exported files are stored. The path is relative to the FileSettings directory. By default, exports are stored under ./data/export.

This feature's config.json setting under the ExportSettings section is Directory: ./export with string input.

Export retention days​

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

The number of days to retain the exported files before deleting them.

This feature's config.json setting under the ExportSettings section is RetentionDays: 30 with numerical input.

Maximum image resolution​

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

Maximum image resolution size for message attachments in pixels.

This feature's config.json setting is "MaxImageResolution": 33177600 with numerical input.

Maximum image decoder concurrency​

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

Indicates how many images can be decoded concurrently at once. The default value of -1 configures Mattermost to automatically use the number of CPUs present.

This feature's config.json setting is "MaxImageDecoderConcurrency": "-1" with numerical input.

Initial font​

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

Font used in auto-generated profile pics with colored backgrounds.

This feature's config.json setting is "InitialFont": "luximbi.ttf" with string input.

Amazon S3 signature v2​

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

By default, Mattermost uses Signature V4 to sign API calls to AWS, but under some circumstances, V2 is required. For more information about when to use V2, see https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html.

True: Use Signature Version 2 Signing Process.

False: Use Signature Version 4 Signing Process.

This feature's config.json setting is "AmazonS3SignV2": false with options true and false.

Amazon S3 path​

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

Allows using the same S3 bucket for multiple deployments.

This feature’s config.json setting is "AmazonS3PathPrefix: "" with string input.

GitLab scope​

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

Standard setting for OAuth to determine the scope of information shared with OAuth client. Not currently supported by GitLab OAuth.

This feature's config.json setting is "Scope": "" with string input.

Global relay SMTP server timeout​

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

The number of seconds that can elapse before the connection attempt to the SMTP server is abandoned. The default value is 1800 seconds. This setting is currently not available in the System Console and can only be set in config.json.

This feature's config.json setting is "GlobalRelaySettings.SMTPServerTimeout": "1800" with numerical input.

Google scope​

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

Standard setting for OAuth to determine the scope of information shared with OAuth client. Recommended setting is profile email.

This feature's config.json setting is "Scope": "profile email" with string input.

Import input directory​

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

The directory where the imported files are stored. The path is relative to the FileSettings directory. By default, imports are stored under ./data/import.

This feature's config.json setting under the ImportSettings section is Directory: ./import with string input.

Import retention days​

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

The number of days to retain the imported files before deleting them.

This feature's config.json setting under the ImportSettings section is RetentionDays: 30 with numerical input.

Export from timestamp​

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

Set the Unix timestamp (seconds since epoch, UTC) to export data from.

This feature's config.json setting is "ExportFromTimestamp": 0 with numerical input.

Entra ID Scope​

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

Standard setting for OAuth to determine the scope of information shared with OAuth client. Recommended setting is User.Read.

This feature's config.json setting is "Scope": "User.Read" with string input.

Enable plugin uploads​

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

True: Enables plugin uploads by system admins at Plugins > Management. If you do not plan to upload a plugin, set to false to control which plugins are installed on your server. See documentation to learn more.

False: Disables plugin uploads on your Mattermost server.

This feature's config.json setting is "EnableUploads": false with options true and false.

Allow insecure download URL​

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

True: Enables downloading and installing a plugin from a remote URL.

False: Disables downloading and installing a plugin from a remote URL.

This feature's config.json setting is "AllowInsecureDownloadUrl": false with options true and false.

Enable plugin health check​

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

True: Enables plugin health check to ensure all plugins are periodically monitored, and restarted or deactivated based on their health status. The health check runs every 30 seconds. If the plugin is detected to fail 3 times within an hour, the Mattermost server attempts to restart it. If the restart fails 3 successive times, it's automatically disabled.

False: Disables plugin health check on your Mattermost server.

This feature's config.json setting is "EnableHealthCheck": true with options true and false.

Plugin directory​

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

The location of the plugin files. If blank, they are stored in the ./plugins directory. The path that you set must exist and Mattermost must have write permissions in it.

This feature's config.json setting is "Directory": "./plugins" with string input.

Client plugin directory​

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

The location of client plugin files. If blank, they are stored in the ./client/plugins directory. The path that you set must exist and Mattermost must have write permissions in it.

This feature's config.json setting is "ClientDirectory": "./client/plugins" with string input.

Scoping IDP provider ID​

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

Allows an authenticated user to skip the initial login page of their federated Azure AD server, and only require a password to log in.

This feature's config.json setting is "ScopingIDPProviderId": "" with string input.

Scoping IDP provider name​

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

Adds the name associated with a user's Scoping Identity Provider ID.

This feature's config.json setting is "ScopingIDPName": "" with string input.

Group unread channels​

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

This setting applies to the new sidebar only. You must disable the Enable Legacy Sidebar configuration setting to see and enable this functionality in the System Console.

Default Off: Disables the unread channels sidebar section for all users by default. Users can enable it in Settings > Sidebar > Group unread channels separately.

Default On: Enables the unread channels sidebar section for all users by default. Users can disable it in Settings > Sidebar > Group unread channels separately.

This feature's config.json setting is "ExperimentalGroupUnreadChannels": "default_off" with options "default_off" and "default_on".

Enable channel category sorting​

From Mattermost v10.10, when this experimental feature is enabled, users can assign channels to new or existing channel categories when creating or renaming channels.

This configuration setting applies only to cloud-based deployments.

True: Users can assign channels to new or existing channel categories when creating or renaming channels.

False: (Default) Disables the ability to automatically assign channels to new or existing channel categories.

This feature's config.json setting is "ExperimentalEnableChannelCategorySorting": false with options true and false.

Strict CSRF token enforcement​

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

True: Enables CSRF protection tokens for additional hardening compared to the currently used custom header. When the user logs in, an additional cookie is created with the CSRF token contained.

False: Disables CSRF protection tokens and enables legacy X-Requested-With header fallback for backward compatibility.

This feature's config.json setting is "ExperimentalStrictCSRFEnforcement": false with options true and false.

Developer flags​

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

This configuration setting specifies a list of strings where each string is a flag used to set the content security policy (CSP) for the Mattermost Web App. Each flag must be in the format flag=true (e.g. unsafe-eval=true,unsafe-inline=true). Not recommended for production environments.

The following values are currently supported:

  • unsafe-eval: Adds the unsafe-eval CSP directive to the root webapp, allowing increased debugging in developer environments.
  • unsafe-inline: Adds the unsafe-inline CSP directive to the root webapp, allowing increased debugging in developer environments.

This configuration setting is disabled by default and requires developer mode to be enabled.

This feature's config.json setting is "DeveloperFlags": "" with string input.

Enable post search​

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

If this setting is enabled, users can search for messages in their Mattermost instance.

This feature's config.json setting is "EnablePostSearch": true with options true and false.

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

True: Supported document types are searchable by their filename.

False: File-based searches are disabled.

This feature's config.json setting is "EnableFileSearch": true with options true and false.

Enable user status updates​

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

Turn status updates off to improve performance. When status updates are off, users appear online only for brief periods when posting a message, and only to members of the channel in which the message is posted.

This feature's config.json setting is "EnableUserStatuses": true with options true and false.

Websocket secure port​

This setting isn't available in the System Console and can only be set in config.json. Changes to this setting require a server restart before taking effect.

(Optional) This setting defines the port on which the secured WebSocket is listening using the wss protocol. Defaults to 443. When the client attempts to make a WebSocket connection it first checks to see if the page is loaded with HTTPS. If so, it will use the secure WebSocket connection. If not, it will use the unsecure WebSocket connection. IT IS HIGHLY RECOMMENDED PRODUCTION DEPLOYMENTS ONLY OPERATE UNDER HTTPS AND WSS.

This feature's config.json setting is "WebsocketSecurePort": 443 with numerical input.

Websocket port​

This setting isn't available in the System Console and can only be set in config.json. Changes to this setting require a server restart before taking effect.

(Optional) This setting defines the port on which the unsecured WebSocket is listening using the ws protocol. Defaults to 80. When the client attempts to make a WebSocket connection it first checks to see if the page is loaded with HTTPS. If so, it will use the secure WebSocket connection. If not, it will use the unsecure WebSocket connection. IT IS HIGHLY RECOMMENDED PRODUCTION DEPLOYMENTS ONLY OPERATE UNDER HTTPS AND WSS.

This feature's config.json setting is WebsocketPort": 80 with numerical input.

Enable local mode for mmctl​

This self-hosted deployment setting isn't available in the System Console and can only be set in config.json.

True: Enables local mode for mmctl.

False: Prevents local mode for mmctl.

This feature's config.json setting is "EnableLocalMode": false with options true and false.

Enable local mode socket location​

This self-hosted deployment setting isn't available in the System Console and can only be set in config.json.

The path for the socket that the server will create for mmctl to connect and communicate through local mode. If the default value for this key is changed, you will need to point mmctl to the new socket path when in local mode, using the --local-socket-path /new/path/to/socket flag in addition to the --local flag.

If nothing is specified, the default path that both the server and mmctl assumes is /var/tmp/mattermost_local.socket.

This feature's config.json setting is "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket" with string input.

Default channels​

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

Default channels every user is added to automatically after joining a new team. Only applies to Public channels, but affects all teams on the server.

When not set, every user is added to the town-square channel by default.

This feature's config.json setting is "ExperimentalDefaultChannels": [] with string array input consisting of channel names, such as ["announcement", "developers"].

Experimental job configuration settings​

With self-hosted deployments, you can configure how Mattermost schedules and completes periodic tasks such as the deletion of old posts with Data Retention enabled or indexing posts with Elasticsearch. These settings control which Mattermost servers are designated as a Scheduler, a server that queues the tasks at the correct times, and as a Worker, a server that completes the given tasks.

When running Mattermost on a single machine, both RunJobs and RunScheduler should be enabled. Without both of these enabled, Mattermost will not function properly.

When running Mattermost in High Availability mode, RunJobs should be enabled on one or more servers while RunScheduler should be enabled on all servers under normal circumstances. A High Availability cluster-based deployment will have one Scheduler and one or more Workers. See the below sections for more information.

Run jobs​

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

Set whether or not this Mattermost server will handle tasks created by the Scheduler. When running Mattermost on a single machine, this setting should always be enabled.

When running Mattermost in High Availablity mode, one or more servers should have this setting enabled. We recommend that your High Availability cluster-based deployment has one or more dedicated Workers with this setting enabled while the remaining Mattermost app servers have it disabled.

This feature's config.json setting is "RunJobs": true with options true and false.

Run scheduler​

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

Set whether or not this Mattermost server will schedule tasks that will be completed by a Worker. When running Mattermost on a single machine, this setting should always be enabled.

When running Mattermost in High Availablity mode, this setting should always be enabled. In a High Availability cluster-based deployment, exactly one of the servers will be designated as the Scheduler at a time to ensure that duplicate tasks aren't created. See High Availability documentation for more details.

This feature's config.json setting is "RunScheduler": true with options true and false.

Clean up old database jobs​

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

Defines the threshold in days beyond which older completed database jobs are removed. This setting is disabled by default, and must be set to a value greater than or equal to 0 to be enabled.

This feature's config.json setting is "JobSettings.CleanupJobsThresholdDays": -1 with numerical input.

Clean up outdated database entries​

This setting only applies to configuration in the database. It isn't available in the System Console and can be set via mmctl or changed in the database.

Defines the threshold in days beyond which outdated configurations are removed from the database.

This feature's config.json setting is "JobSettings.CleanupConfigThresholdDays": 30 with numerical input.