Experimental configuration settings

Available on Entry, Professional, Enterprise, and Enterprise Advanced plans

This document contains approximately 45 experimental configuration settings organized into three categories. Most settings can be managed through the System Console by selecting the Product menu, selecting System Console, and then selecting Experimental > Features.

• Experimental System Console configuration settings - Settings with System Console UI access

• Experimental audit logging configuration settings - Audit logging configuration options

• Experimental config.json-only configuration settings - Settings only accessible via config.json file

Tip

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, one LoginButtonColor value is under LdapSettings.

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

• When working with the config.json file manually, look for an object such as LdapSettings, then within that object, find the key LoginButtonColor.

---

Experimental System Console configuration settings

AD/LDAP login button color

Specify the color of the AD/LDAP login button for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

AD/LDAP login button border color

Specify the color of the AD/LDAP login button border for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

AD/LDAP login button text color

Specify the color of the AD/LDAP login button text for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

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.

Link metadata timeout

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.

Email batching buffer size

Specify the maximum number of notifications batched into a single email.

Note

• We recommend increasing the buffer size from the default value if you see the following error in the Mattermost logs: Email batching job's receiving buffer was full. Please increase the EmailBatchingBufferSize. Falling back to sending immediate mail. Increasing this value will ensure emails are queued up, without impacting server performance.

• Notifications will be sent instantly if the queue of emails exceeds the email batching interval configured.

This feature’s config.json setting is EmailBatchingBufferSize: 256`` with numerical input.

Email batching interval

Specify the maximum frequency, in seconds, which the batching job checks for new notifications.

Note

• We recommend decreasing the email batching interval from the default value if you see the following error in the Mattermost logs: Email batching job's receiving buffer was full. Please increase the EmailBatchingBufferSize. Falling back to sending immediate mail..

• Longer batching intervals may increase performance.

• Notifications will be sent instantly if the queue of emails exceeds the email batching interval configured.

This feature’s config.json setting is EmailBatchingInterval": 30 with numerical input.

Email login button color

Specify the color of the email login button for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

Email login button border color

Specify the color of the email login button border for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

Email login button text color

Specify the color of the email login button text for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

Enable account deactivation

True: Ability for users to deactivate their own account from Settings > Advanced > Deactivate Account. If a user deactivates their own account, they will get an email notification confirming they were deactivated. Available only when authentication is set to use email/password. Not available when authentication uses SAML or AD/LDAP.

False: Ability for users to deactivate their own account is disabled.

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

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 channel viewed websocket messages

This setting determines whether channel_viewed WebSocket events are sent, which synchronize unread notifications across clients and devices.

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

Note

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

• Reduced Database Load: When channel_viewed events are disabled, the server no longer needs to log these events in the database. This reduces the number of write and update operations, which can be substantial in a busy server with many users frequently switching channels.

• Decreased Network Traffic: Disabling these events means there are fewer messages sent between the server and clients. This reduction in network traffic can lower latency and improve the overall responsiveness of the server, especially for users with slower connections.

• Lower Server CPU Usage: Processing channel_viewed events requires CPU resources to handle database transactions and network communication. Without these events, the server’s CPU can be utilized more efficiently for other tasks, improving the overall performance.

• Improved User Experience: With reduced server load and network traffic, users may experience faster loading times and a more fluid interaction with the application.

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

Enable 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 hardened mode

True: Enables a hardened mode for Mattermost that makes user experience trade-offs in the interest of security.

False: Disables hardened mode.

Changes made when hardened mode is enabled:

• Failed login returns a generic error message instead of a specific message for username and password.

• If multi-factor authentication (MFA) is enabled, the route to check if a user has MFA enabled always returns true. This causes the MFA input screen to appear even if the user does not have MFA enabled. The user may enter any value to pass the screen. Note that hardened mode does not affect user experience when MFA is enforced.

• Password reset does not inform the user that they can not reset their SSO account through Mattermost and instead claims to have sent the password reset email.

• Mattermost sanitizes all 500 errors before returned to the client. Use the supplied request_id to match user facing errors with the server logs.

• Standard users authenticated via username and password can’t use post props reserved for integrations, such as override_username or override_icon_url.

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

Enable theme selection

True: Enables the Display > Theme tab in Settings so users can select their theme.

False: Users cannot select a different theme. The Display > Theme tab is hidden in Settings.

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

Allow custom themes

True: Enables the Display > Theme > Custom Theme section in Settings.

False: Users cannot use a custom theme. The Display > Theme > Custom Theme section is hidden in Settings.

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

Default theme

Set a default theme that applies to all new users on the system.

This feature’s config.json setting is "DefaultTheme": "default" with options "default", "organization", "mattermostDark", and "windows10".

Enable tutorial

True: Users are prompted with a tutorial when they open Mattermost for the first time after account creation.

False: The tutorial is disabled. Users are placed in Town Square when they open Mattermost for the first time after account creation.

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

Enable onboarding flow

True: New Mattermost users are shown key tasks to complete as part of initial onboarding.

False: User onboarding tasks are disabled. Users are placed in Town Square when they open Mattermost for the first time after account creation.

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

Enable user typing messages

This setting determines whether “user is typing…” messages are displayed below the message box when using Mattermost in a web browser or the desktop app.

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

Note

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

• Reduced Server Load: Typing events generate additional websocket traffic. Disabling them can reduce the amount of data that needs to be handled by the server, improving the overall response time and decreasing server load.

• Lower Network Traffic: When typing events are enabled, every keystroke generates a network event. This can lead to a significant amount of network traffic, particularly in busy channels. Disabling these events reduces the amount of information transmitted over the network.

• Client Performance: On the client side, processing typing events requires resources. By not having to handle these events, the client can be more responsive and use less memory and CPU.

User typing timeout

This setting defines how frequently “user is typing…” messages are updated, measured in milliseconds.

This feature’s config.json setting is "TimeBetweenUserTypingUpdatesMilliseconds": 5000 with numerical input.

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.

Note

Decrease this configuration setting value to increase how often Mattermost checks for and retrieves updated user profile datails. Reducing this value can be particularly helpful to reduce the likelyhood of usernames being displayed in channels as Someone due to outdated or missing data.

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.

SAML login button color

Specify the color of the SAML login button for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

SAML login button border color

Specify the color of the SAML login button border for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

SAML login button text color

Specify the color of the SAML login button text for white labeling purposes. Use a hex code with a #-sign before the code. This setting only applies to the mobile app.

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

Use channel name in email notifications

True: Channel and team name appears in email notification subject lines. Useful for servers using only one team.

False: Only team name appears in email notification subject line.

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

User status away timeout

This setting defines the number of seconds after which the user’s status indicator changes to “Away”, when they are away from Mattermost.

This feature’s config.json setting is "UserStatusAwayTimeout": 300 with numerical 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.

Disable app bar

This setting disables the app bar (channel header) in the Mattermost web and desktop app.

True: The app bar is hidden, providing a more streamlined interface with additional screen space for messages.

False: (Default) The app bar is displayed at the top of the channel, showing channel information, favorite status, and action buttons.

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

View archived channels

This setting controls the default behavior for viewing archived channels.

default_on: Users can view archived channels by default. Users can change this in Settings > Advanced > View Archived Channels.

default_off: (Default) Users cannot view archived channels by default. Users can enable this in Settings > Advanced > View Archived Channels.

---

Experimental audit logging configuration settings

Enable the following settings to output audit events in the System Console by going to Compliance > Audit Logging, or in the config.json file.

Note

The ability to enable and configure audit logging is currently in Beta.

Advanced logging

Available on Entry, Enterprise, and Enterprise Advanced plans (not available on Professional)

Output log and audit records to any combination of console, local file, syslog, and TCP socket targets for a Mattermost Cloud deployment. See the advanced logging documentation for details about logging options.

Enable audit logging

Available on Enterprise and Enterprise Advanced plans

When audit logging is enabled in a self-hosted instance, you can specify size, backup interval, compression, maximium age to manage file rotation, and timestamps for audit logging, as defined below. You can specify these settings independently for audit events and AD/LDAP events.

True: Audit logging files are enabled, and audit files are written locally to a file for a self-hosted deployment.

False: Audit logging files aren’t enabled, and audit logs aren’t written locally to a file for a self-hosted deployment.

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

File name

Available on Enterprise and Enterprise Advanced plans

Specify the path to the audit file for a self-hosted deployment.

This feature’s config.json setting is ".ExperimentalAuditSettings.FileName": "" with string input consisting of a user-defined path (e.g. /var/log/mattermost_audit.log).

Max file size

Available on Enterprise and Enterprise Advanced plans

This is the maximum size, in megabytes, that the file can grow before triggering rotation for a self-hosted deployment. The default setting is 100.

This feature’s config.json setting is ".ExperimentalAuditSettings.FileMaxSizeMB": 100 with numerical input.

Max file age

Available on Enterprise and Enterprise Advanced plans

This is the maximum age, in days, a file can reach before triggering rotation for a self-hosted deployment. The default value is 0, indicating no limit on the age.

This feature’s config.json setting is ".ExperimentalAuditSettings.FileMaxAgeDays": 0 with numerical input.

Maximum file backups

Available on Enterprise and Enterprise Advanced plans

This is the maximum number of rotated files kept for a self-hosted deployment. The oldest is deleted first. The default value is 0, indicating no limit on the number of backups.

This feature’s config.json setting is ".ExperimentalAuditSettings.FileMaxBackups": 0 with numerical input.

File compression

Available on Enterprise and Enterprise Advanced plans

When true, rotated files are compressed using gzip in a self-hosted deployment.

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

Maximum file queue

Available on Enterprise and Enterprise Advanced plans

This setting determines how many audit records can be queued/buffered at any point in time when writing to a file for a self-hosted deployment. The default is 1000 records. This setting can be left as default unless you are seeing audit write failures in the server log and need to adjust the number accordingly.

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

Certificate

Cloud Enterprise customers can upload and manage a certificate for audit logging encryption on Syslog or TCP logging targets. The ability to upload a certificate is only available when the feature flag ExperimentalAuditSettingsSystemConsoleUI is enabled.

Upload the certificate PEM file in the System Console by going to System Console > Audit Log Settings > Certificate and selecting File/Remove Certificate. The certificate file can be stored in the filestore or stored locally on the filesystem.

Experimental config.json-only configuration settings

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

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.

Enable client-side certification

Available on Enterprise and Enterprise Advanced plans

Important

Certificate-based authentication has been deprecated from Mattermost v11.0. This setting must be set to false to start the server from v11. Setting this to true will prevent the server from starting.

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

Available on Enterprise and Enterprise Advanced plans

Important

Certificate-based authentication has been deprecated from Mattermost v11.0. This setting is no longer functional from Mattermost v11.0 and should be left at the default value.

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

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.

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.

Note

Even if town-square isn’t listed, every user is added to that channels automatically when joining a new team.

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

---